How to Configure Reasoning Options for Different Models in Codebuff

Add a reasoningOptions block to your agent definition to control whether models return chain-of-thought data, set token budgets with max_tokens, or adjust reasoning depth with effort presets.

When building agents in Codebuff, you can configure reasoning options for different models to balance cost, latency, and explainability. The SDK supports this through a unified reasoningOptions schema that works across any model available via OpenRouter, including Claude, Gemini, and GPT-5.

Understanding Reasoning Configuration in Codebuff

The AgentDefinition Schema

The source of truth for reasoning configuration lives in agents/types/agent-definition.ts. Here, the AgentDefinition interface includes an optional reasoningOptions property that accepts either a token budget or an effort level.

According to the Codebuff source code, the type definition allows:

• max_tokens: A hard limit on reasoning tokens
• effort: A preset level (high, medium, low, minimal, none)
• enabled: Boolean to toggle reasoning on or off
• exclude: Boolean to hide reasoning from the final output while still generating it

OpenRouter Integration

Under the hood, Codebuff maps your agent's reasoningOptions to the OpenRouter API format defined in packages/internal/src/openrouter-ai-sdk/types/openrouter-chat-completions-input.ts. This ensures that models supporting chain-of-thought—such as anthropic/claude-sonnet-4 or google/gemini-3-pro-preview—receive the correct parameters.

How to Configure Reasoning Options for Different Models

Basic Schema and Validation

When you configure reasoning options for different models in Codebuff, the SDK validates your configuration using Zod during the validateAgents step. You must choose exactly one of max_tokens or effort, not both.

The valid structure is:

reasoningOptions?: {
  enabled?: boolean;
  exclude?: boolean;
} & (
  | { max_tokens: number }
  | { effort: 'high' | 'medium' | 'low' | 'minimal' | 'none' }
);

Token-Based Configuration Example

To configure a strict token budget for Claude, specify max_tokens in your agent definition:

// ./my-agents/claude-reasoner.ts
import { AgentDefinition } from '../agents/types/agent-definition';

export const claudeReasoner: AgentDefinition = {
  id: 'claude-reasoner',
  displayName: 'Claude Reasoner',
  model: 'anthropic/claude-sonnet-4',
  reasoningOptions: {
    max_tokens: 2048,   // Allocate up to 2,048 tokens for chain-of-thought
  },
};

export default claudeReasoner;

At runtime, packages/agent-runtime/src/prompt-agent-stream.ts copies this configuration onto the OpenRouter request as reasoning: { max_tokens: 2048 }.

Effort-Based Configuration Example

For models like Gemini where you prefer to specify compute depth rather than token limits, use the effort preset:

import { AgentDefinition } from '../agents/types/agent-definition';

export const geminiThinker: AgentDefinition = {
  id: 'gemini-thinker',
  displayName: 'Gemini Thinker',
  model: 'google/gemini-3-pro-preview',
  reasoningOptions: {
    effort: 'high',   // Request maximum reasoning depth
  },
};

export default geminiThinker;

Disabling or Hiding Reasoning

To completely disable reasoning for a specific model:

reasoningOptions: {
  enabled: false,   // No reasoning field is sent to the provider
}

Alternatively, to generate reasoning for internal logging but exclude it from the user-facing response:

reasoningOptions: {
  exclude: true,   // Reasoning is generated but stripped from final output
}

Model-Specific Routing with Provider Options

When you configure reasoning options for different models in Codebuff, you can combine reasoningOptions with providerOptions to ensure OpenRouter selects a provider that supports your chosen reasoning style:

import { AgentDefinition } from '../agents/types/agent-definition';

export const mixedReasoner: AgentDefinition = {
  id: 'mixed-reasoner',
  displayName: 'Mixed Reasoner',
  model: 'openrouter/auto',
  reasoningOptions: {
    effort: 'high',
  },
  providerOptions: {
    order: ['anthropic', 'google'],  // Prioritize Claude, then Gemini
    allow_fallbacks: true,
    require_parameters: true,        // Ensures selected model supports reasoning
  },
};

export default mixedReasoner;

Runtime Implementation and Code Examples

Complete Agent Definition Example

Here is a production-ready agent definition that demonstrates how to configure reasoning options for different models in Codebuff:

// ./agents/example/reasoning-demo.ts
import type { AgentDefinition } from '../../agents/types/agent-definition';

export const reasoningDemo: AgentDefinition = {
  id: 'reasoning-demo',
  version: '0.1.0',
  displayName: 'Reasoning Demo',
  model: 'anthropic/claude-opus-4.6',
  reasoningOptions: {
    max_tokens: 3072,
    enabled: true,
  },
  providerOptions: {
    order: ['anthropic'],
    allow_fallbacks: false,
  },
  instructionsPrompt: `
    You are a helpful AI that must think step-by-step.
    Return a concise answer and include your chain-of-thought reasoning.
  `,
  handleSteps: function* ({ logger }) {
    logger.info('Running reasoning demo');
    yield 'STEP';
  },
};

export default reasoningDemo;

Accessing Reasoning Output at Runtime

When you execute an agent configured with reasoning options, the SDK surfaces the model's internal chain-of-thought through the result object. The stream processor in sdk/src/impl/llm.ts extracts reasoningText and reasoningTokens from the OpenRouter response:

import { runAgent } from '@codebuff/sdk';
import reasoningDemo from './agents/example/reasoning-demo';

async function demo() {
  const result = await runAgent({
    agent: reasoningDemo,
    input: { prompt: 'Explain quantum entanglement.' },
  });

  console.log('Final Answer:', result.output?.answer);
  console.log('Chain of Thought:', result.reasoning?.text);
  console.log('Reasoning Tokens:', result.reasoning?.tokens);
}

demo();

The result.reasoning object contains the raw reasoning string returned by the provider and the token count reported in completion_tokens_details.reasoning_tokens.

Key Source Files Reference

File	Purpose
agents/types/agent-definition.ts	Defines the AgentDefinition interface and reasoningOptions schema used when authoring agents.
packages/internal/src/openrouter-ai-sdk/types/openrouter-chat-completions-input.ts	Contains the OpenRouterReasoningOptions type that maps to the OpenRouter API specification.
packages/agent-runtime/src/prompt-agent-stream.ts	Runtime logic that copies template.reasoningOptions into the OpenRouter request payload.
sdk/src/impl/llm.ts	Stream processor that extracts reasoningText and reasoningTokens from OpenRouter responses.
web/src/llm-api/openrouter.ts	Server-side endpoint that forwards reasoning parameters to OpenRouter and handles usage accounting.

Summary

• Add reasoningOptions to any AgentDefinition to request chain-of-thought data from supported models.
• Choose max_tokens for explicit token budgets or effort for preset reasoning depth levels.
• Use enabled to toggle reasoning on or off, and exclude to hide reasoning from final outputs while retaining it for logging.
• Combine providerOptions with reasoning settings to ensure OpenRouter routes to models that support your chosen reasoning style.
• At runtime, access generated reasoning through result.reasoning.text and result.reasoning.tokens as processed in sdk/src/impl/llm.ts.

Frequently Asked Questions

What is the difference between max_tokens and effort in reasoning options?

The max_tokens parameter sets a hard limit on how many tokens the model can allocate to its internal chain-of-thought, giving you precise control over cost and context window usage. The effort parameter uses provider-specific presets (high, medium, low, minimal, none) that adjust reasoning depth without requiring you to calculate token budgets manually. You must specify exactly one of these two options, not both.

Can I use reasoning options with any model in Codebuff?

You can configure reasoning options for any model supported through OpenRouter, including Claude, Gemini, GPT-5, and Qwen. However, the actual behavior depends on the specific provider's implementation. Some models may ignore max_tokens or map effort presets differently. To ensure compatibility, use providerOptions with require_parameters: true to force OpenRouter to select only models that explicitly support your chosen reasoning configuration.

How do I access the reasoning output after running an agent?

When you execute an agent using runAgent() from the @codebuff/sdk, the result object includes a reasoning property containing text (the raw chain-of-thought string) and tokens (the count reported in completion_tokens_details.reasoning_tokens). This data is extracted by the stream processor in sdk/src/impl/llm.ts and surfaced automatically when your agent configuration has enabled: true and exclude: false.

Why would I set exclude: true instead of enabled: false?

Setting enabled: false prevents the SDK from sending any reasoning parameters to the provider, meaning the model will not generate chain-of-thought data at all. Setting exclude: true still requests reasoning from the model (incurring the associated token cost) but strips the reasoning content from the final response returned to your application. Use exclude: true when you need reasoning for internal logging or debugging but want to hide it from end users, or when you want to ensure the model performs deep reasoning without cluttering the output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}