Free field guide · prompt-free evidence
Attribute agent cost before you try to cap it.
A budget limit cannot repair a ledger that cannot identify the run, agent, attempt, retry, or fan-out path that spent the money. Capture these eight evidence gates first.
Operational information only · No prompts or production access required · Missing evidence stays unknown
- workflow_key
- the bounded process being measured
- run_key
- one invocation of that workflow
- agent_key
- the stable agent or role that acted
- attempt_no
- the first pass, retry, or repair attempt
rule identity → outcome → usage → cost
Eight evidence gates
Every cost needs an owner and an outcome.
Passing all eight gates does not prove efficiency. It creates the evidence needed to compare cost and reliability without guessing which agent, retry, or missing field produced the result.
Bound one workflow
Name the process, its start and end, and the decision the measurement must support.
Assign stable identities
Use pseudonymous workflow, run, task, agent, and attempt keys that survive log joins.
Record every attempt
Preserve first passes, retries, repairs, and refusals instead of collapsing them into one task row.
Separate usage, billing, and money
Store tokens, billing basis, and observed cost independently; never treat subscription-covered usage as metered spend—or missing spend as zero.
Expose fan-out
Capture parent attempt, recursion depth, and concurrent spawn count before enforcing a fan-out bound.
Use closed outcomes
Define completed, failed, refused, cancelled, and unknown so dashboards do not invent success.
Publish evidence coverage
Report the share of attempts with known usage, cost, outcome, and latency beside every aggregate.
Compare cost with reliability
Read cost per completed task beside first-pass completion, retries, failures, and latency.
Minimum normalized ledger
Keep the raw row narrow and explicit.
This is a field map, not a universal schema. Values may be pseudonymous. Prompts, responses, tool payloads, direct identifiers, credentials, and customer data do not belong in the cost-attribution row.
| Field | Purpose | Truth rule |
|---|---|---|
workflow_key, run_key | Bound the measured process and invocation. | Stable and pseudonymous. |
task_key, agent_key | Attribute work to one task and one agent or role. | No display name required. |
attempt_no, parent_attempt_key | Separate retries and reconstruct fan-out. | Never overwrite an earlier attempt. |
provider, model | Identify the pricing and runtime context. | Pin the version when known. |
billing_basis, billing_period_key | Distinguish metered API usage, subscription-covered usage, credits, and other declared bases. | Do not convert a flat plan into per-run cash spend without an explicit allocation rule. |
input_tokens, output_tokens | Preserve supplied usage evidence. | Missing is null, not zero. |
observed_cost, allocated_cost, currency | Keep provider-reported money separate from any documented internal allocation. | Label estimates and allocations; neither substitutes for an invoice. |
outcome, latency_ms | Compare spend with completion and speed. | Use a closed outcome vocabulary. |
started_at, completed_at | Support bounded windows and concurrency checks. | Use one documented timezone. |
Evidence boundaries
A cost ledger supports decisions. It does not prove causality.
It can support
- Observed cost by workflow, run, task, agent, and attempt
- Known retry and fan-out cost
- Cost per supplied completion outcome
- Coverage gaps and lower-bound reporting
- Priorities for the next instrumentation change
It cannot prove
- That one agent caused a business outcome
- That an estimate matches a provider invoice
- That missing usage or cost was zero
- That a budget cap is race-safe under concurrency
- Any guaranteed savings or reliability improvement
One workflow, one decision
Need a measured baseline before the implementation work?
The WrightOps AI Agent Cost & Reliability Snapshot turns up to 50 prompt-free normalized attempts into deterministic aggregate JSON and Markdown, evidence gaps, and up to five human-reviewed priorities.
Three business days after accepted inputs and provider-confirmed settled payment. No implementation, production access, or outcome guarantee.