docker-agent-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Agent Configuration

Docker Agent 配置

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.

Docker Agent（CLI 为

docker agent

，开源项目为

cagent

）运行在 YAML 文件中声明的 AI agent，而不是应用程序代码。此技能负责

agent.yaml

工件：

agents

部分（每个条目的

model

、

instruction

，以及各自的

toolsets

sub_agents

）、agent 引用的顶级

models

providers

部分，以及 agent 可通过

use_commands

选择加入的顶级

commands

组。它不涉及 CLI 的调用或配置的提供/共享——请参阅相关技能。

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.

在以下情况激活此技能：

用户正在创建、编辑或审查
```
agent.yaml
```
/
```
agent.yml
```
/
```
agent.hcl
```
文件。
用户想要向 agent 配置添加工具/工具集、MCP 服务器或子 agent。
用户想要为 agent 选择或配置模型/provider（OpenAI、Anthropic、Google、Bedrock、Docker Model Runner、自定义端点）。
用户想要一个多 agent “团队”，由协调者将任务委派给专家。

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
```
.

在以下情况请勿使用此技能：

任务涉及运行 CLI（
```
docker agent run
```
标志、
```
--safety
```
、
```
--sandbox
```
、别名、worktrees）——请使用
```
docker-agent-run
```
。
任务涉及将 agent 作为服务器暴露（
```
serve mcp/api/a2a/acp/chat
```
）、分发它（
```
share push/pull
```
）或评估它（
```
docker agent eval
```
）——请使用
```
docker-agent-deploy
```
。
任务涉及与 Docker Agent 无关的通用 Dockerfile 或 Compose 服务——请使用
```
docker-build-strategies
```
或
```
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.

每个配置在顶层
```
agents:
```
下至少需要一个 agent。名为
```
root
```
的 agent，或第一个定义的 agent，是接收用户消息的入口点。

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

必需的 agent 属性：
```
model
```
、
```
description
```
、
```
instruction
```
（或
```
instruction_file
```
）。
```
description
```
不是装饰性的——其他 agent 会读取它来决定是否将任务委派给该 agent，因此请保持准确。
对于较长的提示，使用
```
instruction_file
```
（相对路径，不包含
```
..
```
）而不是内联
```
instruction
```
；这样可以让 diff 聚焦于行为，而不是 YAML 转义。
```
instruction
```
和
```
instruction_file
```
互斥。从 OCI 引用或 URL 加载的 agent 不支持
```
instruction_file
```
——在那里使用内联
```
instruction
```
。

Models and providers

模型与 provider

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

设置模型有两种方式：内联
```
provider/model
```
简写，或顶层
```
models:
```
下引用
```
provider
```
的命名条目。当你需要
```
temperature
```
、
```
max_tokens
```
、
```
thinking_budget
```
或在多个 agent 间复用时，请使用命名形式。

yaml

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

  agents:
    root:
      model: claude

内置 provider 键：
```
openai
```
、
```
anthropic
```
、
```
google
```
、
```
amazon-bedrock
```
、
```
dmr
```
（Docker Model Runner，本地，无需 API key）、
```
ollama
```
（本地）。还有数十个额外的内置别名（
```
mistral
```
、
```
groq
```
、
```
xai
```
、
```
together
```
、
```
azure
```
、
```
github-copilot
```
、
```
openrouter
```
，等等）——每个都需要自己的
```
<PROVIDER>_API_KEY
```
风格的环境变量；运行
```
docker agent models --all
```
查看可解析的内容，运行
```
docker agent setup
```
以交互方式注册凭据，而不是手工编辑环境变量。
切勿在
```
agent.yaml
```
中硬编码 API key。Provider 凭据来自环境变量（自定义 provider 使用
```
token_key
```
）或由
```
docker agent setup
```
写入的
```
~/.config/cagent/.env
```
。
对于必须在离线状态下运行或不得将数据发送给第三方的 agent，优先使用
```
dmr/<model>
```
；它不需要成本，也不需要凭据。仅在任务需要时才使用付费云 provider。
为对韧性要求较高的 agent 提供
```
fallback
```
，这样 provider 故障或速率限制不会中断运行：

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

对于自托管/兼容 OpenAI 的端点（vLLM、LiteLLM、企业网关），定义带
```
base_url
```
和
```
token_key
```
的
```
providers:
```
条目，而不是在每个模型上内联 URL：

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.

内置工具集不需要外部依赖：
```
filesystem
```
、
```
shell
```
、
```
think
```
、
```
todo
```
、
```
tasks
```
、
```
memory
```
、
```
fetch
```
、
```
background-jobs
```
、
```
script
```
、
```
lsp
```
、
```
api
```
。每个列表条目添加一个：

yaml

  toolsets:
    - type: filesystem
    - type: shell

如果 agent 只描述计划但从不执行，请添加
```
type: todo
```
（或
```
shell
```
）——这通常是 agent 缺少行动所需工具的症状，而不是模型问题。
对于外部工具，优先使用 Docker MCP 目录中的 MCP 服务器，而不是定制集成——它以容器化方式运行，并且可跨 agent 复用：

yaml

  toolsets:
    - type: mcp
      ref: docker:duckduckgo

本地 stdio 和远程 HTTP/SSE MCP 服务器也受支持；请参阅

references/toolsets-and-providers.md

。

在工具集（MCP 或其他）上使用
```
defer: true
```
，以便在 agent 有许多工具集且启动延迟很重要时，按需加载其工具，而不是在启动时加载。
在 agent 上设置
```
readonly: true
```
，将其使用的每个工具集限制为只读工具——用于不得更改任何内容的审查/分析 agent。

Multi-agent teams

多 agent 团队

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.

协调者通过
```
sub_agents: [name, ...]
```
委派；列出子 agent 会自动在父级上启用
```
transfer_task
```
工具。

yaml

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

使用

assets/team-agent.yaml

获取完整可运行的团队，包括 reviewer 的

readonly: true

限制。在改编模板时保持该限制；单独的 filesystem 工具集也会暴露写入操作。

```
sub_agents
```
也接受外部 OCI 引用（
```
myorg/agent:tag
```
）。在生产配置中，将外部引用固定到摘要（
```
name@sha256:...
```
），以跳过标签带来的每次运行的注册表查找。
使用
```
transfer_task
```
（通过
```
sub_agents
```
）进行委派，以获得干净、隔离的结果；仅当你希望用户在本会话剩余时间内成为该 agent 时，才使用带
```
agent:
```
字段的
```
commands:
```
条目。

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.

在任何对不可信输入运行 shell/fetch 工具的 agent 上设置
```
redact_secrets: true
```
。它会从工具参数、传出消息和工具输出中清除可识别的机密模式。这是纵深防御，而不是保证：任意密码、令牌或客户数据可能无法被发现。
在任何自主循环的 agent 上设置
```
max_iterations
```
（默认为无限），以限制成本并防止失控循环；
```
max_consecutive_tool_calls
```
（默认 5）已经可以防止相同调用循环。
保持凭据、令牌和敏感客户数据远离
```
instruction
```
、
```
instruction_file
```
和命令提示，无论是字面值还是插值。
```
${env.VAR}
```
会将值展开到发送给模型的提示文本中；将值存储在环境文件中并不能防止这种泄露。仅将插值用于非敏感上下文。
通过
```
docker agent setup
```
或 provider 支持的环境变量提供 provider 凭据。对于自定义 provider，
```
token_key: MY_API_KEY
```
指定的是环境变量的名称，而不是它的值；不要对它进行插值。通过该集成的认证机制配置工具/MCP 凭据，而不是通过提示或模型提供的工具参数。提示应描述已认证的能力，而不包含其机密。不要要求 agent 读取或打印凭据文件或环境值来检查认证。

Related skills

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.

```
references/toolsets-and-providers.md
```
—— 完整的内置工具集列表、MCP 连接模式以及 provider/环境变量表。
```
references/sources.md
```
—— 此技能中每条规则的来源。

Assets

资产

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

```
assets/team-agent.yaml
```
—— 一个可运行的多 agent 团队模板（协调者 + 编码者 + 审查者）。

Checks

检查

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

在运行 agent 之前，请遵循
```
checks/verification.md
```
确认其解析后的配置、暴露的工具和 provider 连接性，然后进行冒烟测试。