Principle:Openai Openai agents python Usage Tracking
| Knowledge Sources | |
|---|---|
| Domains | Observability, Cost_Management |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for tracking and inspecting cumulative token usage and request counts across an agent run.
Description
Usage Tracking provides a structured way to monitor the computational cost of agent runs. The SDK automatically accumulates token counts and request counts in a `Usage` object accessible via the run context. This includes `input_tokens`, `output_tokens`, `total_tokens`, `requests` (count), and per-request breakdowns in `request_usage_entries`.
The `Usage` object is available on the `RunContextWrapper` which is accessible from `result.context_wrapper.usage` after a run completes, or from within lifecycle hooks during execution. Each LLM call updates the cumulative counters, allowing real-time monitoring of cost during multi-turn or multi-agent runs.
This mechanism enables cost tracking, budget enforcement, usage analytics, and billing attribution without requiring external instrumentation. The per-request entries allow detailed analysis of which turns consumed the most tokens.
Usage
Use this principle when you need to monitor API costs, enforce token budgets, or analyze the efficiency of agent runs. Access `result.context_wrapper.usage` after a run to inspect totals, or use lifecycle hooks (`on_llm_end`) to monitor usage in real-time during execution.
Theoretical Basis
Usage Tracking implements an accumulator pattern applied to LLM API cost metrics:
Pseudo-code Logic:
# Abstract usage accumulation
usage = Usage()
for each llm_call in run:
response = call_model(...)
usage.input_tokens += response.usage.input_tokens
usage.output_tokens += response.usage.output_tokens
usage.total_tokens += response.usage.total_tokens
usage.requests += 1
usage.request_usage_entries.append(response.usage)
# Available at: result.context_wrapper.usage