Skip to main content
Every agent requires a model. You can reference a model inline with a short provider/model-name string, or define named models in a top-level models map for reuse and fine-grained configuration.

​
Inline model references

The quickest way to assign a model is the provider/model-name shorthand directly on the agent:
agent.yaml
agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
This works for any provider. The format is always <provider-key>/<model-name>.

​
Named models

For reusable configuration or advanced options, define models in the top-level models section and reference them by name:
agent.yaml
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 64000
    temperature: 0.7

agents:
  root:
    model: claude
    instruction: You are a helpful assistant.
Named models let you configure temperature, token limits, thinking budgets, and other parameters, and reuse the same model definition across multiple agents.

​
Model fields

​
provider
string
required
Provider identifier. See supported providers below.
​
model
string
required
Model name as understood by the provider (e.g., claude-sonnet-4-0, gpt-4o).
​
temperature
number
Randomness of responses. Range 0.0 (deterministic) to 1.0 (creative). Provider defaults apply when omitted.
​
max_tokens
number
Maximum number of tokens in the model’s response.
​
top_p
number
Nucleus sampling probability. Range 0.0 to 1.0.
​
frequency_penalty
number
Reduces repetition of token sequences. Range 0.0 to 2.0.
​
presence_penalty
number
Encourages the model to introduce new topics. Range 0.0 to 2.0.
​
thinking_budget
string | number
Controls how much the model reasons before responding. Accepts a string effort level or an integer token count. See thinking budget below.
​
base_url
string
Custom API endpoint. Useful for proxies, gateways, or self-hosted models.
​
token_key
string
Environment variable name containing the API token. Overrides the provider default.
​
parallel_tool_calls
boolean
Whether the model can issue multiple tool calls in a single turn.
​
provider_opts
object
Arbitrary provider-specific options passed through to the API.

​
Supported providers

ProviderKeyExample modelsAPI key env var
OpenAIopenaigpt-4o, gpt-5, gpt-5-miniOPENAI_API_KEY
Anthropicanthropicclaude-sonnet-4-0, claude-sonnet-4-5ANTHROPIC_API_KEY
Googlegooglegemini-2.5-flash, gemini-3-proGOOGLE_API_KEY
AWS Bedrockamazon-bedrockClaude, Nova, Llama modelsAWS credentials
Docker Model Runnerdmrai/qwen3, ai/llama3.2None (local)
MistralmistralMistral modelsMISTRAL_API_KEY
xAIxaiGrok modelsXAI_API_KEY
See Model Providers for detailed setup guides.

​
Thinking budget

Control how much the model reasons before responding. The accepted values depend on the provider:
ProviderFormatValuesDefault
OpenAIstringminimal, low, medium, highmedium
Anthropicinteger1024–32768 tokens8192
Gemini 2.5integer0 (off), -1 (dynamic), or token count-1 (dynamic)
Gemini 3stringminimal, low, medium, highvaries
Allstringnone or 0 to disable thinking—
agent.yaml
models:
  deep-thinker:
    provider: anthropic
    model: claude-sonnet-4-5
    thinking_budget: 16384  # integer token budget

  fast-responder:
    provider: openai
    model: gpt-5-mini
    thinking_budget: none   # disable thinking entirely

​
Fallback models

Configure fallback models on an agent for automatic failover when the primary is unavailable:
agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    fallback:
      models:
        - openai/gpt-4o
        - google/gemini-2.5-flash
      retries: 2
      cooldown: 1m
See Agent fallbacks for the full field reference.

​
Alloy models

You can assign multiple models to a single agent by comma-separating them. Docker Agent alternates between them turn by turn, leveraging the strengths of each:
agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0,openai/gpt-5-mini
    instruction: You are a helpful assistant.

​
Multi-provider teams

Different agents in the same config can use different providers. Use named models to keep the config readable:
dev-team.yaml
models:
  fast:
    provider: openai
    model: gpt-5-mini
    temperature: 0.2

  creative:
    provider: openai
    model: gpt-4o
    temperature: 0.8

  local:
    provider: dmr
    model: ai/qwen3  # runs locally, no API cost

agents:
  analyst:
    model: fast
    instruction: Analyze requirements precisely.

  writer:
    model: creative
    instruction: Write engaging documentation.

  helper:
    model: local
    instruction: Handle simple formatting tasks.
Agents in a multi-agent config can freely mix providers. This lets you use fast cheap models for simple tasks and powerful models only where needed.

​
Next steps

Model providers

Setup guides for every supported provider.

Model configuration reference

Full reference for model config fields.

Multi-Agent

Use different models for different agent roles.

Agents

How agents use models and configure fallbacks.

Build docs developers (and LLMs) love

Get started for freeTalk to us