docker-agent-config

Docker Agent 配置

概述

Docker Agent（CLI 为 docker agent，开源项目为 cagent） 会运行在 YAML 文件中声明的 AI Agent，而不是应用代码。本技能负责 agent.yaml 工件：agents 部分（每个条目的 model、instruction， 以及各自的 toolsets/sub_agents）、从 Agent 引用的顶层 models/providers 部分，以及可通过 use_commands 选择启用的顶层 commands 组。本技能不涵盖调用 CLI 或提供/共享配置——请参阅相关 技能。

何时使用此技能

在以下情况下启用此技能：

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

不要在以下情况下使用此技能

在以下情况下不要使用此技能：

• 任务涉及运行 CLI（docker agent run 标志、--safety、--sandbox、别名、工作树）——请使用 docker-agent-run。
• 任务涉及将 Agent 公开为服务（serve mcp/api/a2a/acp/chat）、分发 Agent（share push/pull）或评估 Agent（评估会话、--baseline 回归门控）——请使用 docker-agent-deploy。
• 任务涉及与 Docker Agent 无关的通用 Dockerfile 或 Compose 服务——请使用 docker-build-strategies 或 docker-compose-patterns。

核心指南

文件结构

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

  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；这样可以让差异聚焦于行为，而不是 YAML 转义。instruction 和 instruction_file 不能同时使用。 从 OCI 引用或 URL 加载的 Agent 不支持 instruction_file——请在此类情况下使用内联的 instruction。

模型和提供方

• 设置模型有两种方式：内联 provider/model 简写，或在顶层 models: 下定义引用 provider 的命名条目。只要需要 temperature、max_tokens、thinking_budget，或要在多个 Agent 之间 复用模型，就使用命名形式。

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

• 内置提供方键：openai、anthropic、google、amazon-bedrock、 dmr（Docker Model Runner，本地，无需 API 密钥）、ollama（本地）。还有数十种 其他内置别名（mistral、groq、xai、together、 azure、github-copilot、openrouter 等）——每种都需要对应的 <PROVIDER>_API_KEY 格式环境变量；运行 docker agent models --all 查看 可解析的提供方，并运行 docker agent setup 以交互方式注册凭据， 而不是手动编辑环境变量。
• 切勿在 agent.yaml 中硬编码 API 密钥。提供方凭据应来自 环境变量（自定义提供方使用 token_key），或来自 docker agent setup 写入的 ~/.config/cagent/.env。
• 对于必须离线运行或不得向第三方发送数据的 Agent，优先使用 dmr/<model>；它不产生费用，也不需要凭据。只有在任务需要时才使用付费云提供方。
• 对于对韧性要求较高的 Agent，设置 fallback，以免提供方中断或达到速率限制时 导致运行停止：

  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：

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

工具集

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

  toolsets:
    - type: filesystem
    - type: shell
  

• 如果 Agent 只描述计划，却从未执行，请添加 type: todo （或 shell）——这通常表明 Agent 缺少执行所需的工具，而不是模型问题。
• 对于外部工具，优先选择 Docker MCP 目录中的 MCP 服务，而不是定制集成——它以容器方式运行，可供多个 Agent 重用：

  toolsets:
    - type: mcp
      ref: docker:duckduckgo
  

  也支持本地 stdio 和远程 HTTP/SSE MCP 服务；请参阅 references/toolsets-and-providers.md。
• 当 Agent 拥有许多工具集且启动延迟很重要时，在工具集（无论是否为 MCP）上使用 defer: true，即可按需加载其工具，而非在启动时加载。
• 在 Agent 上设置 readonly: true，可将其使用的所有工具集限制为只读工具——适用于不得修改任何内容的审查/分析 Agent。

多 Agent 团队

• 协调器通过 sub_agents: [name, ...] 分配任务；列出子 Agent 会自动为父级启用 transfer_task 工具。

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

  使用 assets/team-agent.yaml 获取完整、可运行的团队配置，其中包括审查员的 readonly: true 限制。改编模板时请保留此限制；仅使用 filesystem 工具集也会开放写入权限。
• sub_agents 也接受外部 OCI 引用（myorg/agent:tag）。 在生产配置中，将外部引用固定到摘要（name@sha256:...），以跳过标签每次运行都会触发的注册表查询。
• 委派任务并获取干净、隔离的结果时，使用 transfer_task（通过 sub_agents）；仅当你希望用户在会话剩余时间内成为该 Agent 时，才使用带有 agent: 字段的 commands: 条目。

安全与卫生

• 对任何使用 shell/fetch 工具处理不可信输入的 Agent，设置 redact_secrets: true。此设置会从工具参数、发出的消息和工具输出中清除可识别的密钥模式。这是纵深防御措施，并非保证：任意密码、令牌或客户数据可能无法被检测到。
• 对任何自主循环的 Agent 设置 max_iterations（默认值为无限），以限制成本并防止失控循环；max_consecutive_tool_calls（默认值为 5）已能防止重复调用形成循环。
• 不要将凭据、令牌和敏感客户数据放入 instruction、instruction_file 和命令提示中，无论是直接写入还是插值写入都不行。${env.VAR} 会将值展开到发送给模型的提示文本中；将值存储在 env 文件中也无法避免泄露。仅对非敏感上下文使用插值。
• 通过 docker agent setup 或提供方支持的环境变量提供提供方凭据。对于自定义提供方，token_key: MY_API_KEY 指定的是环境变量名称，而非其值；不要对其进行插值。通过相应集成的身份验证机制配置工具/MCP 凭据，不要通过提示或模型提供的工具参数配置。提示应描述已通过身份验证的功能，不得包含密钥。不要要求 Agent 读取或打印凭据文件或环境变量值来检查身份验证。

相关技能

• 要运行 Agent（docker agent run、安全模式、沙盒、别名），请使用 docker-agent-run。
• 要提供服务、共享或评估 Agent，请使用 docker-agent-deploy。

参考资料

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

资源文件

• assets/team-agent.yaml — 可运行的多 Agent 团队模板（协调器 + 编码 Agent + 审查员）。

检查

• 运行 Agent 前，请按照 checks/verification.md 确认解析后的配置、已开放的工具和提供方连接，然后进行冒烟测试。