Repository navigation
V1 Usage and Cost en
简体中文 | English
Applies to v1.0.0. Usage here means reported model tokens, run metrics, and execution budgets, not an account balance or a provider invoice.
| What you want to know | Where to read it |
|---|---|
| Tokens reported for one native Agent run | Non-streaming RunResult.usage
|
| Model requests, tool calls, latency, and estimated cost |
summarize_trace() / agent.summarize_trace()
|
| Counts returned by the Codex CLI |
RunResult.usage or agent.last_backend_result.usage
|
| Used or reserved budget for a reconnectable task | ExecutionHandle.budget() |
Use the agent configured in Getting Started. result_format="object" returns a RunResult; trace=True also records events for diagnostics and aggregation:
from LightAgent import summarize_trace
result = agent.run("Give a one-sentence summary.", result_format="object", trace=True)
if result.error:
print("Run error:", result.error)
if result.usage:
print("Reported usage:", result.usage)
# Illustrative USD rates per million tokens, not provider prices.
summary = summarize_trace(
result.trace, usage=result.usage,
pricing={"input_per_million": 1.0, "output_per_million": 5.0},
)
print("Estimated USD:", summary.estimated_cost_usd)
else:
print("Usage not reported; cost is unknown.")The native path accumulates usage from recorded model requests: prompt_tokens is input, completion_tokens is output, and total_tokens is the total. The summary also accepts input_tokens and output_tokens. A run can send multiple model requests, for example when generation resumes after a tool result. Do not add a run total to that same run's per-request totals.
The estimate is (input tokens × input rate + output tokens × output rate) / 1_000_000. The application supplies rates in USD per million tokens. LightAgent does not look up prices or separately apply cache discounts, tool charges, or model-specific rates. When mixing models, price each model's usage before summing. Reconcile against provider records.
This example calls no model and needs no API key:
from LightAgent import summarize_trace
events = [
{"type": "model_request", "data": {"usage": {"input_tokens": 100, "output_tokens": 25}}},
{"type": "model_request", "data": {"usage": {"prompt_tokens": 60, "completion_tokens": 15}}},
]
summary = summarize_trace(events, pricing={"input_per_million": 1.0, "output_per_million": 5.0})
assert summary.usage == {"prompt_tokens": 160, "completion_tokens": 40, "total_tokens": 200}
assert summary.model_request_count == 2
assert summary.estimated_cost_usd == 0.00036
print(summary.to_dict())TraceSummary also includes latency, error, retry, tool, and approval metrics. agent.summarize_trace() uses the most recent run. For historical accounting, save each result.trace and result.usage and deduplicate by trace ID. LightEvaluator(pricing=...) aggregates estimates across evaluation cases. Do not treat an estimate as total cost unless you know how much usage was reported. See Safety, Observability, and Evaluation.
-
Missing does not mean zero. Empty
RunResult.usagemeans no usable counts were reported. The accumulated total can be incomplete if some requests omit usage. Trace summaries can still show zero tokens or a zero estimate when usage is absent. Record "not reported" separately. -
Streaming usage is not guaranteed. Consume the iterator before reading
agent.summarize_trace(). Usage depends on the provider sending counts and the v1.0.0 streaming path receiving them. Do not rely on a dedicatedusagestream event. Prefer non-streaming for more consistent capture, and reconcile against provider records. -
Codex returns raw backend usage. When the CLI reports counts in the terminal event, the backend result includes them. Typical fields are
input_tokens,output_tokens, andcached_input_tokens. They are not your account quota or bill; do not add cached tokens to input totals again. External backends do not supportstream=True; see Codex.
Use the handle from the durable execution example:
budget = handle.budget()
print("Used:", budget["used"])
print("Reserved:", budget["reserved"])
print("Unknown:", budget["unknown"])used is recorded consumption; reserved is capacity held pending settlement; unknown counts unreconciled usage entries by dimension, not tokens. backend_calls and seconds measure execution. Token and cost reporting or hard limits depend on the backend. Reconcile unknown outcomes before settlement rather than counting them as zero or blindly replaying work.
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing