Docker Agent YAML 教程：一份配置 5 步跑通智能体

Docker Agent 是 Docker 官方的开源智能体框架（即原 cagent，Docker Desktop 4.63 起更名）：用一份 YAML 声明式定义智能体的模型、角色指令与工具，再用 OCI 仓库像容器镜像一样分发。全程 5 步、免费开源，本教程带你从安装一路跑到分享。

前置准备：安装与模型密钥

Docker Agent 的安装有两条路，任选其一：

• Docker Desktop 4.63 及以上版本直接内置，开箱即用
• Docker Engine 或自定义安装：macOS 用 brew install docker-agent，Windows 用 winget install Docker.Agent，或从 GitHub releases 下载预编译二进制，把 docker-agent 放到 ~/.docker/cli-plugins 目录后即可用 docker agent 命令（也可作为独立二进制直接运行），官方安装说明见 Docker Agent 文档

接着准备模型。按你想用的厂商导出对应密钥：

export ANTHROPIC_API_KEY=你的密钥   # Claude 系列模型
export OPENAI_API_KEY=你的密钥      # OpenAI 模型
export GOOGLE_API_KEY=你的密钥      # Gemini 模型

不想配云厂商密钥的话，可以用 Docker Model Runner 拉本地模型（dmr/ 前缀的模型不需要密钥），适合隐私敏感的场景。

第 1 步：一条命令快速试跑

先不写任何配置，直接跑默认智能体：

docker agent run

这会启动一个带交互界面的通用助手，可以直接对话。想用向导生成配置：

docker agent new
# 或直接指定模型
docker agent new --model openai/gpt-5

docker agent new 会在当前目录生成一个 agent.yaml，保存后就能运行。

第 2 步：手写 agent.yaml 最小配置

配置文件是核心资产，结构如下（来自官方快速开始的最小示例）：

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: 编程助手
    instruction: |
      你是资深软件开发者，帮用户写干净高效的代码，
      并解释你的思路。
    toolsets:
      - type: filesystem
      - type: shell
      - type: think

instruction 怎么写好，可以参考站内 Gemini Skills 用法（斜杠调用 3 步）与 Figma Agent 提示词模板（6 条可直接复制的指令），先想清楚角色再落笔。字段拆解：

• agents.root：主智能体，整个配置必须有它
• model：模型引用，格式是 厂商/模型 名称，例如 anthropic/claude-sonnet-4-5、openai/gpt-5-mini
• description：一句话角色说明，用于上下文识别
• instruction：角色指令，写清楚这个智能体负责什么、按什么规则行事
• toolsets：工具集，filesystem 读写文件、shell 执行命令、think 逐步推理

想用 HCL 也可以，同一份配置写成 agent.hcl 效果等价，团队偏好哪种用哪种。

第 3 步：跑起来并验证

docker agent run agent.yaml

进入交互界面后，用三个问题验证它真的在工作：

1. 列出当前目录的文件
2. 写一个抓取天气数据的 Python 脚本
3. 解释某个代码文件在做什么

非交互场景用 --exec 跑一次性任务：

# 问单个问题
docker agent run --exec agent.yaml "为一个 Node.js 应用写 Dockerfile"
# 管道输入
echo '报错日志内容' | docker agent run --exec agent.yaml "这段日志哪里出了问题？"

信任智能体的工具调用时，可以加 --yolo 自动批准所有工具调用；想系统学一遍操作，运行 docker agent getting-started 有内置导览。

第 4 步：进阶：多智能体、MCP 工具与记忆

Docker Agent 真正的价值在多智能体协作：root 负责统筹，sub_agents 各干一行。下面是一个可直接复制的双智能体调试团队：

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: bug 调查员
    instruction: |
      分析报错信息、堆栈与代码，定位 bug 根因，
      说明哪里错了、为什么错，把修复交给 fixer。
    sub_agents: [fixer]
    toolsets:
      - type: filesystem
      - type: mcp
        ref: docker:duckduckgo
  fixer:
    model: openai/gpt-5-mini
    description: 修复实施员
    instruction: |
      按调查员的诊断写修复，做最小改动并补测试。
    toolsets:
      - type: filesystem
      - type: shell

要点：

• sub_agents 列出的子智能体可以有各自的模型、指令与工具，也可以继续挂自己的子智能体
• 每个智能体上下文独立，不共享知识，靠 root 转交（多智能体协作的产品形态可参考站内 Manus Cue 是什么）
• MCP 工具用 ref: docker:duckduckgo 这种语法，Docker 会在容器里跑对应的 MCP server，隔离又安全，需要 Docker Desktop
• 给智能体加持久记忆：toolsets 里加 - type: memory 并指定 path（如 ./research.db）
• 复杂推理任务可以加 think 工具，让模型先逐步推理再动手

MCP 是接外部工具的标准口，配置 MCP 的通用思路可以参考站内的 Gemini CLI MCP 配置（一条命令 5 步接好）。

第 5 步：用 OCI 仓库分发

智能体配置会被打包成 OCI 制品，像镜像一样推送和拉取：

# 推送：把本地配置发布到仓库（不存在会自动创建）
docker agent share push ./debugger.yaml myusername/debugger

# 拉取：从仓库取回别人的智能体
docker agent share pull myusername/debugger

# 直接运行仓库里的智能体，不用本地 YAML
docker agent run myorg/agent:tag

仓库用 Docker Hub 或任何 OCI 兼容 registry 都行。对已经在用容器镜像的团队，这条分发链路和现有流水线完全对齐，拉取即用，版本化管理。

对团队来说，这条链路最大的价值是「配置即产物」：智能体的模型选择、工具权限和角色指令都锁在 YAML 里，版本跟随仓库走，回滚就是 pull 上一个 tag。新人上手也不用从零搭环境，一条 docker agent run 仓库地址就能拿到和团队一致的智能体。

验证成功与常见报错速查

跑通的标准：docker agent run 能进入交互界面、智能体能完成你指派的任务、share push 后另一台机器能 pull 回来运行。遇到问题先对照下表：

官方完整的排障手册在 Docker Agent troubleshooting 页面，以上是最常见的几种。