Docker Agent Config

Docker Agent Configuration

Overview

Docker Agent (the CLI is docker agent, the open-source project is cagent) runs AI agents declared in a YAML file instead of application code. This skill owns the agent.yaml artifact: the agents section (each entry's model, instruction, and its own toolsets/sub_agents), the top-level models/providers sections referenced from agents, and a top-level commands group agents can opt into with use_commands. It does not cover invoking the CLI or serving/sharing the config — see Related skills.

When to use this skill

Activate this skill when:

• The user is creating, editing, or reviewing an agent.yaml/agent.yml/agent.hcl file.
• The user wants to add a tool/toolset, an MCP server, or a sub-agent to an agent config.
• The user wants to choose or configure a model/provider (OpenAI, Anthropic, Google, Bedrock, Docker Model Runner, custom endpoint) for an agent.
• The user wants a multi-agent "team" with a coordinator delegating to specialists.

Do not use this skill when

Do not use this skill when:

• The task is about running the CLI (docker agent run flags, --safety, --sandbox, aliases, worktrees) — use docker-agent-run.
• The task is about exposing an agent as a server (serve mcp/api/a2a/acp/chat), distributing it (share push/pull), or evaluating it (evaluation sessions, --baseline regression gates) — use docker-agent-deploy.
• The task is about a generic Dockerfile or Compose service unrelated to Docker Agent — use docker-build-strategies or docker-compose-patterns.

Core guidance

File structure

• Every config needs at least one agent under top-level agents:. The agent named root, or the first agent defined, is the entry point that receives user messages.

  agents:
    root:
      model: anthropic/claude-sonnet-4-5
      description: A coding assistant
      instruction: |
        You are an expert developer. Help users write clean,
        efficient code. Explain your reasoning step by step.
      toolsets:
        - type: filesystem
        - type: shell
        - type: think

• Required agent properties: model, description, instruction (or instruction_file). description is not decoration — other agents read it to decide whether to delegate to this one, so keep it accurate.
• Use instruction_file (a relative path, no ..) instead of an inline instruction for long prompts; this keeps diffs focused on behavior, not YAML escaping. instruction and instruction_file are mutually exclusive. instruction_file is not supported for agents loaded from an OCI reference or URL — inline instruction there.

Models and providers

• Two ways to set a model: inline provider/model shorthand, or a named entry under top-level models: referencing a provider. Use the named form whenever you need temperature, max_tokens, thinking_budget, or reuse across agents.

  models:
    claude:
      provider: anthropic
      model: claude-sonnet-4-5
      max_tokens: 64000
  
  agents:
    root:
      model: claude

• Built-in provider keys: openai, anthropic, google, amazon-bedrock, dmr (Docker Model Runner, local, no API key), ollama (local). Dozens of additional built-in aliases exist (mistral, groq, xai, together, azure, github-copilot, openrouter, ...) — each needs its own <PROVIDER>_API_KEY-style env var; run docker agent models --all to see what's resolvable, and docker agent setup to register credentials interactively instead of hand-editing env vars.
• Never hardcode an API key in agent.yaml. Provider credentials come from environment variables (token_key for custom providers) or from ~/.config/cagent/.env written by docker agent setup.
• Prefer dmr/<model> for agents that must run offline or must not send data to a third party; it costs nothing and needs no credential. Use a paid cloud provider only when the task needs it.
• Give resilience-critical agents a fallback so a provider outage or rate limit does not stop the run:

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

• For a self-hosted/OpenAI-compatible endpoint (vLLM, LiteLLM, a corporate gateway), define a providers: entry with base_url and token_key rather than putting the URL inline on every model:

  providers:
    my_gateway:
      base_url: https://api.example.com/v1
      token_key: MY_API_KEY
  models:
    my_model:
      provider: my_gateway
      model: gpt-4o

Toolsets

• Built-in toolsets need no external dependency: filesystem, shell, think, todo, tasks, memory, fetch, background-jobs, script, lsp, api. Add one per list entry:

  toolsets:
    - type: filesystem
    - type: shell

• If an agent only describes a plan but never executes it, add type: todo (or shell) — a common symptom of an agent missing the tool it needs to act, not a model problem.
• For external tools, prefer an MCP server from Docker's MCP catalog over a bespoke integration — it runs containerized and is reusable across agents:

  toolsets:
    - type: mcp
      ref: docker:duckduckgo

  Local stdio and remote HTTP/SSE MCP servers are also supported; see references/toolsets-and-providers.md.
• Use defer: true on a toolset (MCP or otherwise) to load its tools on-demand instead of at startup, when the agent has many toolsets and startup latency matters.
• Set readonly: true on an agent to restrict every toolset it uses to read-only tools — use this for reviewer/analysis agents that must not mutate anything.