> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symbolica.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Usage

### `MaxTokens`

{/* START */}

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

{/* @signature MaxTokens customer_sdk/python/src/agentica/common.py style=dataclass */}

```python theme={null}
@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**

{/* START */}

<ParamField body="per_invocation" type="int | None">
  The maximum number of output tokens generated over all rounds of inference in a single invocation.
  Defaults to None meaning unlimited.
</ParamField>

<ParamField body="per_round" type="int | None">
  The maximum number of output tokens generated in a single round of inference in a single invocation.
  Defaults to None meaning unlimited.
</ParamField>

<ParamField body="rounds" type="int | None">
  The maximum number of rounds of inference in a single invocation.
  Defaults to None meaning unlimited.
</ParamField>

### `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.

```python wrap theme={null}
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**

<ParamField body="input_tokens" type="int">
  The number of input tokens consumed by the model.
</ParamField>

<ParamField body="output_tokens" type="int">
  The number of output tokens generated by the model.
</ParamField>

<ParamField body="input_tokens_details.cached_tokens" type="int">
  The number of input tokens that were served from cache.
</ParamField>

<ParamField body="output_tokens_details.reasoning_tokens" type="int">
  The number of tokens used for internal reasoning / chain-of-thought.
</ParamField>

**Example**

```python theme={null}
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`

{/* START */}

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

{/* @signature total_usage customer_sdk/python/src/agentica/common.py wrap */}

```python wrap theme={null}
def total_usage(ag: Union['AgenticFunction', 'Agent', Callable[..., Any]]) -> 'ResponseUsage':
    ...
```

**Parameters**

{/* START */}

<ParamField body="ag" type="AgenticFunction | Agent | Callable[..., Any]">
  The agent, agentic function, or decorated callable to query.
</ParamField>

{/* @returns total_usage customer_sdk/python/src/agentica/common.py */}

<ResponseField name="Returns" type="ResponseUsage">
  The token usage across all invocations of the agent or agentic function.
</ResponseField>

### `last_usage`

{/* START */}

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

{/* @signature last_usage customer_sdk/python/src/agentica/common.py wrap */}

```python wrap theme={null}
def last_usage(ag: Union['AgenticFunction', 'Agent', Callable[..., Any]]) -> 'ResponseUsage':
    ...
```

**Parameters**

{/* START */}

<ParamField body="ag" type="AgenticFunction | Agent | Callable[..., Any]">
  The agent, agentic function, or decorated callable to query.
</ParamField>

{/* @returns last_usage customer_sdk/python/src/agentica/common.py */}

<ResponseField name="Returns" type="ResponseUsage">
  The token usage of the last invocation of the agent or agentic function.
</ResponseField>