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.

yaml

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.

yaml

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:

yaml

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:

yaml

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:

yaml

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:
yaml
```
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.
yaml
```
# 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.

docker-agent-config

NPX Install

Tags

SKILL.md Content

Docker Agent Configuration

Overview

When to use this skill

Do not use this skill when

Core guidance

File structure

Models and providers

Toolsets

Multi-agent teams

Safety and hygiene

Related skills

References

Assets

Checks