# OpenMAIC Agent Driver Model Configuration: How It Works

> Discover how the OpenMAIC agent driver model is configured. Learn about its stage based routing system, model identifier, API override, dialect, and context window for powerful agent operations.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-06

---

**The OpenMAIC agent driver model is configured through a stage-based routing system in [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts), where the special `maic-agent-driver` stage defines the model identifier, API override, dialect, and context window that powers agent operations.**

The OpenMAIC platform separates model selection from business logic by using **stage-based routing**. This design lets developers declaratively configure which language model drives agent behavior without modifying application code. The configuration lives in [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts) and resolves at runtime through the `resolveModel()` function.

---

## Where the Driver Model Is Defined

In [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts), the server registers a dedicated route for the stage name **`maic-agent-driver`** (see line 152). This route is structurally identical to other stage routes but carries special semantic weight—it exclusively powers the agent driver implementation.

Each route supports these fields:

- **`model`** – The canonical model identifier, formatted as `provider:name` (e.g., `openai:gpt-5.6-luna`)
- **`api`** – An explicit API name that overrides the generic model endpoint (e.g., `openai-completions`)
- **`dialect`** – The response parsing dialect (e.g., `openai-responses`)
- **`contextWindow`** – Numeric override for maximum token context

When both `api` and `dialect` are present, **the `api` value takes precedence** per the implementation comment: "Both api and dialect set … api wins".

---

## How the Configuration Resolves at Runtime

The resolution flow involves three key operations:

1. **Stage targeting** – Code calls `resolveModel({ stage: 'maic-agent-driver' })` to request the driver configuration
2. **Environment merging** – The resolver overlays any user-defined overrides from the **`MODEL_ROUTES`** environment variable
3. **Validation and fallback** – Invalid configurations trigger fallback defaults (verified in [`tests/server/model-routes.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/model-routes.test.ts))

This architecture keeps the driver model isolated. As noted at line 49, the **`maic-agent-driver` route is consumed only by the agent-driver stage**—other stages ignore it entirely.

---

## Runtime Customization via Environment Variables

Operators modify driver behavior without redeployment by setting `MODEL_ROUTES` to a JSON object mapping stage names to specifications:

```json
{
  "maic-agent-driver": {
    "model": "openai:gpt-5.6-luna",
    "api": "openai-completions",
    "contextWindow": 32000
  }
}

```

The resolver validates entries against the schema and applies fallbacks when validation fails.

---

## Special Driver Model Behaviors

The platform treats resolved driver models differently from standard stage models:

- **Connection reuse** – The same driver connection persists for the entire session
- **Thinking disabled** – The "driver thinking" toggle that adds reasoning steps is **forced off** for driver operations

These behaviors are confirmed in [`tests/agent-runtime/conversation-title-generator.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/conversation-title-generator.test.ts), which verifies that driver connections bypass default model selection and operate with thinking disabled.

---

## Code Examples

### Resolving the driver model in server handlers

```typescript
import { resolveModel } from '@/lib/server/model-routes';

// Retrieve configured driver model for current request
const driverModel = await resolveModel({ stage: 'maic-agent-driver' });

```

### Setting driver model via environment

```bash

# In .env or deployment configuration

export MODEL_ROUTES='{
  "maic-agent-driver": {
    "model": "anthropic:claude-sonnet-4",
    "api": "anthropic-messages",
    "dialect": "anthropic-messages"
  }
}'

```

### Accessing resolved driver model ID

```typescript
import { getStageModel } from '@/lib/server/model-routes';

// Inside agent driver implementation
const modelId = getStageModel('maic-agent-driver');
// Returns: 'anthropic:claude-sonnet-4'

```

---

## Key Source Files

| File | Purpose |
|------|---------|
| [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts) | Defines stage routes including `maic-agent-driver` entry |
| [`tests/server/resolve-model.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/resolve-model.test.ts) | Tests driver model resolution logic |
| [`tests/server/model-routes.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/model-routes.test.ts) | Validates override handling and fallback behavior |
| [`tests/agent-runtime/conversation-title-generator.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/conversation-title-generator.test.ts) | Confirms driver connection reuse and thinking disable |

---

## Summary

- **Configuration location**: [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts) registers the `maic-agent-driver` stage route
- **Resolution function**: `resolveModel({ stage: 'maic-agent-driver' })` retrieves active configuration
- **Runtime override**: `MODEL_ROUTES` environment variable accepts JSON with stage-to-model mappings
- **Precedence rule**: `api` field overrides `dialect` when both are set
- **Special behaviors**: Driver connections are reused session-wide with thinking mode disabled
- **Isolation guarantee**: The driver route is consumed exclusively by the agent-driver stage

---

## Frequently Asked Questions

### What is the `maic-agent-driver` stage in OpenMAIC?

The **`maic-agent-driver`** stage is a reserved stage name that identifies which language model powers OpenMAIC's agent runtime. Unlike generic stages that handle user-facing generation, this stage is consumed internally by the agent driver to produce tool calls, plan execution, and conversation management. It is defined alongside other routes in [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts) but treated specially for connection persistence and reasoning control.

### How do I change the OpenMAIC agent driver model without modifying code?

Set the **`MODEL_ROUTES`** environment variable to a JSON object containing a `maic-agent-driver` key with your desired `model`, `api`, `dialect`, and optional `contextWindow`. The resolver merges this with built-in defaults at runtime. Invalid JSON triggers fallback behavior—verify your configuration in [`tests/server/model-routes.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/model-routes.test.ts) patterns.

### Why does the agent driver disable "thinking" mode?

The driver model operates as an **infrastructure component** rather than a reasoning layer. Per [`tests/agent-runtime/conversation-title-generator.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/conversation-title-generator.test.ts), thinking is disabled to ensure deterministic, low-latency execution for internal operations like conversation titling and tool dispatch. End-user reasoning happens in separate stages with their own model configurations.

### What happens if `api` and `dialect` conflict in the driver configuration?

The **`api` field wins**. The resolution logic in [`lib/server/model-routes.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/model-routes.ts) explicitly checks for this condition and prioritizes the explicit API endpoint over the dialect hint. This matters when migrating between provider implementations where the same dialect name maps to different API versions.