Token Usage

Each LLM completion can report token counts via interfaces.LLMUsage on LLMResponse.Usage. OpenAI, Anthropic, and Gemini clients populate the fields when the provider returns them. An agent run can involve multiple LLM calls — the initial generation, then one more per tool round as the model processes tool results and decides next steps. AgentRunResult.LLMUsage is the sum across all rounds, giving you a single number for the full cost of a run.

Usage fields

Field	Description
`PromptTokens`	Input tokens
`CompletionTokens`	Output tokens
`TotalTokens`	Sum when reported by provider
`CachedPromptTokens`	Prompt cache hits (when supported)
`ReasoningTokens`	Extended thinking tokens (when supported)

CachedPromptTokens is populated by OpenAI automatically (server-side caching, no client option needed) and by Anthropic only when llm.WithPromptCaching(true) is set — it’s 0 for Anthropic otherwise, since caching is disabled by default there.

Run

AgentRunResult.LLMUsage is the sum across all LLM calls in that run — including tool rounds. Use it for cost estimates, quotas, and logging:

agentRun, err := a.Run(ctx, prompt, nil)
if err != nil {
    return err
}
result, err := agentRun.Get(ctx)
if err != nil {
    return err
}

if result.LLMUsage != nil {
    fmt.Printf("prompt=%d completion=%d total=%d\n",
        result.LLMUsage.PromptTokens,
        result.LLMUsage.CompletionTokens,
        result.LLMUsage.TotalTokens,
    )
}

Stream

The same aggregate appears on LLMUsage in the AgentEventTypeRunFinished event — Result is an *AgentRunResult:

for ev := range eventCh {
    if ev.Type() != agent.AgentEventTypeRunFinished {
        continue
    }
    finished, ok := ev.(*agent.AgentRunFinishedEvent)
    if !ok || finished.Result == nil || finished.Result.LLMUsage == nil {
        continue
    }
    u := finished.Result.LLMUsage
    fmt.Printf("total tokens: %d\n", u.TotalTokens)
}

OpenAI streaming with include_usage surfaces totals on RUN_FINISHED. Example: Stream.

Budget enforcement

To automatically stop or pause a run when a token or cost limit is reached, use WithBudget. It works across all runtimes and covers sub-agent usage transparently without any hook code.

Per-request usage

For per-LLM-call breakdowns — to log each round individually, build cost dashboards, or track iteration-level usage — use AfterLLMHook and inspect in.Response.Usage on each iteration:

agent.WithHooks("cost", agent.AgentHooks{
    AfterLLM: []agent.AfterLLMHook{
        func(ctx context.Context, in agent.AfterLLMHookInput) (agent.AfterLLMHookOutput, error) {
            if in.Response.Usage != nil {
                log.Printf("iter=%d tokens=%d", in.RunMeta.Iteration, in.Response.Usage.TotalTokens)
            }
            return agent.AfterLLMHookOutput{Response: in.Response}, nil
        },
    },
})

Example

Simple Agent

SHOW_LLM_USAGE footer

Budget

Token and cost limits with automatic enforcement

Reasoning

ReasoningTokens from extended thinking

Streaming

Usage on RUN_FINISHED events

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Usage fields

Run

Stream

Budget enforcement

Per-request usage

Example

Simple Agent

Budget

Reasoning

Streaming

​Usage fields

​Run

​Stream

​Budget enforcement

​Per-request usage

​Example

Simple Agent

​Related

Budget

Reasoning

Streaming

Usage fields

Run

Stream

Budget enforcement

Per-request usage

Example

Related