使用 Docker 构建和运行 Agentic AI 应用程序

简介

自主式应用程序正在改变软件的构建方式。这些应用程序不仅会响应，还会决策、规划和行动。它们由模型驱动，由代理编排，并与 API、工具和服务实时集成。

所有这些新的自主式应用程序，无论它们做什么，都共享一个共同的架构。这是一种新型的技术栈，由三个核心组件构成

模型：这些是您的 GPTs、CodeLlamas、Mistrals。它们进行推理、编写和规划。它们是智能背后的引擎。
代理：这是逻辑所在之处。代理接受一个目标，将其分解，并找出如何完成它。它们编排一切。它们与 UI、工具、模型和网关进行通信。
MCP 网关：这是将您的代理连接到外部世界（包括 API、工具和服务）的桥梁。它为代理提供了一种通过模型上下文协议 (MCP) 调用功能的标准方式。

Docker 通过将模型、工具网关和云基础设施统一到一个使用 Docker Compose 的开发者友好工作流中，使这个 AI 驱动的技术栈更简单、更快、更安全。

本指南将引导您了解自主式开发的核心组件，并展示 Docker 如何通过以下工具将它们全部联系在一起

Docker Model Runner 允许您通过简单的命令和与 OpenAI 兼容的 API 在本地运行 LLM。
Docker MCP 目录和工具包帮助您使用模型上下文协议 (MCP) 发现并安全地运行外部工具，如 API 和数据库。
Docker MCP 网关让您编排和管理 MCP 服务器。
Docker Offload 提供一个强大的、GPU 加速的环境，让您可以使用与本地相同的基于 Compose 的工作流来运行您的 AI 应用程序。
Docker Compose 是将所有这些联系在一起的工具，让您可以用一个文件定义和运行多容器应用程序。

在本指南中，您将首先在 Docker Offload 中运行应用程序，使用您已经熟悉的相同 Compose 工作流。然后，如果您的机器硬件支持，您将使用相同的工作流在本地运行相同的应用程序。最后，您将深入研究 Compose 文件、Dockerfile 和应用程序，以了解它们是如何协同工作的。

先决条件

要遵循本指南，您需要：

步骤 1：克隆示例应用程序

您将使用一个现有的示例应用程序，该应用程序演示了如何使用 Docker 的 AI 功能将模型连接到外部工具。

$ git clone https://github.com/docker/compose-for-agents.git
$ cd compose-for-agents/adk/

步骤 2：使用 Docker Offload 运行应用程序

您将首先在 Docker Offload 中运行该应用程序，它提供了一个用于运行 AI 工作负载的托管环境。如果您想利用云资源，或者您的本地机器不满足在本地运行模型的硬件要求，这是一个理想的选择。Docker Offload 支持 GPU 加速实例，非常适合像 AI 模型推理这样的计算密集型工作负载。

要使用 Docker Offload 运行应用程序，请按照以下步骤操作

登录到 Docker Desktop 仪表板。
在终端中，通过运行以下命令启动 Docker Offload
$ docker offload start
出现提示时，选择您要用于 Docker Offload 的帐户，并在提示“您需要 GPU 支持吗？”时选择“是”。
在克隆仓库的 adk/ 目录中，在终端中运行以下命令来构建和运行应用程序
$ docker compose up
首次运行此命令时，Docker 会从 Docker Hub 拉取模型，这可能需要一些时间。
应用程序现在正通过 Docker Offload 运行。请注意，使用 Docker Offload 时的 Compose 工作流与本地工作流相同。您在 `compose.yaml` 文件中定义您的应用程序，然后使用 `docker compose up` 来构建和运行它。
访问 https://:8080。在提示框中输入一个正确或错误的事实，然后按回车。一个代理会搜索 DuckDuckGo 来验证它，另一个代理会修改输出。
完成后，在终端中按 ctrl-c 停止应用程序。
运行以下命令停止 Docker Offload：
$ docker offload stop

步骤 3：可选。在本地运行应用程序

如果您的机器满足必要的硬件要求，您可以使用 Docker Compose 在本地运行整个应用程序堆栈。这使您可以端到端地测试应用程序，包括模型和 MCP 网关，而无需在云中运行。这个特定示例使用上下文大小为 10000 的 Gemma 3 4B 模型。

硬件要求

VRAM：3.5 GB
存储空间：2.31 GB

如果您的机器超过这些要求，可以考虑使用更大的上下文大小或更大的模型来运行应用程序，以提高代理的性能。您可以在 `compose.yaml` 文件中轻松更新模型和上下文大小。

要在本地运行应用程序，请按照以下步骤操作：

在克隆仓库的 adk/ 目录中，在终端中运行以下命令来构建和运行应用程序
$ docker compose up
首次运行此命令时，Docker 会从 Docker Hub 拉取模型，这可能需要一些时间。
访问 https://:8080。在提示框中输入一个正确或错误的事实，然后按回车。一个代理会搜索 DuckDuckGo 来验证它，另一个代理会修改输出。
完成后，在终端中按 ctrl-c 停止应用程序。

步骤 4：审查应用程序环境

您可以在 `adk/` 目录中找到 `compose.yaml` 文件。在文本编辑器中打开它，查看服务是如何定义的。

compose.yaml

services:
  adk:
    build:
      context: .
    ports:
      # expose port for web interface
      - "8080:8080"
    environment:
      # point adk at the MCP gateway
      - MCPGATEWAY_ENDPOINT=http://mcp-gateway:8811/sse
    depends_on:
      - mcp-gateway
    models:
      gemma3 :
        endpoint_var: MODEL_RUNNER_URL
        model_var: MODEL_RUNNER_MODEL

  mcp-gateway:
    # mcp-gateway secures your MCP servers
    image: docker/mcp-gateway:latest
    use_api_socket: true
    command:
      - --transport=sse
      # add any MCP servers you want to use
      - --servers=duckduckgo

models:
  gemma3:
    # pre-pull the model when starting Docker Model Runner
    model: ai/gemma3:4B-Q4_0
    context_size: 10000 # 3.5 GB VRAM
    # increase context size to handle search results
    # context_size: 131000 # 7.6 GB VRAM

该应用由三个主要组件组成

adk 服务，是运行自主式 AI 应用程序的 Web 应用程序。该服务与 MCP 网关和模型通信。
mcp-gateway 服务，是将应用程序连接到外部工具和服务的 MCP 网关。
models 块，定义了与应用程序一起使用的模型。

当您检查 compose.yaml 文件时，您会注意到模型的两个值得注意的元素：

adk 服务中的服务级 models 块
一个顶层 models 块

这两个块一起让 Docker Compose 自动启动并将您的 ADK Web 应用程序连接到指定的 LLM。

提示
正在寻找更多可用的模型吗？请查看 Docker AI 模型目录。

在检查 compose.yaml 文件时，您会注意到网关服务是一个由 Docker 维护的镜像，docker/mcp-gateway:latest。这个镜像是 Docker 的开源 MCP 网关，它使您的应用程序能够连接到 MCP 服务器，这些服务器公开了模型可以调用的工具。在此示例中，它使用 duckduckgo MCP 服务器来执行网页搜索。

提示
正在寻找更多可用的 MCP 服务器？请查看 Docker MCP 目录。

仅用 Compose 文件中的几行指令，您就能够运行并连接一个自主式 AI 应用程序的所有必要服务。

除了 Compose 文件之外，Dockerfile 及其创建的 `entrypoint.sh` 脚本在构建和运行时也扮演着连接 AI 技术栈的角色。您可以在 `adk/` 目录下找到 `Dockerfile`。请在文本编辑器中打开它。

Dockerfile

# Use Python 3.11 slim image as base
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1

RUN pip install uv

WORKDIR /app
# Install system dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy \
    uv pip install --system .
# Copy application code
COPY agents/ ./agents/
RUN python -m compileall -q .

COPY <<EOF /entrypoint.sh
#!/bin/sh
set -e

if test -f /run/secrets/openai-api-key; then
    export OPENAI_API_KEY=$(cat /run/secrets/openai-api-key)
fi

if test -n "\${OPENAI_API_KEY}"; then
    echo "Using OpenAI with \${OPENAI_MODEL_NAME}"
else
    echo "Using Docker Model Runner with \${MODEL_RUNNER_MODEL}"
    export OPENAI_BASE_URL=\${MODEL_RUNNER_URL}
    export OPENAI_MODEL_NAME=openai/\${MODEL_RUNNER_MODEL}
    export OPENAI_API_KEY=cannot_be_empty
fi
exec adk web --host 0.0.0.0 --port 8080 --log_level DEBUG
EOF
RUN chmod +x /entrypoint.sh

# Create non-root user
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

ENTRYPOINT [ "/entrypoint.sh" ]

entrypoint.sh 有五个关键环境变量：

MODEL_RUNNER_URL：由 Compose（通过服务级 models: 块）注入，指向您的 Docker Model Runner HTTP 端点。
MODEL_RUNNER_MODEL：由 Compose 注入，用于选择在 Model Runner 中启动哪个模型。
OPENAI_API_KEY：如果您在 Compose 文件中定义了一个 openai-api-key 密钥，Compose 会将其挂载到 /run/secrets/openai-api-key。入口点脚本会读取该文件并将其导出为 OPENAI_API_KEY，从而使应用程序使用托管的 OpenAI 而不是 Model Runner。
OPENAI_BASE_URL：当没有真实的密钥时，此项被设置为 MODEL_RUNNER_URL，以便 ADK 的 OpenAI 兼容客户端将请求发送到 Docker Model Runner。
OPENAI_MODEL_NAME：当回退到 Model Runner 时，模型名称前会加上 `openai/` 前缀，以便客户端能找到正确的模型别名。

总的来说，这些变量让同一个 ADK Web 服务器代码能够无缝地针对以下任一目标：

托管的 OpenAI：如果您提供 OPENAI_API_KEY（以及可选的 OPENAI_MODEL_NAME）
Model Runner：通过将 MODEL_RUNNER_URL 和 MODEL_RUNNER_MODEL 重新映射到 OpenAI 客户端预期的变量中

步骤 5：审查应用程序

adk Web 应用程序是一个代理实现，通过环境变量和 API 调用连接到 MCP 网关和模型。它使用 ADK (Agent Development Kit) 定义一个名为 Auditor 的根代理，该代理协调两个子代理 Critic 和 Reviser，以验证和完善模型生成的答案。

这三个代理是：

批评家（Critic）：使用工具集（如 DuckDuckGo）验证事实性声明。
修订者（Reviser）：根据批评家提供的验证结论编辑答案。
审计员（Auditor）：一个更高级别的代理，它按顺序安排批评家和修订者的工作。它作为入口点，评估 LLM 生成的答案，验证它们，并完善最终输出。

应用程序的所有行为都在 `agents/` 目录下的 Python 中定义。以下是主要文件的分解说明：

agents/agent.py：定义了 Auditor，一个将 Critic 和 Reviser 代理连接在一起的 SequentialAgent。该代理是应用程序的主要入口点，负责使用真实世界的验证工具来审核 LLM 生成的内容。
agents/sub_agents/critic/agent.py：定义了 Critic 代理。它加载语言模型（通过 Docker Model Runner），设置代理的名称和行为，并连接到 MCP 工具（如 DuckDuckGo）。
agents/sub_agents/critic/prompt.py：包含 Critic 的提示，指示代理使用外部工具提取并验证声明。
agents/sub_agents/critic/tools.py：定义 MCP 工具集配置，包括解析 mcp/ 字符串、创建工具连接以及处理 MCP 网关通信。
agents/sub_agents/reviser/agent.py：定义 Reviser 代理，它接收 Critic 的发现并对原始答案进行最少的重写。它还包括清理 LLM 输出并确保其格式正确的回调。
agents/sub_agents/reviser/prompt.py：包含修订者（Reviser）的提示，指示代理根据已验证的声明结论来修订答案文本。

MCP 网关通过 MCPGATEWAY_ENDPOINT 环境变量进行配置。在本例中，为 http://mcp-gateway:8811/sse。这允许应用程序使用服务器发送事件 (SSE) 与 MCP 网关容器通信，该容器本身代理对 DuckDuckGo 等外部工具服务的访问。

摘要

基于代理的 AI 应用程序正在成为一种强大的新型软件架构。在本指南中，您探索了一个模块化的思维链系统，其中一个 Auditor 代理协调 Critic 和 Reviser 的工作，以进行事实核查并完善模型生成的答案。这种架构展示了如何以结构化、模块化的方式将本地模型推理与外部工具集成相结合。

您还看到了 Docker 如何通过提供一套支持本地和云端自主式 AI 开发的工具来简化这一过程：

Docker Model Runner：通过 OpenAI 兼容的 API 在本地运行并提供开源模型服务。
Docker MCP 目录和工具包：启动和管理遵循模型上下文协议 (MCP) 标准的工具集成。
Docker MCP 网关：编排和管理 MCP 服务器，将代理连接到外部工具和服务。
Docker Compose：使用单个文件定义和运行多容器自主式 AI 应用程序，在本地和云中使用相同的工作流。
Docker Offload：在安全、托管的云环境中使用与本地相同的 Docker Compose 工作流运行 GPU 密集型 AI 工作负载。

有了这些工具，您可以在本地或云端高效地开发和测试自主式 AI 应用程序，始终使用相同且一致的工作流程。