用 Docker 官方 docker-agent 组建多智能体团队：YAML 声明式编排、MCP 工具接入与 OCI 分发实操

# 方式一：Docker Desktop 4.63+ 已内置，升级后验证
cagent version
# （内置插件版本用：docker agent version）

# 方式二：macOS 独立安装
brew install cagent

# 方式三：Windows
winget install Docker.cagent
# 或到 GitHub Releases 下载对应平台二进制

# 配置至少一家模型的 API Key
export OPENAI_API_KEY=sk-...
# 或 ANTHROPIC_API_KEY / GOOGLE_API_KEY 等，按 models 块所用 provider 配

项目 Apache-2.0 协议，全部功能免费，成本只来自模型 API 调用。兼容性上官方有明确策略：如果你的机器上已经用 Homebrew 装过 cagent，brew 版优先于 Docker Desktop 内置版生效——避免升级后行为突变，想切内置版卸掉 brew 版即可。

# hello-agent.yaml
version: "2"
models:
  gpt:
    provider: openai
    model: gpt-4o-mini
    max_tokens: 1000
agents:
  root:
    model: gpt
    description: "A friendly greeting agent"
    instruction: |
      You are a helpful assistant that creates personalized greetings.
      Ask the user their name and create a warm welcome message.

# 运行
cagent run hello-agent.yaml

# 模型可简写在 agent 上，省掉 models 块
#   model: openai/gpt-5-mini

# 问答式交互生成一份配置骨架
cagent new

# 官方目录里直接跑现成 Agent
cagent run agentcatalog/pirate

cagent run 启动终端交互界面，你说话它干活，工具调用过程实时可见。models 块集中声明的好处是换模型只改一处；快速实验用简写形式更顺手。cagent new 会问你名字、职责、用什么模型，然后生成合法配置——不确定 YAML 字段怎么写时，让它先给你打个样，再照官方配置参考改。

# bug-investigator.yaml（节选）
version: "2"
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 64000
agents:
  root:
    model: claude
    description: 故障排查协调员
    instruction: |
      分析用户给出的报错与代码上下文，先定位根因。
      需要查资料时委派 researcher；确定根因后委派 fixer 修复；
      修复完成让 tester 验证。最后汇总一份带根因与验证结论的报告。
    sub_agents: [researcher, fixer]
    toolsets:
      - type: think
      - type: todo
  researcher:
    model: claude
    description: 文档与同类问题检索专家
    instruction: |
      用搜索工具查官方文档与相似 issue，返回带出处的结论。
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
  fixer:
    model: claude
    description: 代码修复执行者
    instruction: |
      按 root 给出的根因修改代码，保持最小改动，说明改了什么。
    toolsets:
      - type: filesystem

运行 cagent run bug-investigator.yaml，贴一段报错试试：root 先用 think 拆解问题，需要外部信息就把检索任务转给 researcher（它只有搜索工具，改不了文件），拿到结论后把修复任务转给 fixer，最后自己汇总。官方文档的示例是一个四人版（加 tester 生成测试），架构相同——每个专家一个窄职责、一套小工具集，协调者只做拆解与汇总。

toolsets:
  - type: think                 # 分步推理
  - type: todo                  # 任务清单
  - type: memory                # 持久记忆
    path: "./memory.db"
  - type: mcp
    ref: docker:duckduckgo      # 写法A：Docker Hub MCP 目录直连
  - type: mcp                   # 写法B：命令拉起任意 MCP Server
    command: uvx
    args: ["duckduckgo-mcp-server"]
  - type: mcp                   # 写法C：docker mcp gateway 聚合多个 Server
    command: docker
    args: ["mcp", "gateway", "run", "--servers=duckduckgo"]

三种 MCP 写法按场景选：ref 最省事，前提是目录里恰好有；本地或小众 Server 用 command/args 拉起；要一次接一串 Server 就走网关聚合。10 月 7 日同步发布的 v1.149.0 还新增了从公共 GitHub 仓库加载 Skills 的能力——技能包（SKILL.md 那一套）可以直接喂给团队里的 Agent。

# Zed 编辑器 settings 里把 cagent 配成 agent server
"agent_servers": {
  "cagent": {
    "command": "cagent",
    "args": ["acp", "./your-agent.yaml"]
  }
}

# 手动验证 ACP 模式是否正常拉起
cagent acp golang_developer.yaml

ACP 解决的是「每个编辑器都要给每个 Agent 做定制集成」的碎片化问题：协议标准化之后，YAML 里定义的团队直接出现在编辑器会话里，工具调用确认、文件编辑追踪都有现成 UI。官方博客的类比很到位——这层关系类似 LSP 之于语言服务器。编码向的团队（官方仓库里就带着 golang_developer.yaml 示例）可以把「架构师审查 + 实现者改码」的组合直接挂进 Zed 用。

# 官方 README「Package & share」：push/pull 到任意 OCI 注册中心
# 具体命令以官方 docs 对应章节为准，形态类似：
# cagent push <registry>/<team>:<tag>
# cagent pull  <registry>/<team>:<tag>

# 本地模型：Docker Model Runner
# models 块 provider 指向 Docker Model Runner，无需云 API Key
# 代价：CPU 推理延迟明显（秒级到分钟级），建议 GPU 机型

OCI 分发是 docker-agent 与 Docker 生态咬合最深的一环：Agent 定义进注册中心后，同事 pull 下来一条命令就能跑，和拉镜像的体验完全一致。对合规团队，Docker Model Runner 路线让整条链路（配置、推理、工具执行）都不出本机。发布节奏要留意：项目十天内连发多个小版本（v1.149.0 当天新增 GitHub Skills 加载、Models Gateway 默认路由评估器、OpenAI Decisions 评估后端），跑不通先查官方 README 与 examples/ 目录是否已更新。