使用 Docker 构建可落地运行的 AI 系统——高级 Agent 编排在第 7 章中，你手工构建了 autonomo

在第 7 章中，你手工构建了 autonomous agents——编写 Python controllers、配置 Redis 作为 memory，并用几十行 infrastructure code 把 Docker Compose files 串起来。在第 8 章中，你把多个 models 和 agents 编排成 collaborative systems。这些 approaches 是可行的，而且理解它们非常重要。但坦率地说，对于一个本该很 straightforward 的任务——让一些 agents 跑起来、保持安全，并让它们协作——前面那些工作确实有太多 plumbing 了。

Figure 9.1：为 setup 做了太多 plumbing

本章将覆盖以下主要主题：

使用 Docker Sandboxes 保障 agent execution 安全
使用 Docker Agent 构建 declarative agent teams
使用 kagent 实现 Kubernetes-native orchestration
Production deployment patterns 和 best practices

到本章结束时，你将知道如何为每种 scenario 选择正确的 orchestration tool：从在 laptop 上安全运行的单个 coding agent，到跨 Kubernetes cluster 处理 workloads 的 specialized agents fleet。

Technical requirements

为了跟随本章所有 examples，你需要准备以下内容：

Software：

Docker Desktop 4.58 或更高版本：Docker Sandboxes 的 microVM support 所必需。使用 docker version 验证。
Docker Agent CLI：通过 Homebrew 安装（brew install docker/tap/docker-agent），或从 GitHub releases 安装。
kubectl 和 kind：用于 Kubernetes / kagent sections。可从 https://kind.sigs.k8s.io 安装 kind。
Helm 3.x：用于在 Kubernetes 上安装 kagent。

API keys（Docker Agent 至少需要一个）：

OpenAI API key、Anthropic API key，或 Google Gemini API key。
Docker Model Runner 可以作为 local models 的免费替代方案。

Hardware：

推荐 16 GB RAM（同时运行 sandboxes、LLMs 和 Kubernetes 非常 resource-intensive）。
20 GB free disk space，用于 container images、microVMs 和 model files。

Knowledge prerequisites

本章直接建立在第 7 章和第 8 章之上。你应该理解 agent loop（perceive-reason-plan-act-observe）、container isolation patterns，以及 multi-agent communication。熟悉 YAML configuration 和基本 Kubernetes concepts（pods、services、deployments）会有助于理解 kagent sections。

本章代码示例可在以下位置获取：

https://github.com/PacktPublishing/Operational-AI-with-Docker/tree/main/chap-09

Securing agent execution with Docker sandboxes

Prerequisites 已经处理完毕，现在我们从最根本的 challenge 开始：防止你的 agents 把你的机器搞坏。在第 7 章中，你通过 read-only filesystems、dropped Linux capabilities 和 internal networks 来保护 agents。这对你构建的 monitoring agents 和 data processors 很有效——这些 services 会持续运行在 containers 中，并通过 APIs 与 external systems 交互。

Figure 9.2：Docker sandboxes 与 microVM isolation

但请想想 coding agents。Claude Code、Gemini CLI、Codex——这些 agents 不只是调用 API。它们会 install packages。它们会 rewrite configuration files。它们会运行 arbitrary shell commands。它们会 execute 自己写出来的 code。而且还有一个让人不太舒服的现实：它们有时需要运行 Docker，来测试它们正在构建的 containers。如果你尝试用第 7 章中的 security constraints 做 Docker-in-Docker，你马上会遇到 privileged mode requirements，而这会彻底击败 isolation 的目的。

Docker Sandboxes 采用了一种 fundamentally different approach。它不是把 agents 隔离在共享 host kernel 的 containers 中，而是把每个 agent 运行在一个 dedicated microVM 中——也就是一个轻量级 virtual machine，拥有自己的 kernel、自己的 Docker daemon，以及自己的 filesystem。即使某个 agent 完全攻破了自己的 environment，damage 也会止步于 VM boundary。

Why microVM isolation matters for agents

想想 coding agent 实际会做什么，再把它与你在第 7 章构建的 agents 对比。你的 bug-tracker agent 从 APIs 读取 data，并把 results 存进 Redis。它不会 install npm packages。它不会 rewrite 你的 .bashrc。它不会运行 docker build 来测试刚生成的 Dockerfile。

Figure 9.3：Docker sandbox architecture

Coding agents 会做所有这些事情。让 Claude Code 或 Gemini CLI 直接访问你的 development machine，意味着你是在把 SSH keys、credentials 和 entire project history 交给 AI-generated code 去信任。一次糟糕的 rm -rf 不只是 inconvenience；它可能 wipe 掉 critical business data，把 proprietary source code 暴露给 malicious actors，或者触发一个远远超出本地机器的 supply chain compromise。Container-based isolation 有帮助，但 containers 共享 host kernel——kernel vulnerability 可能允许 escape。而一旦你需要 Docker-in-Docker，你又回到了 privileged mode。

Docker Sandboxes 通过三个 key capabilities 解决这些问题：

每个 sandbox 都运行在自己的 microVM 中，并拥有 dedicated kernel——这是 hard security boundary，而不仅仅是 namespace isolation。
每个 sandbox 都有自己的 Docker daemon，因此 agents 可以 build 和 run containers，而不会 touch 你的 host Docker。
Network allow / deny lists 让你可以精确控制 agent 能访问哪些 domains。

这就是理论。接下来我们真正运行一个 sandbox，看看实践中是什么样子。

Getting started with Docker sandboxes

Docker Sandboxes 要求 Docker Desktop 4.58 或更高版本，并启用 sandboxes feature。验证你的 setup：

docker sandbox --help

docker sandbox command 是你管理 sandboxes 的入口。--help flag 会显示所有 available subcommands。如果你看到 help output 中列出 run、ls、exec、stop 和 rm 等 commands，就说明已经准备好了。如果没有，请更新 Docker Desktop，并确保在 Settings 中启用了 sandboxes feature。

在运行 sandbox 之前，请在 shell configuration 中全局设置 API key。这一点很重要——Docker Sandboxes 使用一个独立于 shell session 运行的 daemon process，因此 inline environment variables 不会生效：

# For Claude Code
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

# Restart Docker Desktop so the daemon picks up the new variable

echo command 会把 export line 追加到你的 shell configuration file 中。source command 会重新加载 configuration，使其立即生效。完成后你必须 restart Docker Desktop——sandbox daemon 会在 startup 时读取 environment variables，而不是动态读取。

现在创建并运行你的第一个 sandbox：

# Create a sandbox for Claude Code in your project directory
docker sandbox run claude ~/my-project

拆解这个 command：docker sandbox run 会创建并启动一个新的 sandbox。claude argument 指定要运行哪个 agent——Docker 为每个 supported agent 都提供了 pre-configured templates。~/my-project argument 指定你的 workspace directory，它会被 sync 到 sandbox 中。

第一次运行会更久，因为 Docker 需要初始化 microVM，并 pull template image。准备就绪后，Claude Code 会在 sandbox 内启动，并默认启用 --dangerously-skip-permissions——这是安全的，因为 agent 已经被完整隔离在自己的 VM 中。

在 sandbox 内，agent 拥有 full autonomy。它可以 install system packages、modify configuration files、run services，甚至 use Docker——这些都不会影响你的 host machine。你的 workspace directory 会在 host 和 sandbox 之间以相同 absolute path 同步，因此 error messages 中的 file paths 在两个 environments 中是一致的。

Managing sandboxes

这里有一个容易绊倒人的地方：sandboxes 不会出现在 docker ps 中。它们不是 containers，而是 microVMs。你需要使用专门的 sandbox commands 来管理它们：

列出所有 sandboxes：

docker sandbox ls

在 sandbox 内运行 command：

docker sandbox exec claude-my-project -- ls -la

打开 interactive shell 进行 debugging：

docker sandbox exec -it claude-my-project -- bash

停止 sandbox（保留 state）：

docker sandbox stop claude-my-project

重新连接到 stopped sandbox：

docker sandbox run claude-my-project

永久删除 sandbox：

docker sandbox rm claude-my-project

拆解这些 commands：docker sandbox ls 会显示所有 sandboxes，包括它们的 IDs、names、status、workspace paths 和 creation time。exec command 会在 sandbox 的 container 内运行 command；-- 用来分隔 Docker arguments 和你想运行的 command。-it flags 会给你一个 interactive terminal session，非常适合 debugging。stop command 会暂停 sandbox，但保留所有内容——installed packages、configuration 和 state。rm command 会永久删除 sandbox，所以要小心使用。

Sandboxes 会一直 persist，直到你显式 remove 它们。Installed packages、configuration changes，以及 agent 创建的任何 state，在你 reconnect 时仍然可用。这使它们非常适合 long-running development sessions，因为 agent 可以随着时间积累 context。

Network isolation

你的 agent 现在已经安全地运行在自己的 microVM 中。但默认情况下，它可以访问 internet 上的任何 domain；当你处理 proprietary code 或 sensitive data 时，这可能不是你想要的。Docker Sandboxes 允许你用 allow 和 deny lists 锁定 network access：

默认 deny 所有 network access：

docker sandbox network proxy claude-my-project --policy deny

只允许 agent 需要的 specific domains：

docker sandbox network proxy claude-my-project \
  --allow api.anthropic.com \
  --allow github.com \
  --allow registry.npmjs.org \
  --allow pypi.org

network proxy command 会为 sandbox 配置 network policies。--policy deny flag 会默认阻止所有 outbound traffic——除非你显式 allow，否则任何请求都出不去。每个 --allow flag 都会把一个 domain 添加到 allowlist。每行末尾的 backslash（``）表示 command 继续到下一行，使其更易读。

Network proxy configuration 存储在：

~/.docker/sandboxes/vm/<vm-name>/proxy-config.json

你可以直接 inspect 和 edit 这个 JSON file，以进行 fine-grained control。

这遵循 least privilege principle：agents 只能访问它们实际需要的 domains。如果 agent 尝试访问 blocked domain，请求会失败，agent 可以尝试 alternative approach。相信我，当你的 coding agent 拥有 codebase access 时，知道它不能随便向 random servers “phone home”，你会睡得更踏实。

Docker execution inside sandboxes

接下来这个 capability 才真正把 Docker Sandboxes 区分开来，也是仅靠 containers 无法解决这个问题的原因。还记得 Docker-in-Docker challenge 吗？在第 7 章中，如果你想在 container 内运行 Docker，要么 mount host socket（security risk），要么使用 privileged mode（破坏 isolation 目的）。在 sandbox 内，这件事直接 works。每个 sandbox 都有自己的 Docker daemon。

在 sandbox 内，agent 可以：

docker build -t my-app .
docker run -d -p 8080:8080 my-app
docker compose up --build

这些操作都不会影响你的 host Docker daemon。Agent 的 containers、images 和 networks 只存在于 sandbox VM 内部。这对 coding agents 非常关键，因为它们需要把 testing containerized applications 作为 workflow 的一部分。

Supported agents and multi-workspace mounting

前面的 examples 中我们一直使用 Claude Code，但 Docker Sandboxes 并不绑定到单个 agent。它支持主要 AI coding agents：

Claude Code：

docker sandbox run claude ~/my-project

Gemini CLI：

docker sandbox run gemini ~/my-project

Codex CLI：

docker sandbox run codex ~/my-project

Mount multiple workspaces（reference docs 以 read-only 方式挂载）：

docker sandbox run claude ~/my-project ~/docs:ro ~/shared-libs:ro

:ro suffix 会把 directories 作为 read-only mount，让 agents 可以 reference documentation 或 shared libraries，但不能修改它们。

现在盘点一下你已经拥有了什么：你的 agent 运行在一个 dedicated microVM 中，拥有自己的 kernel；它有自己的 Docker daemon，用于 build 和 test containers；你已经把 network access 锁定到它真正需要的 domains；你还能以 fine-grained read / write control 挂载多个 workspaces。这已经是很强的能力。但它也引出了一个显而易见的问题。

When to use sandboxes versus containers

到这里你可能会问：我是否应该用 sandboxes 替换第 7 章中构建的一切？答案是：不要。Docker Sandboxes 和 container isolation 服务于不同目的。

Aspect	Container isolation（第 7 章）	Docker Sandboxes
Isolation level	Namespace / cgroup	Full microVM
Kernel	与 host 共享	每个 sandbox 独立
Use case	Long-running service agents	Coding / development agents
Lifecycle	Persistent services	Disposable environments
Network control	Docker networks	Allow / deny lists
Overhead	Minimal	每个 microVM 约 200MB

Table 9.1：基于 container 的 isolation 与 Docker Sandboxes 对比

对于 service-oriented agents，请使用 container isolation；它们作为 infrastructure 的一部分持续运行——例如第 7 章中构建的 monitoring agents、data processors 和 controllers。对于 coding agents，请使用 Docker Sandboxes；这类 agents 需要执行 arbitrary code、install packages，并把与 Docker 的交互作为 workflow 的一部分。

现在，你已经为 coding agents 拥有一个安全 execution environment：microVM isolation、network control，以及 multi-workspace mounting。Security problem 已经解决了。但 productivity problem 仍然存在：第 7 章和第 8 章中你必须写的大量 infrastructure code。Sandboxes 让 agents 安全，但并不会让它们更容易构建。接下来我们解决这个问题。

Declarative agent teams with Docker Agent

Sandboxes 解决的是 “how do I let this agent run safely” 的问题。但回头看看在第 7 章和第 8 章中，为了让一个 multi-agent system 跑起来，你实际构建了什么：每个 agent 一个 separate Python file，每个 agent 一个 Dockerfile，一个用于把它们 wire together 的 Compose file，Redis 用于 memory，Flask 用于 API endpoints，在 agents 真正开始做有用工作之前，你已经写了 hundreds of lines of infrastructure code。

对于 “我想让三个 AI agents 协作完成一个 task” 这种需求来说，这有太多 boilerplate 了。就像每次想开车去哪里，都要先自己造一台 engine。

如果所有这些都能变成一个 YAML file 呢？

这就是 Docker Agent。它是 Docker 的 CLI tool，用于构建和运行 AI agent teams。你描述 agents 应该做什么、需要哪些 tools、使用哪些 models。Docker Agent 负责 runtime loop、tool execution 和 inter-agent communication——也就是你在前面章节中手写的所有 plumbing。

From imperative to declarative

我用一个具体对比来说明。回想你在第 7 章中为 multi-agent controller 创建的所有内容：

agent.py（约 100 行）
controller.py（约 150 行）
worker.py（约 80 行）
Dockerfile.agent（约 15 行）
Dockerfile.controller（约 15 行）
docker-compose.yml（约 60 行）
requirements.txt
package.json
.env

总共大约 9 个 files，超过 400 行 code。

而 Docker Agent 中的等价物是：

agents.yaml（约 30–60 行）

总共只需要一个 file。

你在第 7 章中手工构建的四个 components——reasoning engine、tool access、memory 和 controller——都可以映射到 YAML fields：

Chapter 7 component	Docker Agent equivalent
Docker Model Runner + API code	`model:` field
MCP Gateway + tool calls	`toolsets:` section
Redis + persistence code	`memory` built-in tool
Python agent loop	Docker Agent runtime（automatic）

Table 9.2：第 7 章中手工实现的 agent system components，与 Docker Agent YAML configuration 中 declarative equivalents 的映射

简单说，这就是 trade-off：你失去了 custom Python code 的灵活性，但获得了几分钟内定义 agents 的能力，而不是花几个小时。现在我们安装 Docker Agent，并在实践中看看它如何工作。

Installing Docker Agent

使用你所在 platform 的 package manager 安装 Docker Agent。

macOS：

brew install docker-agent

Windows：

winget install docker.docker-agent

验证安装：

docker agent version

通过设置对应 environment variable，配置至少一个 AI provider：

Option 1: OpenAI

export OPENAI_API_KEY=sk-your-key-here

Option 2: Anthropic

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Option 3: Google Gemini

export GEMINI_API_KEY=your-key-here

Option 4: Docker Model Runner（free、local）

No API key needed - uses your local DMR instance

Docker Agent 安装完成并配置好 provider 后，我们来构建第一个 agent。

Your first agent

我来展示它有多简单。

创建一个名为 agents.yaml 的 file：

agents:
  root:
    model: openai/gpt-4.1-mini
    description: A helpful assistant that talks like a pirate
    instruction: |
      You are a helpful assistant that talks like a pirate.
      Always respond with "Arrr!" and use pirate slang.

运行它：

docker agent run agents.yaml

就是这样。五行 YAML，就有了一个 running agent。没有 Dockerfile。没有 Compose file。没有 Python。Docker Agent 会处理 model connection、conversation management 和 runtime loop。输入一条 message，agent 会以角色设定回应。

docker agent run command 会启动一个 interactive agent session。Argument 指定要加载哪个 YAML file。model field 使用 provider/model-name 格式。可用 providers 包括 openai/、anthropic/、gemini/，以及用于 Docker Model Runner 的 docker/。

Core properties and autonomy

Pirate assistant 很好玩，但它并不是真正的 agent——它只是回答 prompts。要让 agents 具备真正 autonomy，你需要给它们 tools。Docker Agent 包含六个 built-in toolsets：

filesystem：Read、write 和 edit files。Agent 可以 navigate directories、create files，并对 existing code 做 targeted edits。

shell：Execute shell commands。结合 filesystem 后，agents 就可以 build、test 和 deploy code。

memory：使用 SQLite 的 persistent storage。不同于第 7 章中基于 Redis 的 memory，这个 memory 会在本地 persist，且 zero configuration——不需要 separate database container。

think：Structured reasoning scratchpad。Agent 可以写下自己的 thought process，而不采取 action，这对 complex multi-step problems 非常有用。

todo：用于跟踪 complex workflows progress 的 task management。Agent 可以 create、update 和 check off tasks。

environment：访问 environment variables，用于 configuration。

下面是一个同时使用多个 tools 的 agent：

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Reviews code and suggests improvements
    instruction: |
      You are an expert code reviewer. When given a codebase:
      1. Use filesystem to read the project structure
      2. Create a todo list of files to review
      3. Use think to analyze patterns and issues
      4. Write a review summary using filesystem
      5. Use memory to track which files you've reviewed
    toolsets:
      - type: filesystem
      - type: shell
      - type: memory
        path: ./review-memory.db
      - type: think
      - type: todo

运行：

docker agent run agents.yaml

这个 agent 现在拥有真正 autonomy：它可以 read 你的 codebase、reason about issues、track progress，并产出 written review。

与第 7 章中的 agent setup 对比：能力相同（filesystem、shell、memory、reasoning），但这里是用 YAML configuration，而不是 Python code 实现。现在让这些 agents 更聪明一些：给每项工作匹配正确 model。

Multi-modal configurations

你在第 8 章已经学到，并不是每个 task 都需要 frontier model。Simple classification 如果用 GPT-4.1 会浪费钱，而 complex reasoning 在 smaller models 上又会表现吃力。Docker Agent 让 per-agent model assignment 变得非常直接：

agents:
  root:
    model: openai/gpt-4.1-mini
    description: Fast triage of incoming requests
    instruction: |
      Classify incoming requests as: bug, feature, question, or other.
      Be fast and concise. For complex issues, delegate to deep-analyzer.
    sub_agents: [deep-analyzer]

  deep-analyzer:
    model: anthropic/claude-sonnet-4-5
    description: Deep analysis of complex issues
    instruction: |
      Perform thorough analysis of technical issues.
      Consider edge cases, security implications, and performance.
    toolsets:
      - type: think
      - type: filesystem

你也可以使用 Docker Model Runner，获得完全 local、free inference：

models:
  local-llm:
    provider: dmr
    model: ai/llama3.2:3B-Q8_0

agents:
  root:
    model: local-llm
    description: Runs entirely on local hardware
    instruction: Analyze files in the current directory.
    toolsets:
      - type: filesystem

Named model configurations 允许你控制 temperature 和 reasoning depth 等 parameters：

models:
  creative-writer:
    provider: openai
    model: gpt-4.1-mini
    temperature: 0.9

  precise-coder:
    provider: anthropic
    model: claude-sonnet-4-5
    temperature: 0.1

  deep-thinker:
    provider: anthropic
    model: claude-sonnet-4-5
    thinking_budget: 8192

agents:
  root:
    model: creative-writer
    description: Creative writing assistant
    instruction: You are a creative writer. Be imaginative and expressive.

  coder:
    model: precise-coder
    description: Precise coding assistant
    instruction: You are an expert coder. Be exact, minimal, and correct.
    toolsets:
      - type: filesystem
      - type: shell

  analyst:
    model: deep-thinker
    description: Deep technical analyst
    instruction: Perform thorough analysis. Think through edge cases and implications.
    toolsets:
      - type: think

你甚至可以使用 Docker Model Runner 做完全 local、free inference——不需要 API keys、不调用 cloud、data 不离开你的机器。只需把 model line 改成：

docker/ai/llama3.2:3B-Q8_0

Docker Agent 会处理剩下的事情。

现在，你已经让 agents 针对不同 tasks 使用正确 model：fast models 用于 triage，powerful models 用于 deep analysis，local models 用于 privacy。但到目前为止，每个 agent 都是独立工作的。那第 8 章中构建的 collaborative patterns 呢？那些 specialists 会 coordinate 来解决单个 agent 无法处理的问题。

Building multi-agent teams

Single agents 很有用，但请回想第 8 章中你构建的内容：specialists teams 会 coordinate，解决 single agent 无法单独解决的问题。

Figure 9.4：Docker multi-agent team 与 sub-agent hierarchy

Docker Agent 通过两种 coordination mechanisms 支持同样的 patterns：

Sub-agents（hierarchical delegation） ：Parent agent 将 specific tasks delegate 给 child agents，并接收 results。Parent 维持 control 和 context。

Handoffs（conversation transfer） ：Parent agent 将 entire conversation transfer 给 child agent。Original agent 退出，new agent 接管。

下面是一个 practical example——bug investigation team：

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Lead investigator that coordinates bug fixes
    instruction: |
      You lead bug investigations. When a bug is reported:
      1. Analyze the bug report
      2. Delegate code investigation to the code-analyst
      3. Delegate fix implementation to the fixer
      4. Review the fix and provide final assessment
    toolsets:
      - type: think
      - type: todo
    sub_agents: [code-analyst, fixer]

  code-analyst:
    model: anthropic/claude-sonnet-4-5
    description: Investigates code to find root causes
    instruction: |
      Analyze the codebase to find the root cause of bugs.
      Read relevant files, trace execution paths, and report findings.
    toolsets:
      - type: filesystem
      - type: think

  fixer:
    model: anthropic/claude-sonnet-4-5
    description: Implements bug fixes
    instruction: |
      Implement fixes for bugs identified by the code-analyst.
      Make minimal, targeted changes and explain what you changed.
    toolsets:
      - type: filesystem
      - type: shell

运行 team：

docker agent run bug-investigator.yaml

Lead investigator 负责 coordinate everything。当需要 code analysis 时，它 delegate 给 code analyst。当需要实现 fix 时，它 delegate 给 fixer。每个 sub-agent 都使用针对自身 task 优化的 model：GPT-4.1-mini 用于 fast analysis，Claude Sonnet 用于 careful implementation。

相比之下，在第 7 章中构建同样的 three-agent system 需要三个 Python files、两个 Dockerfiles、一个 Docker Compose file 和 Redis configuration。使用 Docker Agent，只需要三个小 YAML files。Same result，工作量少很多。

到目前为止，你的 agents 使用的是 Docker Agent 的 built-in tools。但第 6 章中配置的 MCP servers 呢——GitHub、DuckDuckGo 和 Slack？Docker Agent 可以直接接入这个 ecosystem。

Integrating external tools with MCP

还记得第 6 章中的 Docker MCP Catalog 吗？Docker Agent 只需要在 YAML 中写一行，就能连接到同样的 servers：

agents:
  root:
    model: openai/gpt-4.1-mini
    description: Researches topics using web search and GitHub
    instruction: |
      Research the given topic thoroughly.
      Search the web for recent information.
      Check GitHub for relevant repositories and code.
    toolsets:
      - type: think
      - type: memory
        path: ./research-memory.db
      - type: mcp
        ref: docker:duckduckgo
      - type: mcp
        ref: docker:github-official

docker: prefix 告诉 Docker Agent 从 Docker Hub pull MCP server。Docker Agent 会管理 server lifecycle：当 agent 需要 tools 时启动 server，完成后停止。

你还可以限制 agent 在 MCP server 中可访问哪些 tools：

toolsets:
  - type: mcp
    ref: docker:github-official
    tools: [search_repositories, get_file_contents, list_issues]
    # Agent can only search, read files, and list issues
    # Cannot create issues, push code, or delete anything

如果你在第 6 章中用 Docker MCP Toolkit 配置了 Google Drive 或 Slack 之类 services 的 OAuth connections，Docker Agent 也可以使用它们：

toolsets:
  - type: mcp
    ref: docker:slack
  - type: mcp
    ref: docker:google-drive

你现在已经用 YAML 构建了 agent teams：它们拥有 built-in tools、multiple models 和 external MCP servers。但如果同事想运行同样的 agent team，会发生什么？这就是 Docker Agent 的 distribution model 变得有趣的地方。

Sharing agents via Docker Hub

Docker Agent 会把 agent configurations 打包成 OCI artifacts——这与 Docker 用于 container images 的 format 相同。这意味着你可以像分享 container image 一样，通过 Docker Hub push 和 pull agent teams：

Push 一个 agent team 到 Docker Hub：

docker agent share push agents.yaml docker.io/yourusername/research-team:v1.0

Pull 并运行别人发布的 agent：

docker agent share pull docker.io/someuser/code-reviewer:latest
docker agent run code-reviewer.yaml

docker agent share push command 会把你的 YAML file 打包成 OCI artifact，并上传到 registry。第一个 argument 是 local YAML file。第二个 argument 是带 version tag 的 registry path。docker agent share pull command 会下载 artifact。就是这么简单。

这让 teams 可以 share pre-configured agent teams，用 tags 对它们 version，并在 organizations 内分发。需要更新 agent？Push 一个 new tag。需要 rollback？Pull previous version。

Running agents as API servers and MCP tools

到目前为止，我们一直在 terminal 中以 interactive 方式运行 agents。但如果你希望其他 applications 与你的 agent 对话，该怎么办？Docker Agent 提供两种 production integration modes：

作为 HTTP API server 运行：

docker agent serve api agents.yaml

指定 custom port：

docker agent serve api agents.yaml --listen :8080

其他 services 现在可以调用你的 agent：

# POST http://localhost:8080/v1/chat/completions

作为 MCP server 运行（你的 agent 会变成其他 agents 的 tool）：

docker agent serve mcp agents.yaml

API server mode 让任何支持 OpenAI-compatible API 的 application 都能访问你的 agent。MCP server mode 更有意思——你的 agent 会变成其他 agents 可以使用的 tool，从而支持 agent-of-agents architectures：一个 Docker Agent team 只是更大 system 中的一个 tool。

现在，你已经拥有可以 interactively run、serve as APIs，甚至作为 tools 被其他 agents 调用的 agents。但在继续之前，Docker Agent 还有一件值得知道的事：它可以帮助你编写 YAML。

Generating agents with AI

不知道该如何开始写 YAML？Docker Agent 可以帮你 scaffold：

docker agent new "Create an agent that reviews pull requests,
  checks for security issues, and suggests improvements"

Docker Agent 会基于你的 description，用 AI 生成完整 YAML configuration。运行前请 review 并 customize output——把它当成 starting point，而不是 finished product。

这就是 Docker Agent 的核心：把一个 9-file、400-line project 变成一个 single YAML file。你拥有了通过 sub-agents 和 handoffs 协作的 multi-agent teams、per-agent model selection、MCP integration，以及通过 Docker Hub 一条命令分发的能力。对大多数 use cases 来说，这已经足够了。

但如果一台机器不够用呢？如果你需要 agents 根据 demand 自动 scale？或者 agents 在凌晨 3 点 crash 时能自己 restart？或者有一整个 fleet 分布在多个 servers 上，并且对每个 request 都有完整 observability？这就是第三个 tool 登场的地方。

Kubernetes-native orchestration with kagent

Docker Agent 非常适合定义 agent teams，并在本地或 single server 上运行它们。但下面这个 scenario 它无法处理：你的 research assistant team 每小时要处理 500 个 document analysis requests。一台机器不够。你需要把 agents 分布到多台 servers 上；当 queue 很深时自动 spin up 更多 replicas；当 workload 平静下来时自动 scale back down。你需要 agents 在 crashes 后 self-restart，需要 secrets at rest 加密，还需要 observability stack 来 trace workflow 中每个 agent 的 requests。

Figure 9.5：kagent Kubernetes-native agent architecture

这就是 Kubernetes territory。kagent 是一个专门把 AI agent workloads 带入 Kubernetes ecosystem 的 framework。你不再编写 Dockerfiles 和 Compose files，而是编写 Kubernetes manifests，定义 agents、它们的 models 和 tools。Kubernetes 负责 scheduling、scaling、networking 和 recovery——也就是现在运行 production services 的同一套 infrastructure，用来管理你的 agent fleets。

From Docker Compose to Kubernetes: Understanding the gap

贯穿本书，你一直在使用 Docker Compose，它很好地服务了你。但 Compose 是为 single-machine deployments 设计的。面对 agent workloads 时，它会在以下方面开始吃力：

Capability	Docker Compose	Kubernetes and kagent
Scaling	Manual `--scale` flag	Automatic HPA based on metrics
Recovery	`restart: on-failure`	Self-healing with pod replacement
Multi-node	Single-machine only	Distributed across a cluster
Service discovery	DNS in Compose	Cluster-wide DNS and Ingress
Secrets	`.env` files	Encrypted Kubernetes secrets
Observability	Manual setup	Native Prometheus integration
Rolling updates	Downtime during restarts	Zero-downtime deployments

Table 9.3：Docker Compose 与 Kubernetes（with kagent）对比

kagent 在 Kubernetes 之上增加了 AI-specific capabilities：用于 agents 和 models 的 custom resource definitions（CRDs）、built-in MCP server management，以及用于 monitoring agent fleets 的 dashboard。

现在我们搭建一个 cluster，并看看它在实践中如何工作。

Setting up a local Kubernetes cluster

你不需要 cloud Kubernetes cluster 才能跟着做。kind（Kubernetes in Docker）会创建一个非常适合 development 和 testing 的 local cluster：

创建一个拥有足够 resources 运行 agent workloads 的 cluster：

cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker
EOF

验证 cluster：

kubectl get nodes

拆解一下：cat << EOF construct 会创建 heredoc——两个 EOF markers 之间的所有内容都会作为 input 被 pipe 进去。kind create cluster command 会创建一个新的 Kubernetes cluster。--config=- flag 告诉 kind 从 stdin 读取 configuration（也就是 piped heredoc）。YAML 定义了一个包含三个 nodes 的 cluster：一个 control plane 和两个 workers。kubectl get nodes command 用来验证所有东西都在运行。

你应该会看到类似 output：

NAME                 STATUS   ROLES           AGE   VERSION
kind-control-plane   Ready    control-plane   60s   v1.31.0
kind-worker          Ready    <none>          40s   v1.31.0
kind-worker2         Ready    <none>          40s   v1.31.0

三个 nodes 都 ready：一个 control plane，两个 workers。现在把 kagent 安装到这个 cluster 上。

Installing kagent with Helm

kagent 通过 Helm 安装，Helm 是标准 Kubernetes package manager。

首先安装 CRDs chart（required）：

helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --namespace kagent \
  --create-namespace

使用你的 API key 安装 kagent：

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --namespace kagent \
  --set providers.default=openAI \
  --set providers.openAI.apiKey=$OPENAI_API_KEY

验证安装：

kubectl get pods -n kagent

CRDs 必须先作为 separate chart 安装，然后才能安装 kagent 本身。这是 hard requirement。

helm install command 会直接使用 OCI references；不需要 helm repo add 或 helm repo update。--set providers.default=openAI flag 选择 provider，--set providers.openAI.apiKey= 会传入你的 API key。

kagent 0.8.1 有一个 known issue：Helm chart 中的 pod image references 指向 cr.kagent.dev，而不是 ghcr.io；同时还引用了 Docker Hub 上不存在的 postgres:18。如果安装后看到 ErrImagePull 或 ImagePullBackOff，请 patch 受影响的 deployments：

for deploy in $(kubectl get deployments -n kagent -o name); do
  kubectl patch $deploy -n kagent --type='json' \
    -p='[{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"ghcr.io/kagent-dev/kagent/app:0.8.1"}]' \
    2>/dev/null && echo "Patched $deploy"
done

Patch infrastructure components：

kubectl set image deployment/kagent-controller \
  controller=ghcr.io/kagent-dev/kagent/controller:0.8.1 -n kagent

kubectl set image deployment/kagent-ui \
  ui=ghcr.io/kagent-dev/kagent/ui:0.8.1 -n kagent

kubectl set image deployment/kagent-postgresql \
  postgres=docker.io/library/postgres:17 -n kagent

安装完成后，你应该看到以下 pods running：

NAME                                           READY   STATUS    RESTARTS
kagent-controller-xxx                          1/1     Running   0
kagent-ui-xxx                                  1/1     Running   0
kagent-postgresql-xxx                          1/1     Running   0
kagent-kmcp-controller-manager-xxx             1/1     Running   0
kagent-tools-xxx                               1/1     Running   0
kagent-grafana-mcp-xxx                         1/1     Running   0
kagent-querydoc-xxx                            1/1     Running   0
k8s-agent-xxx                                  1/1     Running   0
helm-agent-xxx                                 1/1     Running   0
istio-agent-xxx                                1/1     Running   0
observability-agent-xxx                        1/1     Running   0

安装 kagent CLI。

macOS：

brew install kagent

验证：

kagent version

通过 port-forward 访问 dashboard：

kubectl -n kagent port-forward service/kagent-ui 8080:8080

然后在 browser 中打开：

http://localhost:8080

Controller 已经运行，CLI 也准备好了。在创建第一个 agent 之前，先理解 kagent 如何扩展 Kubernetes API。

Understanding kagent CRDs

如果你用过 Kubernetes，应该熟悉 Pods、Services 和 Deployments 这些 built-in resources。kagent 通过三个专门为 AI agents 设计的 custom resource definitions 来扩展 Kubernetes：

Agent：定义 AI agent，包括 model、instructions、tools 和 behavior。它相当于 Docker Agent 的 YAML，但作为 Kubernetes resource 存在。

ModelConfig：指定 model provider、name 和 parameters。多个 agents 可以引用同一个 model configuration。

Tool / Toolset：定义 agents 可用的 tools，包括 MCP servers。

下面是你的第一个 kagent agent：

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: devops-assistant
  namespace: kagent
spec:
  description: "Kubernetes DevOps assistant"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      You are a DevOps expert. Help with Kubernetes
      troubleshooting, deployment issues, and infrastructure
      questions. Be concise and practical.

应用：

kubectl apply -f devops-assistant.yaml

type: declarative field 是 required——kagent 同时支持 declarative agents（用 YAML 定义）和 BYO agents（custom code）。declarative: block 包含 model reference 和 system message。modelConfig field 引用一个 ModelConfig resource 的 name——当你在 Helm install 中设置 provider 时，kagent 0.8.1 会自动安装一个 default-model-config。

通过 kagent CLI 与 agent 交互：

kagent invoke -t "What pods are running in the kagent namespace?" --agent k8s-agent

或者通过 kagent dashboard 访问：

kubectl -n kagent port-forward service/kagent-ui 8080:8080
# Opens http://localhost:8080 with agent management UI

在 Kubernetes 上运行一个 single agent 并不特别令人兴奋——Docker Agent 也能做到。真正的收益来自于部署 agent team，让 Kubernetes 自动 manage、scale 和 heal 它们。

Building multi-agent architectures

我们来构建一个 DevOps troubleshooting team——一个 coordinator 加两个 specialists——并把它部署到 cluster 上：

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: ops-coordinator
  namespace: kagent
spec:
  description: "Coordinates DevOps troubleshooting"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      You coordinate troubleshooting across specialized agents.
      Delegate log analysis to log-analyzer.
      Delegate metrics investigation to metrics-checker.
      Synthesize findings into actionable recommendations.
---
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: log-analyzer
  namespace: kagent
spec:
  description: "Analyzes Kubernetes logs for issues"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      Analyze Kubernetes pod logs to identify errors,
      warnings, and anomalies. Report findings concisely.
    tools:
      - type: McpServer
        mcpServer:
          name: kagent-tool-server
          kind: RemoteMCPServer
          toolNames:
            - k8s_get_pod_logs
            - k8s_get_events
---
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: metrics-checker
  namespace: kagent
spec:
  description: "Checks cluster metrics and resource usage"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      Monitor Kubernetes cluster metrics including CPU,
      memory, and network usage. Identify resource bottlenecks.
    tools:
      - type: McpServer
        mcpServer:
          name: kagent-tool-server
          kind: RemoteMCPServer
          toolNames:
            - k8s_get_resources
            - k8s_describe_resource

部署整个 team：

kubectl apply -f 02-ops-team/

Trailing slash 告诉 kubectl 应用 02-ops-team/ directory 中的每个 YAML file。一个 command 就部署所有三个 agents。Kubernetes 会把每个 agent schedule 到 available nodes 上，管理它们之间的 networking，并 restart 任何 crashed agent。不再是 restart: on-failure 然后寄希望于最好结果——Kubernetes 会直接 replace failed pods。

Result：

agent.kagent.dev/ops-coordinator created
agent.kagent.dev/log-analyzer created
agent.kagent.dev/metrics-checker created

所有三个 agents 都成功 created。现在验证它们正在 running，并测试它们：

kagent get agent | grep -E "ops-coordinator|log-analyzer|metrics-checker"

Result：

| 1  | kagent/metrics-checker                | 2026-03-30T12:17:51+05:30 | true             | true     |
| 7  | kagent/log-analyzer                   | 2026-03-30T12:17:51+05:30 | true             | true     |
| 14 | kagent/ops-coordinator                | 2026-03-30T12:17:51+05:30 | true             | true     |

现在测试它们：

kagent invoke -t "Check for any pod errors in the kagent namespace" --agent ops-coordinator

你已经在 cluster 上部署了一个 three-agent team，并拥有 automatic healing 和 scheduling。但这些 agents 现在还做不了太多——它们需要 tools。还记得第 6 章中配置过的 MCP servers 吗？kagent 有自己的方式把它们作为 Kubernetes workloads 部署。

Deploying MCP servers with kmcp

kmcp 是 kagent 的 subproject，提供一个 CLI tool，用来在 Kubernetes 中 develop 和 deploy MCP servers。默认情况下，kmcp 会随 kagent 一起安装——不需要单独安装。

在你的 local machine 上安装 kmcp CLI：

curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash

Result：

kmcp installed into /usr/local/bin/kmcp

🎉 KMCP installation completed successfully!

Installation location: /usr/local/bin/kmcp

To verify the installation, please run:
  kmcp --version

KMCP has been added to your PATH, you may need to:
  - Restart your terminal, or
  - Run 'source ~/.zshrc' (for zsh) or 'source ~/.bashrc' (for bash)

For more information, run:
  kmcp --help

使用现有 npm package 部署一个 pre-built MCP server。注意 --namespace kagent flag——如果没有它，kmcp 会部署到 default namespace，而 kagent agents 无法 discover 它：

kmcp deploy package \
   --deployment-name my-mcp-server \
   --manager npx \
   --args @modelcontextprotocol/server-everything \
   --namespace kagent

你应该看到类似 output：

🚀 Applying MCPServer to cluster...
🚀 Applying resources to cluster...
mcpserver.kagent.dev/my-mcp-server created
✅ Resources applied successfully
✅ MCPServer 'my-mcp-server' applied successfully
⌛ Waiting for deployment 'my-mcp-server' to be ready...

从你自己的 image 部署 custom MCP server：

kmcp deploy \
  --file my-mcp-server/kmcp.yaml \
  --image your-registry/custom-mcp:v1.0 \
  --namespace kagent

也可以直接用 kubectl apply 把 MCP servers 作为 Kubernetes resources 部署：

apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: mcp-website-fetcher
  namespace: kagent
spec:
  deployment:
    args:
      - mcp-server-fetch
    cmd: uvx
    port: 3000
    stdioTransport: {}
  transportType: stdio

对于 secrets management，使用 Kubernetes Secrets：

kubectl create secret generic mcp-credentials \
  --from-literal=github-token=ghp_your_token \
  --from-literal=slack-token=xoxb-your-token \
  -n kagent

通过 kmcp 部署的 MCP servers 会通过 Kubernetes service discovery 被 kagent agents 自动 discover。无需手工 networking configuration。

你现在已经部署了 agents，通过 kmcp 连接了 tools，并通过 Kubernetes 管理 secrets。你的 MCP servers 是自动 discoverable 的——不需要手工 networking configuration。但到目前为止，你运行的是 fixed number of agent replicas。如果那条 500 个 document analysis requests 的 queue 突然 spike 到 2,000 个，会发生什么？这正是你迁移到 Kubernetes 的原因。接下来让它 scale。

Autoscaling and resource optimization

还记得本节开头那个 scenario 吗——每小时 500 个 document analysis requests？Kubernetes Horizontal Pod Autoscaler（HPA）可以自动处理这种情况：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: log-analyzer-hpa
  namespace: kagent
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: log-analyzer
  minReplicas: 1
  maxReplicas: 5
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

这个 YAML 定义了一个 Horizontal Pod Autoscaler。scaleTargetRef 指向 kagent 为 log-analyzer agent 创建的 Deployment——HPA target 的是 Kubernetes Deployments，而不是直接 target kagent Agent CRDs。minReplicas 和 maxReplicas 设置 scaling bounds——永远至少有 1 个 log-analyzer running，最多不超过 5 个。averageUtilization: 70 表示当 average CPU utilization 超过 70% 时，Kubernetes 会添加新的 replica。当 analysis tasks queue 增长时，更多 agent pods 会自动出现。当 demand 下降时，它们会 scale back down。无需 manual intervention。也不会凌晨 3 点叫醒你。

应用后，验证 HPA 是否工作：

kubectl get hpa -n kagent

你应该看到：

NAME               REFERENCE                 TARGETS       MINPODS   MAXPODS   REPLICAS   AGE
log-analyzer-hpa   Deployment/log-analyzer   cpu: 0%/70%   1         5         1          2m10s

Note for kind clusters

kind 默认不包含 metrics-server。安装前，HPA 会显示：

cpu: <unknown>/70%

安装 metrics-server：

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
kubectl patch deployment metrics-server -n kube-system \
  --type='json' \
  -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

metrics-server 运行后，kubectl get hpa -n kagent 会显示真实 CPU values，kubectl top nodes 会显示 cluster resource usage。

设置 resource limits，防止 agents 消耗 excessive cluster resources：

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: log-analyzer
  namespace: kagent
spec:
  description: "Analyzes Kubernetes logs for issues"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      Analyze Kubernetes pod logs to identify errors,
      warnings, and anomalies. Report findings concisely.
    deployment:
      resources:
        requests:
          cpu: "500m"
          memory: "512Mi"
        limits:
          cpu: "2"
          memory: "2Gi"
    tools:
      - type: McpServer
        mcpServer:
          name: kagent-tool-server
          kind: RemoteMCPServer
          toolNames:
            - k8s_get_pod_logs
            - k8s_get_events

Agents 已经可以 scale 了。但你如何知道它们实际在做什么？在第 7 章中，你加入了 structured JSON logging。在 Kubernetes 中，你可以获得完整 observability stack。

Observability with Prometheus and tracing

为 agent monitoring 部署 Prometheus 和 Grafana。

添加 prometheus-community Helm repo：

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

安装 Prometheus 和 Grafana：

helm install monitoring prometheus-community/kube-prometheus-stack\
--namespace monitoring\
--create-namespace

验证所有 pods 都在运行：

kubectl get pods -n monitoring

你应该看到：

NAME                                                     READY   STATUS    RESTARTS
alertmanager-monitoring-kube-prometheus-alertmanager-0   2/2     Running   0
monitoring-grafana-xxx                                   3/3     Running   0
monitoring-kube-prometheus-operator-xxx                  1/1     Running   0
monitoring-kube-state-metrics-xxx                        1/1     Running   0
monitoring-prometheus-node-exporter-xxx                  1/1     Running   0
prometheus-monitoring-kube-prometheus-prometheus-0       2/2     Running   0

获取 Grafana admin password：

kubectl --namespace monitoring get secrets monitoring-grafana \
  -o jsonpath="{.data.admin-password}" | base64 -d; echo

访问 Grafana dashboard：

kubectl port-forward svc/monitoring-grafana 3000:80 -n monitoring

打开：

http://localhost:3000

使用 username admin 和上面获取的 password 登录。Pre-built Kubernetes dashboards 会展示所有 agent pods 的 CPU usage、memory consumption、pod restarts 和 request rates。

Agent workloads 的 key metrics：

container_cpu_usage_seconds_total - 每个 agent pod 的 CPU usage
container_memory_working_set_bytes - 每个 agent pod 的 memory usage
kube_pod_container_status_restarts_total - 每个 agent pod 的 crash / restart count
kube_deployment_status_replicas_available - ready 状态的 agent replicas 数量

为了在 multi-agent workflows 中实现 distributed tracing，部署 Jaeger：

cat << 'EOF' > jaeger.yaml
provisionDataStore:
  cassandra: false
allInOne:
  enabled: true
storage:
  type: memory
agent:
  enabled: false
collector:
  enabled: false
query:
  enabled: false
EOF

helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo update

helm upgrade --install jaeger jaegertracing/jaeger \
  --namespace jaeger \
  --create-namespace \
  --values jaeger.yaml \
  --version 4.4.7

通过重新安装并带上 tracing flags 来启用 kagent 中的 tracing：

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --namespace kagent \
  --set providers.default=openAI \
  --set providers.openAI.apiKey=$OPENAI_API_KEY \
  --set otel.tracing.enabled=true \
  --set otel.tracing.exporter.otlp.endpoint=http://jaeger.jaeger.svc.cluster.local:4317

如果 kagent 已经安装，请使用带同样 flags 的 helm upgrade。如果因为 previously patched deployments 遇到 conflict error，请先执行：

helm uninstall kagent -n kagent

然后重新安装。

访问 Jaeger UI：

export POD_NAME=$(kubectl get pods --namespace jaeger \
  -l "app.kubernetes.io/instance=jaeger,app.kubernetes.io/component=all-in-one" \
  -o jsonpath="{.items[0].metadata.name}")
kubectl port-forward --namespace jaeger $POD_NAME 16686:16686 &

打开：

http://localhost:16686

通过 invoke 一个 agent 生成 tracing data：

kagent invoke -t "What pods are running in the kagent namespace?" --agent k8s-agent

在 Jaeger UI 中，从 Service dropdown 选择 kagent，从 Operation dropdown 选择 agent_run [k8s-agent]，然后点击 Find Traces。你会看到每个 request 从 CLI invoke，到 controller，到 agent pod，再到每个 tool call，最后返回的 end-to-end trace。

你已经拥有了能响应 demand 的 scaling，也拥有了能展示每个 agent 内部发生什么的 observability。但在 production-ready 之前，还有一个 piece 需要锁定：security。现在，cluster 中任何 pod 都可能与任何 agent 对话。Development 时这样没问题，但 production 中需要 strict boundaries。

Network policies for security isolation

在第 7 章中，你用 Docker internal networks 来隔离 agents。Kubernetes 有自己的 equivalent——network policies，并且控制粒度更细：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: agent-isolation
  namespace: kagent
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: k8s-agent
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: kagent
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kagent

这个 policy 允许 k8s-agent pod 只接收来自 kagent controller 的 requests，并且只向 kagent namespace 内发送 requests。没有 direct internet access，没有 cross-namespace communication。podSelector 和 matchLabels 使用 actual Kubernetes labels 来 target pods。policyTypes list 指定同时控制 incoming（Ingress）和 outgoing（Egress）traffic。如果 compromised agent 尝试 exfiltrate data，network policy 会 block 它。这就是 defense in depth。

应用 network policies 之前，请验证 pods 上的 actual labels，因为 selectors 必须完全匹配：

kubectl get pods -n kagent --show-labels | grep k8s-agent

Important：NetworkPolicy 要求 CNI plugin 支持 enforcement，例如 Calico 或 Cilium。kind clusters 默认使用 kindnet，它不会 enforce NetworkPolicy rules——policy 会被 API server 接受，但 traffic 实际不会被 block。在 EKS、GKE 或 AKS 等 production clusters 中，NetworkPolicy enforcement 通常开箱即用。

Figure 9.6：kagent production capabilities

这就是 kagent——你的 agents 获得了与 production services 相同的 production-grade infrastructure：autoscaling、self-healing、observability 和 network isolation。

Choosing the right orchestration tool

本章中你已经看到了三个 tools，它们解决的是 fundamentally different problems。Docker Sandboxes 处理 security。Docker Agent 处理 simplicity。kagent 处理 scale。但当你面对一个 new project 时，该如何选择？下面是一份 quick reference：

Scenario	Tool	Why
在 laptop 上安全运行 coding agent	Docker Sandboxes	MicroVM isolation，disposable
为 project 定义 three-agent team	Docker Agent	一个 YAML file，无 infrastructure code
与 team 分享 agent configs	Docker Agent（push / pull）	通过 Docker Hub 分发 OCI artifacts
Prototyping agent workflows	Docker Agent	Fastest iteration cycles
在 production 中 scale 运行 agents	kagent	Autoscaling、self-healing 和 observability
Multi-node agent deployment	kagent	Kubernetes scheduling 和 networking
Enterprise compliance requirements	kagent	RBAC、network policies、audit logging

Table 9.4：基于常见 agent orchestration scenarios，在 Docker Sandboxes、Docker Agent 和 kagent 之间选择的 guidance

这些 tools 并不是 mutually exclusive。一个 realistic workflow 可能是这样的：使用 Docker Agent 在本地快速 iterate agents；使用 Docker Sandboxes 安全测试 coding workflows；然后用 kagent 部署到 Kubernetes，实现 production scale。先从简单开始，只有当 requirements 要求时，再增加 complexity。

知道选哪个 tool，只是 battle 的一半。另一半是正确使用它。不管你是在写 Docker Agent YAML、kagent manifests，还是 sandbox configurations，有些 patterns 会持续带来更好 outcomes。下面是我们发现适用于这三种 tools 的最佳实践。

Best practices for production agent orchestration

在走完 Docker Sandboxes、Docker Agent 和 kagent 之后，你已经看到 agent infrastructure 可以多快变得复杂。无论你是在 laptop 上运行 single coding agent，还是在 Kubernetes cluster 上运行 specialists fleet，以下 practices 都能帮助你控制这种 complexity。

Start with the simplest tool that solves your problem
如果 Docker Agent 的 single YAML file 已经能处理你的 use case，就不要跳到 kagent。如果第 7 章中的 container isolation 已经足够，就不需要 Docker Sandboxes。Complexity 应该由 requirements 来 justify，而不是由对技术的热情来推动。

Keep agents focused
无论是用 Docker Agent YAML 还是 kagent CRDs 定义，每个 agent 都应该有清晰、狭窄的 role。一个 “does everything” 的 agent，比三个 specialists 更难 debug、更难 scale，也更昂贵。

Match models to tasks
大多数 agent tasks——classification、routing、simple analysis——可以由更小、更快的 models 处理，例如 GPT-4.1-mini 或通过 Docker Model Runner 使用 local models。把 large models 保留给真正需要 deep reasoning 的 tasks。Docker Agent 和 kagent 都支持 per-agent model assignment，正是为了这个原因。

Restrict tool access
只给 agents 它们真正需要的 tools。Docker Agent 和 kagent 都支持 MCP servers 上的 tool-level restrictions。一个只能 read repositories 的 agent，比一个还能 push code 或 delete branches 的 agent 安全得多。

Implement observability from the start
在 Docker Agent 中，使用 think 和 todo tools，让 agents 留下 reasoning trail。在 kagent 中，部署 agents 之前先部署 Prometheus 和 Jaeger。没有 observability 的 multi-agent system debugging，就像没有 logs 的 distributed system debugging。

Version control your configurations
Docker Agent YAML files 和 kagent manifests 都是 declarative infrastructure。把它们放进 Git，通过 pull requests review changes，并 tag releases。Docker Agent 的 Docker Hub integration 让这一点变得自然——把 versioned agent configurations 和 application code 一起 push。

Summary

现在回头看看，从第 7 章到这里，你已经走了多远。

在第 7 章中，你从零开始构建 agents——Python scripts、Flask APIs、Redis memory、Docker Compose orchestration。这教会了你底层一切如何工作。在本章中，你学习到 Docker 已经构建了一些 tools，可以替你处理其中大部分 plumbing。

Docker Sandboxes 让 coding agents 能够在 microVMs 中自由 install packages、run Docker、execute arbitrary code，而不会给 host system 带来风险。Network allow / deny lists 进一步细粒度控制 agents 能访问什么。当你需要让 agent autonomously run，并且不能承受一遍遍 babysit permission prompts 时，Sandboxes 就是正确工具。

Docker Agent 完全消除了 infrastructure code。第 7 章中 9 个 files、400 行的 multi-agent projects，可以变成 single YAML files。Built-in tools 处理 filesystem access、shell execution、persistent memory 和 structured reasoning。Multi-agent teams 通过 sub-agents 和 handoffs 进行 coordinate。完成之后，你可以把整个 configuration 作为 OCI artifact push 到 Docker Hub，团队成员只需一条 command 就能 pull 和 run。

kagent 把 agent orchestration 带到 Kubernetes。Custom resource definitions 让 agents 成为 first-class Kubernetes citizens。Horizontal Pod Autoscaling 会基于 demand 调整 replicas。Prometheus 和 Jaeger 提供完整 observability。Network policies 执行 security boundaries。对于需要 enterprise-grade reliability 的 production deployments，kagent 提供了 foundation。

你在第 7 章和第 8 章学到的 infrastructure patterns——agent loop、container isolation、multi-agent communication——仍然是 conceptual foundation。这些 tools 只是让这些 patterns 在各种 scale 上更容易实现。

到这里，你已经从运行单个 model，推进到构建 coordinated multi-agent systems，并使用 proper orchestration 部署它们。你已经看到 Docker Sandboxes 如何为执行 code 的 agents 提供 isolation，Docker Agent 如何通过 declarative configuration 简化 setup，以及 kagent 如何将这些 patterns 扩展到 Kubernetes，用于 scaling 和 production use。关键转变在于：把 agents 当作 structured systems，而不是 standalone scripts。它们需要与其他 infrastructure 相同的 discipline：clear roles、controlled execution 和 scalable deployment。基于这些 foundations，你可以构建更安全、更易管理，并能应对 real workloads 的 agent systems。