# How to Configure Reasoning Options for Different Models in Codebuff

> Configure reasoning options in Codebuff for different models. Control chain-of-thought data, token budgets, and reasoning depth using the reasoningOptions block.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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:

```typescript
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:

```typescript
// ./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`](https://github.com/CodebuffAI/codebuff/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
// ./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`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/impl/llm.ts) extracts `reasoningText` and `reasoningTokens` from the OpenRouter response:

```typescript
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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/prompt-agent-stream.ts) | Runtime logic that copies `template.reasoningOptions` into the OpenRouter request payload. |
| [`sdk/src/impl/llm.ts`](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/impl/llm.ts) | Stream processor that extracts `reasoningText` and `reasoningTokens` from OpenRouter responses. |
| [`web/src/llm-api/openrouter.ts`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/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.