使用 Docker Agent 构建 AI 代理
内容提要
Docker Agent 是 Docker 推出的开源 CLI 插件，可用 YAML 声明式定义 AI 代理，并像容器一样打包、版本化和分发。它支持多模型供应商、多代理协作、MCP 工具和 OCI 镜像仓库共享。教程涵盖安装、单代理配置、添加工具，以及构建由协调者、研究员和写手组成的多代理团队，并建议用官方 schema 校验配置、固定摘要以保证可复现性。
延伸解读
声明式配置与容器化分发
Docker Agent 的核心创新在于将 AI 代理的定义从代码转为 YAML 或 HCL 声明式配置，无需软件工程背景即可构建。代理可像容器镜像一样打包、版本化，并通过 OCI 镜像仓库分发，实现跨环境的一致运行。这种设计让代理成为可移植、可版本控制的工件，便于团队协作和自动化流程。
多代理协作与模型选择
Docker Agent 支持真正的多代理编排，通过 sub_agents 定义团队，协调者使用 transfer_task 将任务委派给专用代理，每个代理可独立选择不同模型供应商（如 Claude、GPT-5）。这种模式适合需要分工协作的复杂任务，而 handoffs 模式则更适合线性管道。多代理配置同样可通过官方 schema 校验，确保结构正确。
安全隔离与工具集成
通过 MCP 工具集，代理可访问外部服务，推荐将 MCP 服务器运行在独立 Docker 容器中，实现安全隔离。内置工具如 filesystem、shell、memory 和 think 提供了文件操作、命令执行、持久化记忆和逐步推理能力。使用 --yolo 标志可自动批准工具调用，但需谨慎，因为它移除了确认步骤，可能带来风险。
配置验证与可复现性
使用官方 agent-schema.json 对 YAML 配置进行 JSON Schema 校验，能提前发现字段错误，确保配置有效。分发代理时，固定摘要（@sha256:...）而非标签（如 latest）可避免每次运行重新解析标签带来的延迟和网络依赖，同时保证行为完全可复现，因为标签可能指向更新后的代理，而摘要则不可变。
Q&A
Docker Agent 是什么？它和 Docker 容器有什么相似之处？
Docker Agent 是 Docker 工程团队构建的开源 Apache 2.0 许可 CLI 插件，以 `docker agent` 命令安装和运行。它允许用 YAML 或 HCL 声明式定义 AI 代理，并像容器一样打包、版本化和分发。相似之处在于：代理定义可以推送到任何 OCI 兼容的注册表，并从那里拉取，就像 Docker 镜像一样。
如何安装 Docker Agent？需要哪些前提条件？
需要三个前提：安装 Docker、一种运行方式、至少一个语言模型的访问权限。安装有三种路径：1) Docker Desktop 4.63 或更新版本已内置插件，直接运行 `docker agent`；2) 通过 Homebrew 安装：`brew install docker-agent`，然后运行 `docker-agent` 或符号链接到 `~/.docker/cli-plugins/docker-agent` 以使用 `docker agent` 形式；3) 从 GitHub Releases 下载二进制文件并同样符号链接。模型设置可选云 API 密钥（如 `export ANTHROPIC_API_KEY=...`）或通过 Docker Model Runner 本地运行。用 `docker agent --help` 确认安装。
如何用 YAML 定义一个最简单的 Docker Agent？
创建一个 `agent.yaml` 文件，包含一个名为 `root` 的代理（入口点必需）。示例： ```yaml agents: root: model: anthropic/claude-sonnet-4-5 description: A helpful coding assistant instruction: | You are an expert software developer. Help users write clean, efficient code. Explain your reasoning step by step. toolsets: - type: filesystem - type: shell - type: think ``` `model` 格式为 `provider/model-name`；`instruction` 是系统提示；`toolsets` 列出能力，如 filesystem、shell、think。运行：交互式 `docker agent run agent.yaml`，或非交互式 `docker agent run --exec agent.yaml "任务"`。
Docker Agent 如何通过 MCP 工具让代理访问外部服务？
Docker Agent 支持 MCP 工具，推荐将 MCP 服务器运行在独立的 Docker 容器中，与主机隔离。在 YAML 中，使用 `toolsets` 下的 `type: mcp` 和 `ref: docker:duckduckgo` 这样的引用，`docker:` 前缀告诉 Docker Agent 在容器内运行该 MCP 服务器，这是官方推荐的安全隔离方式。例如： ```yaml agents: root: model: anthropic/claude-sonnet-4-5 description: Research assistant with memory and web search instruction: | You are a research assistant. Search the web for information, remember important findings, and provide thorough analysis. toolsets: - type: think - type: memory path: ./research.db - type: mcp ref: docker:duckduckgo ``` `memory` 工具集提供持久化存储，`mcp` 工具集添加外部工具。
如何构建一个多代理团队？协调者和子代理如何协作？
在根代理中通过 `sub_agents: [researcher, writer]` 定义子代理，这会自动授予根代理内置的 `transfer_task` 工具。协调者调用 `transfer_task(agent="researcher", task="...", expected_output="...")` 启动子代理的独立会话，等待完成并返回结果。每个代理可指定不同模型（如协调者用 Claude，研究员用 GPT-5）。示例配置包含 root、researcher、writer 三个代理，各自有独立的 instruction 和 toolsets。这与 handoffs 模式不同：handoffs 传递整个对话历史并切换控制，适合流水线；而 transfer_task 适合协调者委托并综合结果。
如何验证 Docker Agent 配置文件的正确性？
使用项目仓库中的 `agent-schema.json` 进行 JSON Schema 验证。示例 Python 代码： ```python import yaml, json, jsonschema with open("agent-schema.json") as f: SCHEMA = json.load(f) def validate(yaml_text: str, label: str): config = yaml.safe_load(yaml_text) try: jsonschema.validate(instance=config, schema=SCHEMA) print(f"[{label}] VALID against agent-schema.json") except jsonschema.ValidationError as e: print(f"[{label}] SCHEMA VALIDATION ERROR: {e.message}") ``` 该验证器能捕获错误，例如使用不存在的工具集类型会失败。所有示例配置均通过验证。
如何打包和共享 Docker Agent？使用标签和摘要引用有何区别？
完成的代理可以推送到任何 OCI 兼容注册表，并用 `docker agent run myorg/agent:tag` 拉取运行。代理也可以作为子代理跨注册表引用，例如 `reviewer:docker.io/myorg/review-agent@sha256:...`。使用标签（如 `myorg/agent:latest`）会在每次运行时重新解析，增加启动延迟和失败风险；使用不可变摘要（`@sha256:...`）则直接从本地缓存提供，启动快且行为可复现，因为标签可能指向更新后的代理，而摘要永远不会。
