Docker Compose for Agents：Docker 官方的 AI Agent 编排实战范本

想象这样一个场景：你是一名 AI 应用开发者，想快速验证某个 Agent 框架的实际效果——但光是搭环境、配依赖就花了大半天。Docker 官方推出的 Compose for Agents 正是为解决这个问题而来：它把 14 种主流 Agent 框架的完整示例打包成 Docker Compose 项目，开发者只需一条命令，就能让一个完整的多 Agent 系统在本地跑起来。

背景：为什么 Docker 要做 Agent 编排示例？

2024 年下半年，AI Agent 从概念走向落地，各种 Agent 框架（A2A、LangGraph、CrewAI、Agno 等）如雨后春笋般涌现。然而，每种框架的安装和运行方式各不相同，开发者常常需要翻阅大量文档、解决版本冲突、管理 API Key，才能让一个 demo 跑通。Docker 作为容器化的事实标准，在这一年推出了 Docker Model Runner——一种让 Docker Desktop 原生支持本地大模型推理的技术。在这一背景下，compose-for-agents 应运而生：它既是 Docker Model Runner 的官方展示，也是一份面向 AI 开发者的"一键启动指南"。

项目由 Docker 官方组织维护，Apache 2.0 开源协议，目前 Stars 981、Forks 431，是同类型项目中 star 数最高的合集类仓库。

核心功能：14 个框架，一个入口

compose-for-agents 的本质是一个多子项目合集，每个子目录对应一个 Agent 框架的完整可运行示例。目前已涵盖：

Agent 框架	语言	特点	示例场景
A2A（Agent2Agent SDK）	Python	MCP 协议协作，多角色分工	事实核查（Auditor/Critic/Reviser）
ADK（Agent Development Kit）	Python	Google 官方，工具调用	事实核查
Agno	Python	结构化 Agent 定义，多工具	GitHub Issue 分析
CrewAI	Python	多代理编排，角色扮演	复杂任务分解
LangGraph	Python	图状工作流，状态管理	数据库问答
Langchaingo	Go	Go 语言 LLM 集成	DuckDuckGo 搜索
Vercel AI SDK	TypeScript	前端友好，流式响应	Web UI + MCP 混合
Spring AI	Java	企业级集成	Java 生态对接
Akka	Scala/Java	分布式 Actor 模型	高并发场景

每个子目录都是一个完整的 Docker Compose 项目，结构统一：

compose.yaml — 基础配置（定义服务、模型、端口）
compose.openai.yaml — OpenAI API 覆盖层（如需使用云端模型）
compose.offload.yaml — Docker Offload 覆盖层（使用远程 GPU 实例）
compose.dmr.yaml — Docker Model Runner 覆盖层

这种分层层叠设计是项目最值得称道的地方：同一个 demo，开发者可以根据硬件条件选择本地推理（默认）、云端 OpenAI API、或远程 GPU Offload，不需要修改基础配置。

A2A Multi-Agent Fact Check Demo

图1：A2A 框架的事实核查 Demo 运行效果

技术架构：MCP 协议 + Model Runner

从 compose.yaml 的配置可以清晰看到项目的核心架构。

Agent 服务层：以 Agno demo 为例，agents 服务定义了与 MCP Gateway 的通信协议，agents.yaml 声明了具体的 Agent 行为（Coordinator / Issue Retriever / Writer 三种角色）。agents-ui 服务提供 Web 界面（端口 3000），通过 HTTP 与 Agent 通信。

MCP 网关层：mcp-gateway 服务是 Docker 官方组件（docker/mcp-gateway:latest），它通过 Docker API Socket 自动启动 MCP 服务器，并将外部 MCP 工具（如 GitHub MCP、DuckDuckGo MCP）安全注入 Agent 运行时。每个 Agent 容器不需要自己管理 MCP 连接，统一由 Gateway 代理。

推理层：默认使用 Docker Model Runner（通过 MODEL_RUNNER_URL 环境变量），支持 Qwen3 8B/14B 等开源模型在本地 GPU 运行。对于没有本地 GPU 的用户，OpenAI 模式提供了零门槛的备选方案。

ADK Multi-Agent Fact Check Demo

图2：ADK 框架的事实核查 Demo 运行效果

部署体验：一行命令背后的工程细节

部署体验是项目最核心的卖点。标准流程只需三步：

# 1. 进入目标 demo 目录
cd agno

# 2. 配置密钥（如需要 MCP 工具）
cp .mcp.env.example .mcp.env
# 填入 GitHub Personal Access Token

# 3. 启动
docker compose up --build

项目还内置了 Taskfile.yaml（基于 Go Task）用于开发流程中的代码质量检查，包括 markdownlint 和 yamllint 两个任务，通过 Docker 容器运行，无需宿主机安装任何工具。

部署难度被评为"简单"，预估时间 10 分钟。关键前提是安装 Docker Desktop 4.43.0+（内置 Model Runner）或 Docker Engine + 独立 Model Runner。有 GPU 的用户可以直接运行本地模型（推荐 8GB+ 显存），无 GPU 用户通过 OpenAI 模式或 Docker Offload（远程 GPU）也能运行。

上手门槛与适用人群

维度	说明
编程要求	几乎不需要（配置 token 即可运行），但阅读 agent 逻辑需要 Python/Go 基础
AI 知识要求	理解 Agent、Tool、LLM 调用等基本概念
Docker 技能	需要基础操作能力（compose up/down、端口查看）
适用场景	快速验证 Agent 框架、演示多 Agent 协作、搭建本地 AI 实验环境
不适用场景	生产环境直接部署（示例未做高可用/安全加固）

局限与争议

项目并非完美，以下几点值得注意：

示例非生产级：每个 demo 都是最小可用实现，缺少错误处理、日志、监控等工程组件，开发者不能直接将其投入生产。
Docker Desktop 强依赖：虽然解决了环境一致性，但要求开发者在本地安装 Docker Desktop，在 CI/CD 环境或纯服务器场景下可能不够灵活。
MCP 协议成熟度：MCP（Model Context Protocol）在 2025 年仍是快速演进的协议，各框架对 MCP 的支持程度不一致，部分 demo 依赖特定版本的 MCP Gateway。
资源占用：本地运行 Qwen3 14B 模型需要约 15GB 显存，即使 8B 模型也需要 7GB+ VRAM，硬件门槛并不低。

行业意义：降低 Agent 开发的"第一次接触"成本

compose-for-agents 的最大价值不在于某个具体 demo，而在于它建立了一种可复制的 Agent 开发工作流标准：框架选型 → Docker 一键启动 → 观察 Agent 行为 → 迭代改进。这种范式让 AI 研究者和应用开发者不需要在环境配置上花费大量时间，可以专注于 Agent 逻辑本身。

从增长曲线看，项目在 2025 年上线后快速积累了接近千星的人气，反映了市场对"开箱即用的 Agent 示例"这一品类的强烈需求。可以预见，随着更多 Agent 框架加入（如 AutoGen、AutoGPT），这一合集将继续扩展，成为 Docker 生态在 AI 领域的重要入口。

Langchaingo DuckDuckGo Search Demo

图3：Langchaingo 框架的 DuckDuckGo 搜索 Demo 运行效果

数据来源：GitHub API（docker/compose-for-agents），采集时间 2026-06-16。图片均为 GitHub 仓库内嵌 demo 截图，经 curl 验证 HTTP 200。