Skip to main content
An agent combines an AI model, a system prompt, and a set of tools into an autonomous unit that can reason and act. Every docker-agent configuration is built from one or more agents.

​
What makes an agent

Each agent is defined by four things:
  • Model — the AI model powering it (e.g., anthropic/claude-sonnet-4-0, openai/gpt-4o)
  • Instruction — the system prompt that shapes the agent’s behavior and personality
  • Toolsets — capabilities like filesystem access, shell commands, web search, or MCP servers
  • Sub-agents — other agents it can delegate tasks to (optional)
agents.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Expert software developer
    instruction: |
      You are an expert developer. Write clean, efficient code
      and explain your reasoning step by step.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think

​
The root agent

Every configuration has a root agent — the entry point that receives user messages. In a single-agent setup this is the only agent. In a multi-agent setup the root agent acts as a coordinator, delegating tasks to specialized sub-agents.
The first agent defined in your YAML (or one explicitly named root) is treated as the root agent. You can start a different agent with:
docker agent run config.yaml -a agent_name

​
Agent fields

​
model
string
required
Model reference — either an inline provider/model-name string or the name of an entry in the top-level models map.
​
description
string
required
Short description of what the agent does. Other agents use this to decide who to delegate tasks to.
​
instruction
string
required
System prompt that defines the agent’s behavior and persona.
​
toolsets
array
List of tool configurations. Each entry is an object with at minimum a type field. See Tools.
​
sub_agents
string[]
Names of other agents this agent can delegate tasks to. Enabling this automatically provides the transfer_task tool. See Multi-Agent.
​
fallback
object
Fallback model configuration for automatic failover. See Model fallbacks below.
​
max_iterations
number
Maximum number of tool-calling loops before the agent stops. Defaults to unlimited.
​
max_consecutive_tool_calls
number
Maximum number of tool calls the agent can make in a row without a model response.
​
add_date
boolean
When true, injects the current date into the agent’s context at session start.
​
add_environment_info
boolean
When true, injects OS, working directory, and git repository info into context.
​
welcome_message
string
Message shown to the user when the agent session starts.
​
commands
object
Named prompts callable as /command-name in the TUI. See Named commands below.
​
skills
boolean | string[]
Enable skill discovery. true loads skills from the local filesystem. Pass a list of URLs to also load remote skills.
​
hooks
object
Lifecycle hooks that run shell commands before/after tool calls or at session start/end. See Hooks.
​
structured_output
object
JSON schema for structured output responses. See Structured Output.
​
rag
string[]
Names of RAG configurations to attach as retrieval tools. See RAG.

​
Model fallbacks

Agents can automatically fail over to alternative models when the primary is unavailable or rate-limited:
agents.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    fallback:
      models:
        - openai/gpt-4o
        - google/gemini-2.5-flash
      retries: 2     # retries per model for 5xx errors
      cooldown: 1m   # stick with fallback after a 429
​
fallback.models
string[]
Ordered list of fallback models to try. Each can be an inline provider/model string or a named model.
​
fallback.retries
number
default:"2"
Number of retries per model with exponential backoff. Only applies to retryable errors (5xx, timeouts). Use -1 to disable retries.
​
fallback.cooldown
string
default:"1m"
How long to stick with a successful fallback before retrying the primary. Uses Go duration format: 30s, 1m, 2m30s.

​
Named commands

Define reusable prompts that can be invoked with /command-name in the TUI:
agents.yaml
agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    commands:
      df: "Check how much free space I have on my disk"
      greet: "Say hello to ${env.USER}"

# Run a named command non-interactively
docker agent run agent.yaml /df
docker agent run agent.yaml /greet
Commands support environment variable interpolation using JavaScript template literal syntax (${env.VARNAME}). Undefined variables expand to empty strings.

​
Default agent

Running docker agent run without a config file launches a built-in default agent — a capable general-purpose assistant requiring no setup: 
# Use the built-in default agent
docker agent run

# Override the default with your own agent
docker agent alias add default /path/to/my-agent.yaml
docker agent run  # now runs your agent
You can also pull and run pre-built agents from the catalog without writing any YAML:
docker agent run agentcatalog/coder

​
Next steps

Models

Configure AI models and providers for your agents.

Tools

Give your agents capabilities with toolsets.

Multi-Agent

Build teams of collaborating agents.

Agent configuration reference

Full reference for all agent config fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us