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

A class to be used on spawning an agent or decorating an agentic function to control the **maximum number of output tokens generated by the underlying model**.

```typescript theme={null}
export class MaxTokens {
    constructor(
        public perInvocation: number | null = null,
        public perRound: number | null = null,
        public rounds: number | null = null
    ) {}

    static from({
        perInvocation,
        perRound,
        rounds,
    }: {
        perInvocation?: number | null;
        perRound?: number | null;
        rounds?: number | null;
    }): MaxTokens;
}
```

#### `MaxTokens.from()`

A static factory method that creates a `MaxTokens` instance from a configuration object with named parameters.

```typescript theme={null}
const maxTokens = MaxTokens.from({ perInvocation: 5000, perRound: 1000, rounds: 5 });
```

**Parameters**

<ParamField body="per_invocation" type="int | null">
  The maximum number of output tokens generated over all rounds of inference in a single invocation.

  Defaults to `null` meaning unlimited.
</ParamField>

<ParamField body="per_round" type="int | null">
  The maximum number of output tokens generated in a single round of inference in a single invocation.

  Defaults to `null` meaning unlimited.
</ParamField>

<ParamField body="rounds" type="int | null">
  The maximum number of rounds of inference in a single invocation.

  Defaults to `null` meaning unlimited.
</ParamField>

### `Usage`

A class outlining the token usage of the underlying model of an agent or agentic function.

```ts wrap theme={null}
export class Usage {
    /**
     * Note: `totalTokens` is not always equal to `inputTokens + outputTokens`.
     * It represents the total tokens involved within the timeframe.
     */
    constructor(
        public readonly inputTokens: number,
        public readonly outputTokens: number,
        public readonly totalTokens: number,
        public readonly cachedTokens: number = 0,
        public readonly reasoningTokens: number = 0
    ) {}
}
```

**Parameters**

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

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

<ParamField body="totalTokens" type="number">
  The total number of tokens *processed*, not double-counting generated then re-consumed tokens.
</ParamField>

<ParamField body="cachedTokens" type="number">
  The number of input tokens that were served from cache. Defaults to `0`.
</ParamField>

<ParamField body="reasoningTokens" type="number">
  The number of tokens used for internal reasoning / chain-of-thought. Defaults to `0`.
</ParamField>