OpenMAIC Agent Driver Model Configuration: How It Works

The OpenMAIC agent driver model is configured through a stage-based routing system in 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 and resolves at runtime through the resolveModel() function.

---

Where the Driver Model Is Defined

In 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)

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:

{
  "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, which verifies that driver connections bypass default model selection and operate with thinking disabled.

---

Code Examples

Resolving the driver model in server handlers

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

# 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

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	Defines stage routes including maic-agent-driver entry
tests/server/resolve-model.test.ts	Tests driver model resolution logic
tests/server/model-routes.test.ts	Validates override handling and fallback behavior
tests/agent-runtime/conversation-title-generator.test.ts	Confirms driver connection reuse and thinking disable

---

Summary

• Configuration location: 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 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 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, 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 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.

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