使用 Docker 構建和執行 Agentic AI 應用程式

目錄

簡介

自主式應用程式正在改變軟體的構建方式。這些應用程式不僅會響應，還會決策、規劃和行動。它們由模型驅動，由代理編排，並與 API、工具和服務即時整合。

所有這些新的自主式應用程式，無論它們做什麼，都共享一個共同的架構。這是一種新型的技術棧，由三個核心元件構成

  • 模型：這些是您的 GPTs、CodeLlamas、Mistrals。它們進行推理、編寫和規劃。它們是智慧背後的引擎。

  • 代理：這是邏輯所在之處。代理接受一個目標，將其分解，並找出如何完成它。它們編排一切。它們與 UI、工具、模型和閘道器進行通訊。

  • MCP 閘道器：這是將您的代理連線到外部世界（包括 API、工具和服務）的橋樑。它為代理提供了一種透過模型上下文協議 (MCP) 呼叫功能的標準方式。

Docker 透過將模型、工具閘道器和雲基礎設施統一到一個使用 Docker Compose 的開發者友好工作流中，使這個 AI 驅動的技術棧更簡單、更快、更安全。

A diagram of the agentic stack

本指南將引導您瞭解自主式開發的核心元件，並展示 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 執行應用程式，請按照以下步驟操作

  1. 登入到 Docker Desktop 儀表板。

  2. 在終端中，透過執行以下命令啟動 Docker Offload

    $ docker offload start

    出現提示時，選擇您要用於 Docker Offload 的帳戶，並在提示“您需要 GPU 支援嗎？”時選擇“是”。

  3. 在克隆倉庫的 adk/ 目錄中，在終端中執行以下命令來構建和執行應用程式

    $ docker compose up

    首次執行此命令時，Docker 會從 Docker Hub 拉取模型，這可能需要一些時間。

    應用程式現在正透過 Docker Offload 執行。請注意，使用 Docker Offload 時的 Compose 工作流與本地工作流相同。您在 `compose.yaml` 檔案中定義您的應用程式，然後使用 `docker compose up` 來構建和執行它。

  4. 訪問 https://:8080。在提示框中輸入一個正確或錯誤的事實，然後按回車。一個代理會搜尋 DuckDuckGo 來驗證它，另一個代理會修改輸出。

    Screenshot of the application

  5. 完成後，在終端中按 ctrl-c 停止應用程式。

  6. 執行以下命令停止 Docker Offload：

    $ docker offload stop

步驟 3：可選。在本地執行應用程式

如果您的機器滿足必要的硬體要求，您可以使用 Docker Compose 在本地執行整個應用程式堆疊。這使您可以端到端地測試應用程式，包括模型和 MCP 閘道器，而無需在雲中執行。這個特定示例使用上下文大小為 10000 的 Gemma 3 4B 模型。

硬體要求

  • VRAM：3.5 GB
  • 儲存空間：2.31 GB

如果您的機器超過這些要求，可以考慮使用更大的上下文大小或更大的模型來執行應用程式，以提高代理的效能。您可以在 `compose.yaml` 檔案中輕鬆更新模型和上下文大小。

要在本地執行應用程式，請按照以下步驟操作：

  1. 在克隆倉庫的 adk/ 目錄中，在終端中執行以下命令來構建和執行應用程式

    $ docker compose up

    首次執行此命令時，Docker 會從 Docker Hub 拉取模型，這可能需要一些時間。

  2. 訪問 https://:8080。在提示框中輸入一個正確或錯誤的事實，然後按回車。一個代理會搜尋 DuckDuckGo 來驗證它，另一個代理會修改輸出。

  3. 完成後，在終端中按 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 應用程式，始終使用相同且一致的工作流程。