Skip to content

V1 Usage and Cost en

weego edited this page Nov 15, 2026 · 1 revision

Usage, Cost Estimates, and Budgets

简体中文 | 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()

Read tokens and estimated cost for one run

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.

Offline example: aggregate two model requests

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.

Streaming, Codex, and missing data

  • Missing does not mean zero. Empty RunResult.usage means 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 dedicated usage stream 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, and cached_input_tokens. They are not your account quota or bill; do not add cached tokens to input totals again. External backends do not support stream=True; see Codex.

Durable task budgets

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.

Clone this wiki locally