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

Type	Purpose	Fallback
`base`	Text generation and reasoning	Required at project level
`structuredOutput`	JSON/structured output only	Falls back to `base`
`summarizer`	Summaries and status updates	Falls back to `base`

Supported Models

Provider	Example Models	API Key
Anthropic	`anthropic/claude-sonnet-4-6` `anthropic/claude-sonnet-4-5` `anthropic/claude-haiku-4-5` `anthropic/claude-opus-4-6`	`ANTHROPIC_API_KEY`
OpenAI	`openai/gpt-5.4-pro` `openai/gpt-5.4` `openai/gpt-5.2` `openai/gpt-5.1` `openai/gpt-4.1` `openai/gpt-4.1-mini` `openai/gpt-4.1-nano` `openai/gpt-5`*	`OPENAI_API_KEY`
Azure OpenAI	`azure/my-gpt4-deployment` `azure/my-gpt35-deployment`	`AZURE_API_KEY`
Google	`google/gemini-3.1-pro-preview` `google/gemini-2.5-flash` `google/gemini-2.5-flash-lite`	`GOOGLE_GENERATIVE_AI_API_KEY`
OpenRouter	`openrouter/anthropic/claude-sonnet-4-0` `openrouter/meta-llama/llama-3.1-405b`	`OPENROUTER_API_KEY`
Gateway	`gateway/openai/gpt-4.1-mini`	`AI_GATEWAY_API_KEY`
NVIDIA NIM	`nim/nvidia/llama-3.3-nemotron-super-49b-v1.5` `nim/nvidia/nemotron-4-340b-instruct`	`NIM_API_KEY`
Custom OpenAI-compatible	`custom/my-custom-model` `custom/llama-3-custom`	`CUSTOM_LLM_API_KEY`
Mock	`mock/default`	None required

Note

*openai/gpt-5, openai/gpt-5-mini, and openai/gpt-5-nano require a verified OpenAI organization. If your organization is not yet verified, these models will not be available.

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 }
  }
}

Note

Constructor-level config (baseURL, headers, resourceName, apiVersion) is always specified at the top level of providerOptions, not nested under a provider key.

Complete Examples

Basic configuration:

OpenAI with reasoning:

Anthropic with thinking:

Google with thinking:

Vercel AI Gateway with model routing:

The Gateway provider supports routing requests across multiple models with automatic fallback. If the primary model fails or is unavailable, the gateway tries the next model in the list.

Note

All models in the models array must be valid Vercel AI Gateway model IDs. The gateway falls through to the next model on failure — if all models fail, the request errors. Set AI_GATEWAY_API_KEY in your environment for authentication.

Azure OpenAI:

Note

Azure OpenAI requires either resourceName (for standard Azure OpenAI deployments) or baseURL (for custom endpoints) in providerOptions. The AZURE_API_KEY environment variable must be set for authentication. Note that only one Azure OpenAI resource can be used at a time since authentication is handled via a single environment variable.

Custom OpenAI-compatible provider:

Note

Custom OpenAI-compatible providers require a base URL to be specified in providerOptions.baseURL or providerOptions.baseUrl. The CUSTOM_LLM_API_KEY environment variable will be automatically used for authentication if present.

Context Window Override

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

Note

The contextWindowSize option is useful when:

Using a custom model not in the built-in registry
The framework incorrectly detects the context window size
You want to artificially limit the context window for testing

This affects compression triggers and oversized artifact detection (artifacts exceeding 30% of the context window).

CLI Defaults

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

Provider	Base	Structured Output	Summarizer
Anthropic	`claude-sonnet-4-5`	`claude-sonnet-4-5`	`claude-sonnet-4-5`
OpenAI	`gpt-4.1`	`gpt-4.1-mini`	`gpt-4.1-nano`
Google	`gemini-2.5-flash`	`gemini-2.5-flash-lite`	`gemini-2.5-flash-lite`

On this page