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

# Reasoning

> Configure extended thinking per provider via WithLLMSampling and LLMReasoning

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.

<Note>
  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.
</Note>

Configure it per agent with [`WithLLMSampling`](/getting-started/configuration) and [`LLMReasoning`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/interfaces#LLMReasoning). Fields are **provider-agnostic** — each LLM client maps them to its native API.

## Configure

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

<Warning>
  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.
</Warning>

<Note>
  Anthropic extended thinking requires `BudgetTokens` ≥ 1024. The SDK clamps lower values to 1024 automatically.
</Note>

## 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](/getting-started/streaming) for event handling patterns.

## Token usage

Reasoning tokens appear in [`LLMUsage.ReasoningTokens`](/features/token-usage) when the provider reports them. They are included in the aggregate on `AgentRunResult.LLMUsage`.

## Example

<CardGroup cols={2}>
  <Card title="Reasoning" icon="play" href="/examples/reasoning" horizontal>
    Extended thinking on supported models
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="LLM Providers" icon="robot" href="/getting-started/llm-providers" horizontal>
    Provider clients and model selection
  </Card>

  <Card title="Streaming" icon="wave-pulse" href="/getting-started/streaming" horizontal>
    Reasoning stream events
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.