Docker Agent 实战：用 YAML 编排 AI 代理

今年 10 月，Docker 在 Docker Desktop 4.63 中悄悄塞进了一个重磅能力：docker-agent。它是一套开源的 AI 代理框架，最大的特点是把”代理”变成了一种可被声明、被分发、被运行的基础设施。你只需要写一份 YAML，描述代理使用哪个模型、遵循什么指令、能调用哪些工具，就可以用一条命令把它跑起来，无需写一行 Python。本文带你从零上手 docker-agent，并落地一个可复用的多代理工作流。

一、docker-agent 解决什么问题

过去一年，AI 代理（Agent）从概念走向生产，但落地方式高度碎片化：有的用 Python SDK 手写编排，有的依赖特定云厂商的运行时。docker-agent 的思路很”Docker”——把代理当成镜像一样的东西来对待。它的三个核心主张是：

• 声明式定义：用 YAML 描述 model、instructions、tools，不写胶水代码。
• 多代理编排：根代理可以派生出拥有独立模型、独立工具集、独立指令的子代理，任务层层委派。
• OCI 分发：代理定义可以推送到任意 OCI 镜像仓库，跨环境拉取运行，和容器镜像一样自然。

这意味着团队可以把”代码审查代理””运维排障代理”打包成制品，在开发机、CI、生产跳板机上用同一份定义运行，避免”在我机器上能跑”的尴尬。如果你已经用 Docker 编排 管理过服务，理解 docker-agent 会非常顺手。

二、核心概念速览

一个代理定义通常包含三块：model（用哪个大模型）、instructions（系统级人设与规则）、tools（能调用的能力，如 shell、文件系统、HTTP）。docker-agent 的差异化在于”多代理”——根代理（root agent）可以在运行时派生子代理，把复杂任务拆给专人。

三、快速开始：第一个代理

升级到 Docker Desktop 4.63 后，docker-agent 以 CLI 插件形式随附。下面这份 agent.yaml 定义了一个最朴素的”翻译代理”。

# agent.yaml
name: translator
model: gpt-5.5
instructions: |
  你是一名专业技术翻译，把用户输入的英文段落翻译为简洁的中文，
  保留专有名词与代码不变，不要添加解释。
tools:
  - fs

随后用一条命令启动它（具体子命令以本地 docker agent --help 为准，不同小版本可能微调）：

# 运行代理定义文件
docker agent run agent.yaml

# 带对话输入
echo "Explain the difference between Pod and Deployment." | docker agent run agent.yaml

相比自己用 SDK 拼提示词、接模型 API、写循环，docker-agent 把”定义即运行”做到了极致。想把它接入更复杂的 AI 工作流，可以参考我们之前写的 Dify + Ollama 本地大模型 的编排思路。

四、多代理编排实战

docker-agent 真正的亮点在”根代理派生子代理”。例如一个”发布助手”根代理，下面挂”变更说明子代理”和”回滚检查子代理”，各自用不同模型与工具，互不干扰。定义方式依然是一份 YAML：

# release-agent.yaml
name: release-assistant
model: claude
instructions: |
  你是发布协调者。先让子代理分别评估"变更说明"与"回滚风险"，
  再综合给出发布建议。不要自己直接执行部署。
agents:
  - name: changelog-agent
    model: gpt-5.5
    instructions: 根据 git diff 生成用户视角的变更说明。
    tools: [shell, fs]
  - name: rollback-agent
    model: gemini
    instructions: 评估本次发布的可回滚性与风险点。
    tools: [shell]
tools:
  - shell
  - fs

运行根代理后，它会按照指令把任务委派给子代理，并把各自结果汇总。这种”分而治之”的结构，正好对应生产里”专人专岗”的协作方式，也避免了单一庞大提示词难以维护的问题。

五、接入多种模型后端

docker-agent 不绑定某一家厂商，官方支持 OpenAI、Anthropic、Google Gemini、AWS Bedrock，以及本地的 Docker Model Runner。你只需在环境变量或配置中提供对应密钥，代理定义里切换 model 字段即可。这对需要 多模型路由与成本管控 的团队尤其友好。

六、把代理打包成 OCI 制品

和容器镜像一样，docker-agent 支持把代理定义推送到任意 OCI 镜像仓库，并在别处拉取运行。这让”代理”成为可版本化、可审计、可分发的软件制品，而不是散落在笔记本里的 YAML 文件。

# 将代理推送到你的镜像仓库（命令形态以 docker agent --help 为准）
docker agent push myregistry.io/agents/reviewer:latest

# 在另一台机器/CI 中拉取并运行
docker agent pull myregistry.io/agents/reviewer:latest
docker agent run myregistry.io/agents/reviewer:latest

把代理制品纳入镜像仓库后，就能像管理应用镜像那样管理”智能体”，配合 GitHub Actions 流水线 实现代理的自动构建与发布。

七、与 CI/CD 集成

把代理跑在 PR 上做自动代码审查，是 docker-agent 最自然的使用方式之一。下面是一段 GitHub Actions 片段，在每次 PR 时启动审查代理：

# .github/workflows/agent-review.yml
name: agent-review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run docker-agent reviewer
        run: |
          docker agent run .github/agents/reviewer.yaml             --input "$(git diff origin/main...HEAD)"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

在编辑器侧，你也可以把代理定义文件交给 VS Code 管理，借助 YAML 插件获得补全与校验，形成”本地编写 → 仓库版本化 → CI 自动跑”的闭环。

八、实战场景举例

1. 代码审查代理

子代理读取 diff，按”安全性、可读性、性能”三维度给建议，根代理汇总成评审意见贴回 PR。比纯 lint 更懂业务上下文。

2. 运维排障代理

给代理开放受限的 shell 与日志读取工具，让它根据告警自动初步定位，并给出排查清单。注意：务必把写权限与密钥访问关掉，只留读能力。

九、安全边界与避坑清单

代理能调用工具，就意味着它拥有”行动力”，安全边界必须前置设计：

• 最小工具集：只给当前任务必需的 tools，审查代理不该有写库权限。
• 密钥隔离：模型密钥走环境变量/密钥管理，不要写进 YAML 提交仓库。
• 人工确认：涉及部署、删除等写操作的步骤，默认要求人审批。
• 网络出口：限制代理可访问的域名，防止数据外泄。
• 版本锁定：代理定义与模型版本一起纳入版本控制，避免”悄悄变聪明”。

十、小结与落地清单

docker-agent 把”AI 代理”从一段难以维护的脚本，变成了可声明、可分发、可治理的基础设施。对已经深度使用 Docker 的团队来说，它是目前门槛最低、最贴近现有工作流的代理框架之一。下一步，可以把它和你们既有的编排、监控体系打通，让代理真正成为流水线里可靠的一环。