Share feedback
Answers are generated based on the documentation.

Agents

Table of contents

Agents are the core building blocks of docker-agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents.

What is an Agent?

An agent in docker-agent is defined by:

  • Model — The AI model powering it (e.g., Claude, GPT-5, Gemini). See Models.
  • Description — A brief summary of what the agent does (used by other agents for delegation)
  • Instruction — The system prompt that defines the agent's behavior and personality
  • Tools — Capabilities like filesystem access, shell commands, or external APIs
  • Sub-agents — Other agents it can delegate tasks to
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    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 docker-agent 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.

Note

Naming

The first agent defined in your YAML (or the one named root) is the root agent by default. You can also specify which agent to start with using docker agent run config.yaml -a agent_name.

Agent Properties

PropertyTypeRequiredDescription
modelstring✓Model reference (inline like openai/gpt-5 or a named model)
descriptionstring✓What the agent does — used by other agents for delegation
instructionstring✓System prompt defining behavior
toolsetsarray✗List of tool configurations
sub_agentsarray✗Names of agents this agent can delegate to
fallbackobject✗Fallback model configuration for resilience
add_dateboolean✗Include current date in context
add_environment_infoboolean✗Include OS, working directory, git info in context
max_iterationsint✗Max tool-calling loops (default: unlimited)
commandsobject✗Named prompts callable via /command
skillsboolean | list✗Enable skill discovery and loading. true = ["local"]; list values may combine "local" with remote skill-server URLs.

Model Fallbacks

Agents can automatically fail over to alternative models when the primary model is unavailable:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    fallback:
      models:
        - openai/gpt-5
        - google/gemini-3.5-flash
      retries: 2 # retries per model for 5xx errors
      cooldown: 1m # stick with fallback after 429

Named Commands

Define reusable prompts that can be invoked as commands:

agents:
  root:
    model: openai/gpt-5
    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
$ docker agent run agent.yaml /df
$ docker agent run agent.yaml /greet

Commands support environment variable interpolation using JavaScript template literal syntax. Undefined variables expand to empty strings.

Default Agent

Running docker agent run without a config file uses a built-in default agent. This is a capable general-purpose agent for quick tasks without needing any configuration.

# Use the default agent
$ docker agent run

# Override the default with an alias
$ docker agent alias add default /path/to/my-agent.yaml
$ docker agent run  # now runs your custom agent
Tip

See also

For reusable task-specific instructions, see Skills. For multi-agent patterns, see Multi-Agent. For full config reference, see Agent Config.