Why cost attribution matters
When agents make LLM calls, every token has a price. In multi-agent systems where one agent can spawn or delegate to others, costs accumulate across multiple providers and chains. Without proper attribution you cannot answer basic questions: which agent is responsible for a $200 spike? Which tool is burning the most budget? Did the delegation chain for last night’s job exceed its allocation? Cost attribution gives you per-agent, per-tool, and per-delegation-chain cost records. Alert callbacks and a budget check read the same cost records, so you can react to spend as it is recorded. The module reports and alerts; it does not block anything by itself.Setup
Configuration options
Currency code stored on each cost record. It is a label only, no conversion happens, and the input field is still named
costUsd.Amounts for 24-hour rolling spend that trigger alerts. Only used when
onAlert is also set.Called from
recordCost() when 24-hour spend is at or above a threshold, or when monthly spend has reached a budget policy limit.Recording costs
CallrecordCost() after each LLM response or API call. Pass the raw token counts and the exact dollar amount from the provider’s response.
RecordCostInput
Provider and model identifier, e.g. ‘openai:gpt-4o’, ‘anthropic:claude-3-5-sonnet’, ‘mcp:github’.
Any additional data to store alongside this event (request IDs, model version, etc.).
Costs are stored internally as integer microdollars (value × 1,000,000) to avoid floating-point drift across aggregations.
Provider helpers
- Tab Title
- Tab Title
- Tab Title
Generating cost reports
Per-agent report
CostReport
Cost breakdown per tool, sorted by cost descending.
Owner report
Aggregate cost across all agents owned by a user:Top agents by cost
Find the most expensive agents in any period:Delegation chain report
getDelegationChainCost(chainId) returns all events recorded with that delegationChainId, regardless of date. The returned report uses the chain ID in its agentId field and a default 30-day period value that does not filter the events. When agents delegate to sub-agents, you can attribute all costs back to the originating chain by passing delegationChainId in recordCost():
Setting up alerts
Alerts are evaluated insiderecordCost() and only when onAlert is set. There are three alert types:
Alerts are level-triggered, not edge-triggered: every
recordCost() call made while spend is above a threshold fires the alert again, so deduplicate in onAlert if you notify humans. Budget alerts need onAlert but not alertThresholds. A failed recordCost() returns an error result; an onAlert that throws is caught and also returns RECORD_COST_FAILED (the cost row is already written).
CostAlert
Integration with budget policies
checkBudget() reads budget policies created via theauth.policies and compares them against calendar-month spend from the cost events table. It only considers policies whose agentId equals the agent (user-wide or tenant-wide policies are ignored), and only the maxTokensCostPerMonth limit; the daily and call-count limits and the policy action are not used. It reports; enforcing the result is up to your code. theauth.authorize() does not call it.
maxTokensCostPerMonth:
budget_exceeded alert fires from recordCost() once spend has reached this limit (withinBudget is false when spend is equal to or above the limit). The action: 'block' value is stored on the policy but nothing in the cost module acts on it, so revoke or block the agent yourself in onAlert.
Maintenance
Cost events accumulate. Runcleanup() periodically to remove events older than the retention window:
retentionDays on the module, you can call cleanup() with no arguments and it uses that value.
Return types
All methods return aResult<T> union:
result.success before accessing result.data. Error codes:
Related
Budget policies
Create the policies that
checkBudget() reads. Policies are not enforced by authorize().Audit trail
The authorization log. Cost events are stored separately, in their own table.
Trust scoring
Trust levels you can combine with spend data in your own logic.
Rate limiting
Hard call-count caps per agent, per resource, per hour.