Reasoning

Reasoning (extended thinking) lets supported models spend additional compute on hidden scratch-pad reasoning before producing a final answer. The model works through the problem internally — planning, considering alternatives, checking its work — before writing the visible response. This typically improves accuracy on multi-step problems, logical reasoning, and complex coding tasks. The internal reasoning is not surfaced in result.Content. When streaming, you can observe thinking deltas via AgentEventTypeReasoningMessageContent events if you want to display the reasoning process to users.

Reasoning tokens incur additional cost on top of normal output tokens. Use BudgetTokens to cap how much thinking the model does per call, and check result.LLMUsage.ReasoningTokens to track spend.

Configure it per agent with WithLLMSampling and LLMReasoning. Fields are provider-agnostic — each LLM client maps them to its native API.

Configure

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithLLMSampling(&agent.LLMSampling{
        Reasoning: &interfaces.LLMReasoning{
            Enabled:      true,
            Effort:       "medium",  // OpenAI reasoning_effort; Gemini thinking level
            BudgetTokens: 4096,      // Anthropic / Gemini thinking budget
        },
    }),
)

Field mapping

Field	OpenAI	Anthropic	Gemini
`Enabled`	Does not infer `reasoning_effort` alone — standard chat models reject that parameter	If `BudgetTokens` is 0, uses minimum 1024 tokens for extended thinking	Helps turn on thought output (`IncludeThoughts`)
`Effort`	Maps to `reasoning_effort` when non-empty — use with reasoning-capable models only	Not used for the thinking API	Maps to `ThinkingLevel` (`low` / `medium` / `high` / `minimal`) — only when `BudgetTokens` is 0
`BudgetTokens`	Not used	Extended-thinking budget (≥1024 when non-zero; values below 1024 are clamped up)	Maps to `ThinkingBudget` — wins over `Effort` when set

Gemini forbids setting both BudgetTokens and Effort (ThinkingLevel) together. If you set BudgetTokens, Effort is not sent as ThinkingLevel. Prefer BudgetTokens over Effort when targeting Gemini.

Anthropic extended thinking requires BudgetTokens ≥ 1024. The SDK clamps lower values to 1024 automatically.

Streaming

When the provider returns thinking deltas, streaming emits reasoning events:

Event	When
`AgentEventTypeReasoningStart`	Reasoning block begins
`AgentEventTypeReasoningMessageContent`	Partial thinking delta — Anthropic emits this as `ThinkingDelta`
`AgentEventTypeReasoningEnd`	Reasoning block ends

See Streaming for event handling patterns.

Token usage

Reasoning tokens appear in LLMUsage.ReasoningTokens when the provider reports them. They are included in the aggregate on AgentRunResult.LLMUsage.

Example

Extended thinking on supported models

LLM Providers

Provider clients and model selection

Streaming

Reasoning stream events

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Reasoning

Configure

Field mapping

Streaming

Token usage

Example

Reasoning

LLM Providers

Streaming

​Configure

​Field mapping

​Streaming

​Token usage

​Example

Reasoning

​Related

LLM Providers

Streaming

Configure

Field mapping

Streaming

Token usage

Example

Related