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

# Reasoning

> Enable extended thinking and reasoning capabilities for agents using OpenAI, Anthropic, Google, and Vertex AI models.

# Reasoning

Agentium supports **extended thinking** (reasoning) across all major model providers. When enabled, the model produces an internal chain-of-thought before generating the final answer — improving performance on complex math, logic, and multi-step problems.

***

## Quick Start

```typescript theme={null}
import { Agent, google } from "@agentium/core";

const agent = new Agent({
  name: "Thinker",
  model: google("gemini-2.5-flash"),
  instructions: "Solve problems step by step.",
  reasoning: {
    enabled: true,
    budgetTokens: 8000,
  },
  logLevel: "info",
});

const result = await agent.run("What is the 15th prime number?");
console.log(result.text);

if (result.thinking) {
  console.log("Reasoning:", result.thinking);
}

console.log("Reasoning tokens:", result.usage.reasoningTokens);
```

***

## Configuration

<ParamField path="reasoning.enabled" type="boolean" required>
  Enable or disable reasoning for this agent.
</ParamField>

<ParamField path="reasoning.effort" type="'low' | 'medium' | 'high'" required={false}>
  Reasoning effort level. **OpenAI only** — maps to `reasoning_effort` parameter. Default: `"medium"`.
</ParamField>

<ParamField path="reasoning.budgetTokens" type="number" required={false}>
  Maximum tokens allocated for the thinking phase. **Anthropic, Google, Vertex AI** — maps to `budget_tokens` / `thinkingBudget`. Default: `10000`.
</ParamField>

***

## Provider Support

Each provider maps `ReasoningConfig` to its native API:

| Provider      | API Parameter                   | Effort         | Budget               | Models                               |
| ------------- | ------------------------------- | -------------- | -------------------- | ------------------------------------ |
| **OpenAI**    | `reasoning_effort`              | `effort` field | N/A                  | `o1`, `o1-mini`, `o3-mini`           |
| **Anthropic** | `thinking.budget_tokens`        | N/A            | `budgetTokens` field | `claude-sonnet-4-20250514`           |
| **Google**    | `thinkingConfig.thinkingBudget` | N/A            | `budgetTokens` field | `gemini-2.5-flash`, `gemini-2.5-pro` |
| **Vertex AI** | `thinkingConfig.thinkingBudget` | N/A            | `budgetTokens` field | `gemini-2.5-flash`, `gemini-2.5-pro` |

<Note>
  When reasoning is enabled for OpenAI, `temperature` is ignored (the API does not allow both). For Anthropic, the `temperature` parameter is removed when thinking is active.
</Note>

***

## Output

When reasoning is enabled, `RunOutput` includes:

| Field                   | Type                  | Description                            |
| ----------------------- | --------------------- | -------------------------------------- |
| `thinking`              | `string \| undefined` | The model's internal chain-of-thought  |
| `usage.reasoningTokens` | `number \| undefined` | Tokens consumed by the reasoning phase |

### Streaming

During streaming, reasoning content is delivered as `thinking` chunks:

```typescript theme={null}
for await (const chunk of agent.stream("Solve this puzzle...")) {
  if (chunk.type === "thinking") {
    process.stdout.write(`[think] ${chunk.text}`);
  } else if (chunk.type === "text") {
    process.stdout.write(chunk.text);
  }
}
```

***

## ReasoningConfig Type

```typescript theme={null}
interface ReasoningConfig {
  enabled: boolean;
  effort?: "low" | "medium" | "high";
  budgetTokens?: number;
}
```

***

## Logging

When `logLevel` is `"info"` or higher, the agent logger displays:

* Thinking content (truncated, italic, dimmed)
* Reasoning token count with a brain icon in the usage summary

***

## Accessing Thinking Content

When reasoning is enabled, the model's internal thinking is available in `RunOutput.thinking`:

```typescript theme={null}
const agent = new Agent({
  name: "analyst",
  model: anthropic("claude-sonnet-4-6"),
  reasoning: { enabled: true, budgetTokens: 4000 },
  instructions: "You are a financial analyst. Think through problems step by step.",
});

const result = await agent.run("Should I invest in AAPL at current prices?");

console.log("Thinking:", result.thinking);
// "Let me analyze AAPL's current fundamentals... P/E ratio is..."

console.log("Response:", result.text);
// The final response the user sees

console.log("Reasoning tokens:", result.usage.reasoningTokens);
// Number of tokens used for thinking (not billed as output on some providers)
```

The `thinking` content is never shown to end users by default — it's available for debugging, logging, or advanced use cases.

***

## Reasoning with maxTokens

When reasoning is enabled on Anthropic, `maxTokens` must accommodate both thinking and response tokens. Agentium handles this automatically:

* If `maxTokens` is set but too small for the thinking budget, it's overridden to `budgetTokens + 4096`
* For example: `maxTokens: 1024` with `budgetTokens: 2000` results in an effective `max_tokens` of `6096` sent to the Anthropic API

```typescript theme={null}
const agent = new Agent({
  name: "thinker",
  model: anthropic("claude-sonnet-4-6"),
  maxTokens: 1024, // This will be overridden to 6096
  reasoning: { enabled: true, budgetTokens: 2000 },
});
```

If you want precise control over `max_tokens`, set `maxTokens` to a value larger than `budgetTokens + 1024`.

***

## Logging Reasoning Output

Enable `logLevel: "debug"` to see thinking content in the console:

```typescript theme={null}
const agent = new Agent({
  name: "debugger",
  model: anthropic("claude-sonnet-4-6"),
  reasoning: { enabled: true, budgetTokens: 3000 },
  logLevel: "debug", // Prints thinking content to console
});
```

At `"info"` level, only token usage summaries are logged. At `"debug"`, the full thinking content is printed.