09d2ef1a37
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1.5 KiB
1.5 KiB
title, summary
| title | summary |
|---|---|
| Cost Reporting | 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