Token Usage

`MaxTokens`

Control the maximum number of tokens an agent or agentic function can generate.

@dataclass(slots=True, frozen=True)
class MaxTokens:

    per_invocation: int | None = DEFAULT_AGENT_MAX_TOKENS_PER_INVOCATION
    per_round: int | None = DEFAULT_AGENT_MAX_TOKENS_PER_ROUND
    rounds: int | None = DEFAULT_AGENT_MAX_ROUNDS

Parameters

int | None

The maximum number of output tokens generated over all rounds of inference in a single invocation. Defaults to None meaning unlimited.

int | None

The maximum number of output tokens generated in a single round of inference in a single invocation. Defaults to None meaning unlimited.

int | None

The maximum number of rounds of inference in a single invocation. Defaults to None meaning unlimited.

`ResponseUsage`

Token usage statistics returned by all usage-reporting methods. This is ResponseUsage from openai.types.responses, which provides richer detail including cached and reasoning token breakdowns.

from openai.types.responses import ResponseUsage

class ResponseUsage:
    input_tokens: int
    output_tokens: int
    total_tokens: int
    input_tokens_details: InputTokensDetails   # .cached_tokens: int
    output_tokens_details: OutputTokensDetails  # .reasoning_tokens: int

Key Fields

int

The number of input tokens consumed by the model.

int

The number of output tokens generated by the model.

int

The number of input tokens that were served from cache.

int

The number of tokens used for internal reasoning / chain-of-thought.

Example

u = agent.last_usage()
print(f"Input tokens:     {u.input_tokens}")
print(f"Output tokens:    {u.output_tokens}")
print(f"Cached tokens:    {u.input_tokens_details.cached_tokens}")
print(f"Reasoning tokens: {u.output_tokens_details.reasoning_tokens}")

`total_usage`

Get the total token usage of an agent or agentic function across all invocations.

def total_usage(ag: Union['AgenticFunction', 'Agent', Callable[..., Any]]) -> 'ResponseUsage':
    ...

Parameters

AgenticFunction | Agent | Callable[..., Any]

The agent, agentic function, or decorated callable to query.

ResponseUsage

The token usage across all invocations of the agent or agentic function.

`last_usage`

Get the token usage of an agent or agentic function for the last invocation.

def last_usage(ag: Union['AgenticFunction', 'Agent', Callable[..., Any]]) -> 'ResponseUsage':
    ...

Parameters

AgenticFunction | Agent | Callable[..., Any]

The agent, agentic function, or decorated callable to query.

ResponseUsage

The token usage of the last invocation of the agent or agentic function.

Core

Logging

Prompting

`MaxTokens`

`ResponseUsage`

`total_usage`

`last_usage`

​MaxTokens

​ResponseUsage

​total_usage

​last_usage

`MaxTokens`

`ResponseUsage`

`total_usage`

`last_usage`