Implementation:Openai Openai agents python Usage Tracking Pattern

Knowledge Sources	Openai_Openai_agents_python
Domains	Observability, Token Usage, Cost Management
Last Updated	2026-02-11 00:00 GMT

Overview

Demonstrates inspecting token usage statistics after an agent run via result.context_wrapper.usage, which returns a Usage object containing input tokens, output tokens, total tokens, request count, and per-request breakdowns.

Description

The Usage Tracking pattern provides visibility into the token consumption of agent runs, which is essential for cost monitoring, quota management, and performance optimization. After a run completes, the Usage object aggregates all token usage across the entire agent execution, including any intermediate tool calls that triggered additional model requests.

The example creates an agent with a get_weather function tool and runs a query that triggers tool use ("What's the weather in Tokyo?"). After the run completes, it accesses result.context_wrapper.usage to retrieve the aggregated Usage object. The Usage class provides top-level summaries (input_tokens, output_tokens, total_tokens, requests) as well as a request_usage_entries list that breaks down token consumption per individual API request, enabling detailed cost attribution.

This pattern is particularly valuable when agents use tools, since a single Runner.run() call may result in multiple API requests (one to decide to call the tool, another to process the tool result). The per-request breakdown in request_usage_entries makes it possible to understand exactly where tokens are being consumed.

Usage

Use this pattern when you need to monitor API costs, implement usage-based billing, enforce token budgets, log consumption metrics, or debug unexpectedly high token usage in agent workflows that involve tool calls or multi-step reasoning.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: examples/basic/usage_tracking.py
• Lines: 1-47

Signature

usage: Usage = result.context_wrapper.usage

# Usage object attributes:
usage.input_tokens    # int - total input tokens across all requests
usage.output_tokens   # int - total output tokens across all requests
usage.total_tokens    # int - sum of input and output tokens
usage.requests        # int - number of API requests made
usage.request_usage_entries  # list - per-request token breakdowns

Import

from agents import Agent, Runner, Usage, function_tool

I/O Contract

Inputs

Name	Type	Required	Description
agent	Agent	Yes	The agent instance to run, optionally configured with tools
input	str	Yes	The user message that triggers the agent run

Outputs

Name	Type	Description
result.context_wrapper.usage	Usage	Aggregated token usage statistics for the entire run
usage.input_tokens	int	Total number of input tokens consumed
usage.output_tokens	int	Total number of output tokens generated
usage.total_tokens	int	Sum of input and output tokens
usage.requests	int	Number of API requests made during the run
usage.request_usage_entries	list	Per-request breakdown with individual input_tokens and output_tokens

Usage Examples

Tracking Token Usage with a Tool-Enabled Agent

import asyncio
from pydantic import BaseModel
from agents import Agent, Runner, Usage, function_tool

class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
def get_weather(city: str) -> Weather:
    """Get the current weather information for a specified city."""
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

def print_usage(usage: Usage) -> None:
    print(f"Input tokens: {usage.input_tokens}")
    print(f"Output tokens: {usage.output_tokens}")
    print(f"Total tokens: {usage.total_tokens}")
    print(f"Requests: {usage.requests}")
    for i, request in enumerate(usage.request_usage_entries):
        print(f"  {i + 1}: {request.input_tokens} input, {request.output_tokens} output")

async def main() -> None:
    agent = Agent(
        name="Usage Demo",
        instructions="You are a concise assistant. Use tools if needed.",
        tools=[get_weather],
    )
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    print(result.final_output)
    print_usage(result.context_wrapper.usage)

asyncio.run(main())

Related Pages

• Environment:Openai_Openai_agents_python_OpenAI_API_Credentials