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

import { Agent, google } from "@agentium/core";

const agent = new Agent({
  name: "Thinker",
  model: google(process.env.GOOGLE_MODEL ?? "gemini-3.8-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

boolean

required

Enable or disable reasoning for this agent.

How hard the model thinks. OpenAI-family and Gemini 3 use it directly. Claude 4.6+ and Claude 5 map it to output_config.effort (minimal becomes low). DeepSeek only accepts low / high / max, so medium is sent as high. Mistral sends high or none. "none" turns thinking off where the provider allows it. Grok 4.5 and 4.6 ignore none.

number

Token budget. Used by Claude models that still take thinking.budget_tokens (before Opus/Sonnet 4.6), Gemini 2.5, and Cohere tokenBudget. Default on those Claude models: 10000.

'auto' | 'concise' | 'detailed'

OpenAI Responses summary. Default "detailed", which is what fills result.thinking. "auto" asks for the most detailed summary that model supports.

'standard' | 'pro'

GPT-5.6 and GPT-6 Responses execution mode. pro spends more work and latency.

'auto' | 'current_turn' | 'all_turns'

Which OpenAI reasoning items later turns should see. Omit it to keep the model default.

Provider Support

Each provider maps ReasoningConfig to its native API:

Provider	What Agentium sends	Models
OpenAI / Azure	Responses: `{ effort, summary: "detailed", mode?, context? }`. The reasoning item is replayed on the next tool turn.	`gpt-5.6-`, `gpt-6-`, `o3`, `o4-mini`
DeepSeek	`thinking.type` plus `reasoning_effort` of `low` / `high` / `max`. `reasoning_content` is replayed.	`deepseek-*`
xAI Grok	`reasoning_effort`. `none` is omitted on Grok 4.5 and 4.6. Responses calls also ask for encrypted reasoning.	`grok-*`
Mistral	Native `reasoningEffort`: `high` or `none`.	`mistral-*`
Cohere	Native `thinking: { type, tokenBudget? }`.	`command-*`
Anthropic / AWS Claude	4.6+ and Claude 5: `thinking: { type: "adaptive", display: "summarized" }` plus `output_config.effort`. Earlier models: `type: "enabled"` with `budget_tokens` and `display: "summarized"`.	Claude 4, 4.5, 4.6, 5
Gemini 2.5 / Vertex	`thinkingBudget` and `includeThoughts: true`	`gemini-2.5-*`
Gemini 3 / Vertex	`thinkingLevel` and `includeThoughts: true`. Gemini 3.8 drops `temperature` and `topP`. Tool calls include the call id.	`gemini-3*`

When reasoning is enabled for OpenAI, temperature is ignored (the API does not allow both). For Anthropic, temperature and top_p are stripped when thinking is active.

Tools + reasoning

GPT-5.4+, GPT-5.6, and GPT-6 reject function tools on Chat Completions unless reasoning_effort is "none". GPT-5.6 defaults to medium when you omit the field, which is why an agent with tools 400s even if you never set reasoning. Agentium routes that combination to /v1/responses and keeps your effort. If the endpoint is missing (old Azure API version, some proxies), it falls back to Chat Completions with reasoning_effort: "none" so the run still works.

const agent = new Agent({
  name: "analyst",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  tools: [/* ... */],
  reasoning: { enabled: true, effort: "high" },
});

Claude, Gemini, OpenAI Responses, and DeepSeek tool turns must echo the previous reasoning payload. Agentium stores it on the assistant message (providerExtras) and sends it back. You do not pass it yourself. OpenAI only returns readable thinking when the request sets reasoning.summary. Agentium sends "detailed" unless you set summary.

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:

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

interface ReasoningConfig {
  enabled: boolean;
  effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
  budgetTokens?: number;
  summary?: "auto" | "concise" | "detailed";
  mode?: "standard" | "pro";
  context?: "auto" | "current_turn" | "all_turns";
}

interface ProviderOptions {
  promptCache?: boolean;
  promptCacheRetention?: "in_memory" | "24h";
  compactionTokens?: number;
  clearToolResults?: boolean;
  mediaResolution?: "low" | "medium" | "high" | "ultra_high";
  cachedContent?: string;
  googleSearch?: boolean;
}

providerOptions is separate from reasoning:

promptCache puts an Anthropic cache_control breakpoint on the system prompt.
compactionTokens turns on Anthropic server compaction (compact_20260112). Values under 50000 are raised to 50000.
clearToolResults turns on Anthropic tool-result clearing.
promptCacheRetention is OpenAI Responses prompt_cache_retention.
mediaResolution, cachedContent, and googleSearch are Gemini generate options. Gemini 3.8 also drops temperature and topP.

const agent = new Agent({
  name: "cached-thinker",
  model: anthropic(process.env.ANTHROPIC_MODEL ?? "claude-opus-5-5"),
  reasoning: { enabled: true, effort: "high" },
  providerOptions: {
    promptCache: true,
    clearToolResults: true,
    compactionTokens: 150_000,
  },
});

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:

const agent = new Agent({
  name: "analyst",
  model: anthropic(process.env.ANTHROPIC_MODEL ?? "claude-sonnet-5-5"),
  reasoning: { enabled: true, effort: "high" },
  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

On Claude models that still use budget_tokens (before Opus/Sonnet 4.6), 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

const agent = new Agent({
  name: "thinker",
  model: anthropic(process.env.ANTHROPIC_MODEL ?? "claude-sonnet-5-5"),
  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:

const agent = new Agent({
  name: "debugger",
  model: anthropic(process.env.ANTHROPIC_MODEL ?? "claude-sonnet-5-5"),
  reasoning: { enabled: true, effort: "high" },
  logLevel: "debug", // Prints thinking content to console
});

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

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Quick Start

Configuration

Provider Support

Tools + reasoning

Output

Streaming

ReasoningConfig Type

Logging

Accessing Thinking Content

Reasoning with maxTokens

Logging Reasoning Output

​Quick Start

​Configuration

​Provider Support

​Tools + reasoning

​Output

​Streaming

​ReasoningConfig Type

​Logging

​Accessing Thinking Content

​Reasoning with maxTokens

​Logging Reasoning Output

Quick Start

Configuration

Provider Support

Tools + reasoning

Output

Streaming

ReasoningConfig Type

Logging

Accessing Thinking Content

Reasoning with maxTokens

Logging Reasoning Output