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 (docker agent eval) — 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.

Multi-agent teams

• A coordinator delegates via sub_agents: [name, ...]; listing sub-agents automatically enables the transfer_task tool on the parent.

  # Fragment: coder and reviewer are defined separately in the full asset.
  agents:
    root:
      sub_agents: [coder, reviewer]
  

  Use assets/team-agent.yaml for the complete runnable team, including the reviewer's readonly: true restriction. Keep that restriction when adapting the template; a filesystem toolset alone also exposes writes.
• sub_agents also accepts external OCI references (myorg/agent:tag). Pin external references to a digest (name@sha256:...) in production configs to skip the per-run registry lookup that a tag incurs.
• Use transfer_task (via sub_agents) for delegation with a clean, isolated result; use a commands: entry with an agent: field only when you want the user to become that agent for the rest of the session.

Safety and hygiene

• Set redact_secrets: true on any agent that runs shell/fetch tools against untrusted input. It scrubs recognized secret patterns from tool arguments, outgoing messages, and tool output. This is defense in depth, not a guarantee: arbitrary passwords, tokens, or customer data may go undetected.
• Set max_iterations on any agent that loops autonomously (default is unlimited) to bound cost and prevent runaway loops; max_consecutive_tool_calls (default 5) already guards against identical-call loops.
• Keep credentials, tokens, and sensitive customer data out of instruction, instruction_file, and command prompts, whether literal or interpolated. ${env.VAR} expands values into prompt text sent to the model; storing a value in an env file does not prevent this disclosure. Use interpolation only for non-sensitive context.
• Supply provider credentials through docker agent setup or the provider's supported environment variables. For custom providers, token_key: MY_API_KEY names the environment variable, not its value; do not interpolate it. Configure tool/MCP credentials through that integration's authentication mechanism, not through prompts or model-supplied tool arguments. Prompts should describe the authenticated capability without containing its secret. Do not ask the agent to read or print credential files or environment values to check authentication.

Related skills

• For running the agent (docker agent run, safety modes, sandbox, aliases), use docker-agent-run.
• For serving, sharing, or evaluating the agent, use docker-agent-deploy.

References

• references/toolsets-and-providers.md — full built-in toolset list, MCP connection modes, and the provider/env-var table.
• references/sources.md — provenance of every rule in this skill.

Assets

• assets/team-agent.yaml — a runnable multi-agent team template (coordinator + coder + reviewer).

Checks

• Before running an agent, follow checks/verification.md to confirm its resolved config, exposed tools, and provider connectivity, then smoke-test it.