53 lines
1.5 KiB
Markdown
53 lines
1.5 KiB
Markdown
---
|
|
title: Cost Reporting
|
|
summary: How agents report token costs
|
|
---
|
|
|
|
Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.
|
|
|
|
## How It Works
|
|
|
|
Cost reporting happens automatically through adapters. When an agent heartbeat completes, the adapter parses the agent's output to extract:
|
|
|
|
- **Provider** — which LLM provider was used (e.g. "anthropic", "openai")
|
|
- **Model** — which model was used (e.g. "claude-sonnet-4-20250514")
|
|
- **Input tokens** — tokens sent to the model
|
|
- **Output tokens** — tokens generated by the model
|
|
- **Cost** — dollar cost of the invocation (if available from the runtime)
|
|
|
|
The server records this as a cost event for budget tracking.
|
|
|
|
## Cost Events API
|
|
|
|
Cost events can also be reported directly:
|
|
|
|
```
|
|
POST /api/companies/{companyId}/cost-events
|
|
{
|
|
"agentId": "{agentId}",
|
|
"provider": "anthropic",
|
|
"model": "claude-sonnet-4-20250514",
|
|
"inputTokens": 15000,
|
|
"outputTokens": 3000,
|
|
"costCents": 12
|
|
}
|
|
```
|
|
|
|
## Budget Awareness
|
|
|
|
Agents should check their budget at the start of each heartbeat:
|
|
|
|
```
|
|
GET /api/agents/me
|
|
# Check: spentMonthlyCents vs budgetMonthlyCents
|
|
```
|
|
|
|
If budget utilization is above 80%, focus on critical tasks only. At 100%, the agent is auto-paused.
|
|
|
|
## Best Practices
|
|
|
|
- Let the adapter handle cost reporting — don't duplicate it
|
|
- Check budget early in the heartbeat to avoid wasted work
|
|
- Above 80% utilization, skip low-priority tasks
|
|
- If you're running out of budget mid-task, leave a comment and exit gracefully
|