docker-agent-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Agent: Serving, Sharing, and Evaluating

Docker Agent：服务、分享与评估

Overview

概述

This skill owns the integration surface of Docker Agent: making an agent reachable by other software (

docker agent serve

), distributing it through an OCI registry the way container images are distributed (

docker agent share

), and proving it still behaves after a change (

docker agent eval

). It assumes the agent config already exists — see

docker-agent-config

for authoring it, and

docker-agent-run

for interactive/local invocation.

此 skill 负责 Docker Agent 的集成面：使代理可被其他软件访问（

docker agent serve

），以容器镜像分发的方式通过 OCI 注册表分发代理（

docker agent share

），以及证明代理在变更后仍然正常运行（

docker agent eval

）。它假定代理配置已存在——编写配置请参阅

docker-agent-config

，交互式/本地调用请参阅

docker-agent-run

。

When to use this skill

何时使用此 skill

Activate this skill when:

The user wants an agent reachable over MCP, an OpenAI-compatible chat endpoint, a plain HTTP API, or A2A/ACP.
The user wants to publish an agent to Docker Hub (or any OCI registry) or pull one someone else published.
The user wants automated evaluations (regression tests) for an agent, or wants to gate CI on eval results.

在以下情况激活此 skill：

用户希望通过 MCP、OpenAI 兼容的聊天端点、纯 HTTP API 或 A2A/ACP 使代理可被访问。
用户希望将代理发布到 Docker Hub（或任何 OCI 注册表），或拉取他人发布的代理。
用户希望为代理进行自动化评估（回归测试），或希望根据评估结果对 CI 进行门禁。

Do not use this skill when

何时不要使用此 skill

Do not use this skill when:

The task is authoring the agent.yaml itself (models, toolsets, sub_agents) — use
```
docker-agent-config
```
.
The task is running the agent interactively on a developer's machine, choosing
```
--safety
```
/
```
--sandbox
```
, or aliases — use
```
docker-agent-run
```
.

在以下情况不要使用此 skill：

任务是编写 agent.yaml 本身（models、toolsets、sub_agents）——请使用
```
docker-agent-config
```
。
任务是在开发者的机器上交互式运行代理、选择
```
--safety
```
/
```
--sandbox
```
或别名——请使用
```
docker-agent-run
```
。

Core guidance

核心指导

Serving an agent

服务代理

Five server modes, each with its own default loopback listen address — never expose any of them beyond loopback without authentication:

Mode	Default listen	Auth flag	Has `--safety` ?
`serve mcp`	`127.0.0.1:8081`	`--auth-token` (only with `--http` )	Yes (only with `--http` )
`serve api`	`127.0.0.1:8080`	`--auth-token`	No
`serve chat`	`127.0.0.1:8083`	`--api-key` / `--api-key-env`	Yes
`serve a2a`	`127.0.0.1:8082`	`--auth-token`	Yes
`serve acp`	(stdio only)	n/a	No

bash

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

```
serve mcp
```
defaults to stdio transport (for local clients like Claude Desktop); pass
```
--http
```
only when you need a network-reachable MCP endpoint, and set
```
--auth-token
```
whenever you do.
Binding any server flag to a non-loopback address without an auth token/key is refused;
```
--insecure-no-auth
```
exists to force it and must be treated as a deliberate, documented exception, never a default.
```
serve mcp
```
(with
```
--http
```
),
```
serve chat
```
, and
```
serve a2a
```
expose
```
--safety
```
(
```
strict
```
/
```
balanced
```
/
```
restricted
```
/
```
autonomous
```
); Docker's docs state it defaults to
```
restricted
```
for these modes when unset.
```
serve api
```
and
```
serve acp
```
expose no
```
--safety
```
flag at all. Never raise
```
--safety
```
to
```
autonomous
```
on a network-reachable listener; if a served agent must approve more, prefer
```
balanced
```
and keep auth enabled.
```
serve api
```
accepts a directory instead of a single file: every
```
.yaml
```
/
```
.yml
```
/
```
.hcl
```
in it is exposed under
```
/api/agents
```
. Use
```
--session-workingdir-root
```
to confine session working directories when the server is reachable by more than one user.

五种服务器模式，每种模式都有自己的默认回环监听地址——未经认证时，切勿将其中任何一个暴露到回环之外：

模式	默认监听地址	认证标志	是否有 `--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）	不适用	否

bash

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
```
；如果被服务的代理必须批准更多操作，请优先使用
```
balanced
```
并保持认证启用。
```
serve api
```
接受目录而非单个文件：目录中的每个
```
.yaml
```
/
```
.yml
```
/
```
.hcl
```
都会在
```
/api/agents
```
下暴露。当服务器可供多个用户访问时，使用
```
--session-workingdir-root
```
来限制会话工作目录。

Sharing agents via OCI registries

通过 OCI 注册表分享代理

Push and pull agent configs the same way you push and pull images — same registry, same

docker login

auth:

bash

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

```
instruction_file
```
contents are inlined into the pushed artifact automatically, so a published agent stays self-contained — you do not need to bundle the referenced files separately.
Pin
```
sub_agents
```
that reference the pushed artifact to a digest (
```
name@sha256:...
```
) once published, to avoid a per-run registry lookup and to guarantee the exact config a consumer gets.
Use
```
--force
```
on
```
share pull
```
only when you intend to overwrite a local copy that already exists; without it, an existing local config is left untouched.

像推拉镜像一样推拉代理配置——相同的注册表、相同的

docker login

认证：

bash

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

```
instruction_file
```
的内容会自动内联到推送的制品中，因此发布的代理保持自包含——你无需单独打包引用的文件。
发布后，将引用该推送制品的
```
sub_agents
```
固定到摘要（
```
name@sha256:...
```
），以避免每次运行时的注册表查询，并确保消费者获得确切的配置。
仅当你打算覆盖已存在的本地副本时，才对
```
share pull
```
使用
```
--force
```
；若不使用，已有的本地配置将保持不变。

Evaluating agents

评估代理

Evals live in an
```
evals/
```
directory next to the agent config by default; each eval is one JSON session file capturing a user message, the recorded tool calls, and an
```
evals
```
object with the scoring criteria.
Create eval sessions from real conversations rather than hand-writing JSON: run the agent interactively, then use the
```
/eval
```
slash command in the TUI to save the session, and edit in
```
relevance
```
/
```
size
```
/
```
assertions
```
criteria afterward.
Four scoring dimensions: Tool Calls (F1 against the recorded sequence), Relevance (LLM-judge,
```
--judge-model
```
, default
```
anthropic/claude-opus-5
```
), Size (S/M/L/XL response-length bucket), and Assertions (deterministic checks; see the complete assertion-type list in
```
references/eval-format.md
```
). Prefer assertions over
```
relevance
```
when a check can be exact: they need no judge model and are deterministic, not approximation-prone.
Evaluations run inside containers for isolation; a Docker-compatible runtime is required. Dedicated provider API keys (
```
ANTHROPIC_API_KEY
```
/
```
OPENAI_API_KEY
```
) are forwarded automatically.
```
GITHUB_TOKEN
```
/
```
GH_TOKEN
```
are not forwarded automatically (they're broad host credentials, not model keys) — pass them explicitly with
```
-e GITHUB_TOKEN
```
when an agent's provider needs one (e.g.
```
github-copilot
```
).
Gate CI on regressions, not on absolute scores, with
```
--baseline
```
:
bash
```
docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json --regression-tolerance 0.05
```
A previously-passing eval that now fails always gates regardless of tolerance; cost changes are reported but never gate. A baseline or run with zero evaluations (e.g. an
```
--only
```
pattern matching nothing) is rejected rather than reported as passing.
Use
```
--keep-containers
```
plus your runtime's
```
exec
```
to inspect a failed eval's container; the eval's
```
.db
```
session file holds the full conversation for offline debugging.

默认情况下，评估（evals）位于代理配置旁边的
```
evals/
```
目录中；每次评估都是一个 JSON 会话文件，捕获用户消息、记录的工具调用以及包含评分标准的
```
evals
```
对象。
从真实对话中创建评估会话，而不是手写 JSON：交互式运行代理，然后在 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
```
不会自动转发（它们是广泛的主机凭据，不是模型密钥）——当代理的提供商需要时（例如
```
github-copilot
```
），请使用
```
-e GITHUB_TOKEN
```
显式传递。
使用
```
--baseline
```
基于回归而非绝对分数对 CI 设门禁：
bash
```
docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json --regression-tolerance 0.05
```
之前通过而现在失败的评估，无论容差如何，始终构成门禁；成本变化会被报告但不会构成门禁。评估次数为零的基线或运行（例如
```
--only
```
模式未匹配到任何内容）会被拒绝，而不会被报告为通过。
使用
```
--keep-containers
```
加上运行时的
```
exec
```
来检查失败评估的容器；评估的
```
.db
```
会话文件包含完整对话，可用于离线调试。

Verify

验证

After changing a served agent's config, re-run its evals with the same explicit
```
--safety
```
value used in the deployment before restarting the listener — this catches an approval-policy regression before it reaches traffic. If a rollout must be rolled back, restore the prior config and safety flag; never restore an unauthenticated listener as a rollback shortcut.

更改被服务代理的配置后，在重新启动监听器之前，使用部署中相同的显式
```
--safety
```
值重新运行其评估——这能在审批策略回归影响流量之前捕获它。如果必须回滚发布，请恢复先前的配置和安全标志；切勿恢复未认证的监听器作为回滚捷径。

Related skills

References

参考资料

```
references/eval-format.md
```
— full eval session JSON schema and CLI flag table.
```
references/sources.md
```
— provenance of every rule in this skill.

```
references/eval-format.md
```
— 完整的评估会话 JSON 模式和 CLI 标志表。
```
references/sources.md
```
— 此 skill 中每条规则的来源。

Assets

资源

```
assets/eval-session-example.json
```
— a minimal eval session file to copy and adapt.

```
assets/eval-session-example.json
```
— 一个可供复制和调整的最小评估会话文件。

Checks

检查

```
checks/verification.md
```
— Verification runbook for serving, sharing, and evaluating an agent.

```
checks/verification.md
```
— 用于服务、分享和评估代理的验证运行手册。

docker-agent-deploy

Original

Translation

Docker Agent: Serving, Sharing, and Evaluating

Docker Agent：服务、分享与评估

Overview

概述

When to use this skill

何时使用此 skill

Do not use this skill when

何时不要使用此 skill

Core guidance

核心指导

Serving an agent

服务代理

Sharing agents via OCI registries

通过 OCI 注册表分享代理

Evaluating agents

评估代理

Verify

验证

Related skills

相关 skills

References

参考资料

Assets

资源

Checks

检查