docker-agent-deploy

Docker Agent：服务、共享与评估

概述

此技能负责 Docker Agent 的集成接口：让其他软件能够访问 Agent（docker agent serve），通过 OCI registry 分发 Agent，就像分发容器镜像一样（docker agent share），并在变更后验证其行为是否正常（docker agent eval）。 此技能假定 Agent 配置已存在——有关如何编写配置，请参阅 docker-agent-config；有关交互式／本地调用，请参阅 docker-agent-run。

何时使用此技能

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

• 用户希望通过 MCP、兼容 OpenAI 的聊天端点、普通 HTTP API 或 A2A/ACP 访问 Agent。
• 用户希望将 Agent 发布到 Docker Hub（或任何 OCI registry），或拉取他人发布的 Agent。
• 用户希望为 Agent 设置自动化评估（回归测试），或希望根据评估结果控制 CI。

何时不要使用此技能

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

• 任务是编写 agent.yaml 本身（模型、工具集、sub_agents）——请使用 docker-agent-config。
• 任务是在开发者的机器上交互式运行 Agent、选择 --safety／--sandbox 或设置别名——请使用 docker-agent-run。

核心指南

提供 Agent 服务

• 五种服务模式各自有默认的回环监听地址——未经身份验证，绝不要将它们暴露到回环地址之外：

  模式	默认监听地址	身份验证标志	支持 --safety？
  serve mcp	127.0.0.1:8081	--auth-token（仅与 --http 搭配时）	是（仅与 --http 搭配时）
  serve api	127.0.0.1:8080	--auth-token	否
  serve chat	127.0.0.1:8083	--api-key / --api-key-env	是
  serve a2a	127.0.0.1:8082	--auth-token	是
  serve acp	（仅 stdio）	不适用	否

  docker agent serve mcp ./agent.yaml --http --listen 127.0.0.1:9090 --auth-token "$TOKEN"
  

• serve mcp 默认使用 stdio 传输（适用于 Claude Desktop 等本地客户端）；仅在需要可通过网络访问的 MCP 端点时传入 --http，并且务必同时设置 --auth-token。

• 将任何服务标志绑定到非回环地址但未设置身份验证令牌／密钥时，操作会被拒绝；--insecure-no-auth 可强制执行此操作，必须将其视为有意为之且经过文档记录的例外，绝不能作为默认设置。

• serve mcp（搭配 --http）、serve chat 和 serve a2a 支持 --safety（strict／balanced／restricted／autonomous）；Docker 文档指出，这些模式未设置该选项时默认值为 restricted。serve api 和 serve acp 完全不支持 --safety 标志。绝不要在可通过网络访问的监听器上将 --safety 提高到 autonomous；如果服务中的 Agent 需要批准更多操作，优先选择 balanced 并保持启用身份验证。

• serve api 可接受目录而非单个文件：目录中的每个 .yaml／.yml／.hcl 文件都会通过 /api/agents 提供服务。当不止一个用户能够访问该服务时，使用 --session-workingdir-root 限制会话工作目录的范围。

通过 OCI registry 共享 Agent

• 推送和拉取 Agent 配置的方式与推送和拉取镜像相同——使用相同的 registry 和相同的 docker login 身份验证：

  docker agent share push ./agent.yaml docker.io/username/my-agent:latest
  docker agent share pull docker.io/username/my-agent:latest
  

• instruction_file 的内容会自动内联到推送的制品中，因此发布的 Agent 保持自包含——无需单独打包引用的文件。
• 发布后，将引用已推送制品的 sub_agents 固定到摘要 (name@sha256:...)，以避免每次运行时查询 registry，并确保使用者获取的配置完全一致。
• 仅当打算覆盖已存在的本地副本时，才在 share pull 中使用 --force；不使用此选项时，现有本地配置会保持不变。

评估 Agent

• 默认情况下，评估文件位于 Agent 配置旁边的 evals/ 目录中；每个评估都是一个 JSON 会话文件，其中记录了用户消息、工具调用，以及包含评分标准的 evals 对象。
• 根据真实对话创建评估会话，而不是手动编写 JSON：以交互方式运行 Agent，然后在 TUI 中使用 /eval 斜杠命令保存会话，之后再编辑并添加 relevance/size/assertions 标准。
• 四个评分维度：工具调用（与记录的序列进行 F1 比较）、相关性（LLM 评判，--judge-model，默认值为 anthropic/claude-opus-5）、长度（S/M/L/XL 响应长度档位）和断言（确定性检查；完整的断言类型列表请参阅 references/eval-format.md）。如果检查可以精确完成，优先使用断言而非 relevance：断言不需要评判模型，而且结果确定，不容易出现近似偏差。
• 评估在容器内运行以实现隔离；需要兼容 Docker 的运行时。专用提供商 API 密钥（ANTHROPIC_API_KEY/OPENAI_API_KEY）会自动转发。 GITHUB_TOKEN/GH_TOKEN 不会自动转发（它们是范围广泛的主机凭据，而不是模型密钥）——如果 Agent 的提供商需要此类凭据（例如 github-copilot），请使用 -e GITHUB_TOKEN 显式传入。
• 使用 --baseline，让 CI 根据回归而非绝对分数进行拦截：

  docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json --regression-tolerance 0.05
  

  之前通过但现在失败的评估始终会触发拦截，不受容差影响；成本变化会报告，但不会触发拦截。零评估的基线或运行（例如，--only 模式未匹配任何内容）会被拒绝，而不会报告为通过。
• 使用 --keep-containers 和运行时的 exec 检查失败评估所用的容器；评估的 .db 会话文件包含完整对话，可用于离线调试。

验证

• 更改正在提供服务的 Agent 配置后，在重启监听器之前，使用部署时相同的显式 --safety 值重新运行其评估——这样可以在审批策略回归影响流量之前发现问题。如果必须回滚部署，请恢复之前的配置和安全标志；切勿为了简化回滚而恢复未经过身份验证的监听器。

相关技能

• 如需编写或更改底层的 agent.yaml，请使用 docker-agent-config。
• 如需本地/交互式运行、安全模式选择和沙盒设置，请使用 docker-agent-run。

参考资料

• references/eval-format.md — 完整的评估会话 JSON 架构和 CLI 标志表。
• references/sources.md — 此技能中每条规则的来源。

资源文件

• assets/eval-session-example.json — 可复制并修改的最简评估会话文件。

检查项

• checks/verification.md — 提供服务、共享和评估 Agent 的验证操作手册。