Model Configuration

Configure models at Project (required), Agent, or Sub Agent levels. Settings inherit down the hierarchy.

Configuration Hierarchy

You must configure at least the base model at the project level:

// inkeep.config.ts
export default defineConfig({
  models: {
    base: {
      model: "anthropic/claude-sonnet-4-5",
      providerOptions: { temperature: 0.7, maxOutputTokens: 2048 }
    }
  }
});

Override at agent or sub agent level:

const myAgent = agent({
  models: {
    base: { model: "openai/gpt-5.2" }  // Override project default
  }
});

const mySubAgent = subAgent({
  models: {
    structuredOutput: { model: "openai/gpt-4.1-mini" }  // Override for JSON output
  }
});

Model Types

Supported Models

Pinned vs Unpinned Models

Pinned models include a specific date or version (e.g., anthropic/claude-sonnet-4-20250514) and always use that exact version.

Unpinned models use generic identifiers (e.g., anthropic/claude-sonnet-4-5) and let the provider choose the latest version, which may change over time as providers update their models.

models: {
  base: {
    model: "anthropic/claude-sonnet-4-5",  // Unpinned - provider chooses version
    // vs
    model: "anthropic/claude-sonnet-4-20250514"  // Pinned - exact version
  }
}

The TypeScript SDK also provides constants for common models:

import { Models } from "@inkeep/agents-sdk";

models: {
  base: {
    model: Models.ANTHROPIC_CLAUDE_SONNET_4_5,  // Type-safe constants
  }
}

Provider Options

Inkeep Agents supports all Vercel AI SDK provider options.

How providerOptions works

providerOptions accepts two types of values:

• Scalars (temperature, topP, maxOutputTokens, seed, maxDuration) — standard generation parameters applied to every call
• Objects (anthropic: {}, openai: {}, gateway: {}, etc.) — provider-specific options for that provider

This means you can mix them freely:

providerOptions: {
  temperature: 0.7,            // generation param
  anthropic: {                 // Anthropic-specific options
    thinking: { type: 'enabled', budgetTokens: 8000 }
  }
}

Complete Examples

Basic configuration:

OpenAI with reasoning:

Anthropic with thinking:

Google with thinking:

Vercel AI Gateway:

When AI_GATEWAY_API_KEY is set, Anthropic, OpenAI, and Google models are automatically routed through Vercel AI Gateway for per-request cost tracking. No configuration changes are needed — your existing model strings work as-is. See AI Gateway below for fallback models, allowed providers, and advanced gateway configuration.

Azure OpenAI:

Custom OpenAI-compatible provider:

Context Window Override

For custom or unlisted models, you can explicitly specify the context window size:

AI Gateway

Vercel AI Gateway provides intelligent model routing, automatic failover, and per-request cost tracking. All AI Gateway features require AI_GATEWAY_API_KEY to be set in your environment.

When the gateway is active, Anthropic, OpenAI, and Google models are automatically routed through it — no configuration changes needed. This enables fallback models and allowed providers for those providers. Per-request cost tracking is available for any model routed through the gateway.

For self-hosted deployments, you can bring your own API keys (BYOK) for any provider by configuring them in your Vercel AI Gateway team settings.

Fallback Models

Configure an ordered list of backup models that the gateway tries if the primary model fails or is unavailable:

If the primary model (anthropic/claude-sonnet-4-5) fails, the gateway automatically tries openai/gpt-5.2, then google/gemini-2.5-flash. If all models fail, the request errors.

Fallback models can be configured on any model slot (base, structuredOutput, summarizer). They inherit through the project → agent → sub agent hierarchy — even when a sub agent overrides the model itself, it still inherits fallbackModels from its parent unless it explicitly sets its own. All entries must use the provider/model format (e.g., "openai/gpt-5.2").

Allowed Providers

Restrict and prioritize which providers can serve requests. The order determines preference — the first provider in the list has the highest priority:

The gateway will try to serve the request via AWS Bedrock first. If Bedrock is unavailable, it falls back to Anthropic's direct API. When allowedProviders is set, the model string should omit the provider prefix (e.g., "claude-sonnet-4-5" instead of "anthropic/claude-sonnet-4-5") since the gateway determines which provider to use.

Available providers include: anthropic, openai, google, bedrock, azure, vertex.

Like fallbackModels, allowedProviders inherits through the project → agent → sub agent hierarchy even when the model is overridden at a lower level.

Combining Both

Both features can be used together. With this configuration, allowedProviders restricts and prioritizes which providers can serve the primary model, while fallbackModels defines alternative models to try if the primary model is unavailable:

models: {
  base: {
    model: "claude-sonnet-4-5",
    allowedProviders: ["bedrock", "anthropic"],
    fallbackModels: ["openai/gpt-5.2", "google/gemini-2.5-flash"],
  }
}

Advanced: Manual Gateway Provider Options

You can also configure gateway routing directly via providerOptions for access to the full gateway provider options (order, only, models, byok, providerTimeouts, tags, zeroDataRetention):

models: {
  base: {
    model: "gateway/openai/gpt-4.1",
    providerOptions: {
      gateway: {
        models: ["openai/gpt-4.1", "anthropic/claude-sonnet-4-5"],
      }
    }
  }
}

CLI Defaults

When using inkeep init, defaults are set based on your chosen provider: