部署到 Cloud Run

Cloud Run 是一个完全托管的平台，使你能够直接在 Google 可扩展基础设施上运行代码。

要部署你的智能体，你可以使用 adk deploy cloud_run 命令（推荐），或通过 Cloud Run 使用 gcloud run deploy 命令。

智能体示例

对于每个命令，我们将引用 LLM 智能体 页面中定义的 capital_agent 示例。我们假设它位于 capital_agent 目录中。

继续之前，请确认你的智能体代码配置如下：

1. 智能体代码位于你的智能体目录中名为 agent.py 的文件中。
2. 你的智能体变量名为 root_agent。
3. __init__.py 位于你的智能体目录中，并包含 from . import agent。

环境变量

按照 设置和安装 指南中描述的设置环境变量。

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1 # 或你偏好的位置
export GOOGLE_GENAI_USE_VERTEXAI=True

（将 your-project-id 替换为你实际的 GCP 项目 ID）

部署命令

adk CLIgcloud CLI

adk CLI

adk deploy cloud_run 命令将你的智能体代码部署到 Google Cloud Run。

确保你已通过 Google Cloud 进行身份验证（gcloud auth login 和 gcloud config set project <your-project-id>）。

设置环境变量

可选但推荐：设置环境变量可以使部署命令更简洁。

# 设置你的 Google Cloud 项目 ID
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# 设置你期望的 Google Cloud 位置
export GOOGLE_CLOUD_LOCATION="us-central1" # 示例位置

# 设置你的智能体代码目录路径
export AGENT_PATH="./capital_agent" # 假设 capital_agent 在当前目录中

# 设置你的 Cloud Run 服务名称（可选）
export SERVICE_NAME="capital-agent-service"

# 设置应用程序名称（可选）
export APP_NAME="capital-agent-app"

命令用法

最小命令

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
$AGENT_PATH

带可选标志的完整命令

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH

参数

• AGENT_PATH：（必需）指定包含你的智能体源代码的目录路径的位置参数（例如，示例中的 $AGENT_PATH 或 capital_agent/）。该目录必须至少包含一个 __init__.py 和你的主智能体文件（例如 agent.py）。

选项

• --project TEXT：（必需）你的 Google Cloud 项目 ID（例如，$GOOGLE_CLOUD_PROJECT）。
• --region TEXT：（必需）部署的 Google Cloud 位置（例如，$GOOGLE_CLOUD_LOCATION，us-central1）。
• --service_name TEXT：（可选）Cloud Run 服务的名称（例如，$SERVICE_NAME）。默认为 adk-default-service-name。
• --app_name TEXT：（可选）ADK API 服务器的应用程序名称（例如，$APP_NAME）。默认为由 AGENT_PATH 指定的目录名称（例如，如果 AGENT_PATH 是 ./capital_agent，则为 capital_agent）。
• --agent_engine_id TEXT：（可选）如果你通过 Vertex AI Agent Engine 使用托管会话服务，请在此处提供其资源 ID。
• --port INTEGER：（可选）ADK API 服务器在容器内监听的端口号。默认为 8000。
• --with_ui：（可选）如果包含，将与智能体 API 服务器一起部署 ADK 开发 UI。默认情况下，仅部署 API 服务器。
• --temp_folder TEXT：（可选）指定用于存储部署过程中生成的中间文件的目录。默认为系统临时目录中的时间戳文件夹。（注意：除非排除故障，否则通常不需要此选项）。
• --help：显示帮助信息并退出。

身份验证访问

在部署过程中，你可能会收到提示：Allow unauthenticated invocations to [your-service-name] (y/N)?。

• 输入 y 允许在没有身份验证的情况下公开访问你的智能体的 API 端点。
• 输入 N（或按 Enter 键使用默认值）要求身份验证（例如，使用"测试你的智能体"部分中显示的身份令牌）。

成功执行后，命令将你的智能体部署到 Cloud Run 并提供已部署服务的 URL。

gcloud CLI

或者，你可以使用标准的 gcloud run deploy 命令和 Dockerfile 进行部署。与 adk 命令相比，这种方法需要更多的手动设置，但提供了灵活性，特别是如果你想要将智能体嵌入到自定义 FastAPI 应用程序中。

确保你已通过 Google Cloud 进行身份验证（gcloud auth login 和 gcloud config set project <your-project-id>）。

项目结构

按如下方式组织你的项目文件：

your-project-directory/
├── capital_agent/
│   ├── __init__.py
│   └── agent.py       # 你的智能体代码（见"智能体示例"标签）
├── main.py            # FastAPI 应用程序入口点
├── requirements.txt   # Python 依赖项
└── Dockerfile         # 容器构建说明

在 your-project-directory/ 的根目录下创建以下文件（main.py、requirements.txt、Dockerfile）。

代码文件

1. 这个文件使用 ADK 的 get_fast_api_app() 设置 FastAPI 应用程序：

   main.py

   import os
   
   import uvicorn
   from fastapi import FastAPI
   from google.adk.cli.fast_api import get_fast_api_app
   
   # Get the directory where main.py is located
   AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
   # Example session DB URL (e.g., SQLite)
   SESSION_DB_URL = "sqlite:///./sessions.db"
   # Example allowed origins for CORS
   ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
   # Set web=True if you intend to serve a web interface, False otherwise
   SERVE_WEB_INTERFACE = True
   
   # Call the function to get the FastAPI app instance
   # Ensure the agent directory name ('capital_agent') matches your agent folder
   app: FastAPI = get_fast_api_app(
       agent_dir=AGENT_DIR,
       session_db_url=SESSION_DB_URL,
       allow_origins=ALLOWED_ORIGINS,
       web=SERVE_WEB_INTERFACE,
   )
   
   # You can add more FastAPI routes or configurations below if needed
   # Example:
   # @app.get("/hello")
   # async def read_root():
   #     return {"Hello": "World"}
   
   if __name__ == "__main__":
       # Use the PORT environment variable provided by Cloud Run, defaulting to 8080
       uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
   

   注意：我们将 agent_dir 指定为 main.py 所在的目录，并使用 os.environ.get("PORT", 8080) 以确保与 Cloud Run 兼容。

2. 列出必要的 Python 包：

   requirements.txt

   google_adk
   # Add any other dependencies your agent needs
   

3. 定义容器映像：

   Dockerfile

   FROM python:3.13-slim
   WORKDIR /app
   
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   
   RUN adduser --disabled-password --gecos "" myuser && \
       chown -R myuser:myuser /app
   
   COPY . .
   
   USER myuser
   
   ENV PATH="/home/myuser/.local/bin:$PATH"
   
   CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"]
   

使用 gcloud 部署

在终端中导航到 your-project-directory。

gcloud run deploy capital-agent-service \
--source . \
--region $GOOGLE_CLOUD_LOCATION \
--project $GOOGLE_CLOUD_PROJECT \
--allow-unauthenticated \
--set-env-vars="GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_VERTEXAI=$GOOGLE_GENAI_USE_VERTEXAI"
# Add any other necessary environment variables your agent might need

• capital-agent-service：你想要给 Cloud Run 服务的名称。
• --source .：告诉 gcloud 从当前目录的 Dockerfile 构建容器映像。
• --region：指定部署区域。
• --project：指定 GCP 项目。
• --allow-unauthenticated：允许公开访问服务。为私有服务删除此标志。
• --set-env-vars：将必要的环境变量传递给运行的容器。确保包含 ADK 和你的智能体所需的所有变量（如 API 密钥，如果不使用应用程序默认凭据）。

gcloud 将构建 Docker 映像，将其推送到 Google Artifact Registry，并将其部署到 Cloud Run。完成后，它将输出已部署服务的 URL。

有关部署选项的完整列表，请参阅 gcloud run deploy 参考文档。

测试你的智能体

一旦你的智能体部署到 Cloud Run，你可以通过已部署的 UI（如果启用）或使用 curl 等工具直接与其 API 端点交互。你需要部署后提供的服务 URL。

UI TestingAPI Testing (curl)

UI 测试

如果你部署了带有 UI 的智能体：

• adk CLI：你在部署期间包含了 --with_ui 标志。
• gcloud CLI：你在 main.py 中设置了 SERVE_WEB_INTERFACE = True。

你可以通过在网络浏览器中导航到部署后提供的 Cloud Run 服务 URL 来测试你的智能体。

# 示例 URL 格式
# https://your-service-name-abc123xyz.a.run.app

ADK 开发 UI 允许你直接在浏览器中与你的智能体交互，管理会话并查看执行详情。

要验证你的智能体是否按预期工作，你可以：

1. 从下拉菜单中选择你的智能体。
2. 输入一条消息并验证你是否收到来自你的智能体的预期响应。

如果遇到任何意外行为，请检查 Cloud Run 控制台日志。

API 测试 (curl)

你可以使用 curl 等工具与智能体的 API 端点交互。这对于程序化交互或者如果你部署时没有启用 UI 非常有用。

你需要部署后提供的服务 URL，如果你的服务未设置为允许未经身份验证的访问，可能还需要一个身份令牌进行身份验证。

设置应用程序 URL

将示例 URL 替换为你部署的 Cloud Run 服务的实际 URL。

export APP_URL="YOUR_CLOUD_RUN_SERVICE_URL"
# 示例：export APP_URL="https://adk-default-service-name-abc123xyz.a.run.app"

获取身份令牌（如需要）

如果你的服务需要身份验证（即，你没有使用 gcloud 的 --allow-unauthenticated 或在 adk 提示中回答了 'N'），请获取身份令牌。

export TOKEN=$(gcloud auth print-identity-token)

如果你的服务允许未经身份验证的访问，你可以在下面的 curl 命令中省略 -H "Authorization: Bearer $TOKEN" 标头。

列出可用的应用程序

验证已部署的应用程序名称。

curl -X GET -H "Authorization: Bearer $TOKEN" $APP_URL/list-apps

（如有需要，根据此输出调整以下命令中的 app_name。默认通常是智能体目录名称，例如 capital_agent）。

创建或更新会话

为特定用户和会话初始化或更新状态。如果不同，请将 capital_agent 替换为你的实际应用程序名称。值 user_123 和 session_abc 是示例标识符；你可以将它们替换为你想要的用户和会话 ID。

curl -X POST -H "Authorization: Bearer $TOKEN" \
    $APP_URL/apps/capital_agent/users/user_123/sessions/session_abc \
    -H "Content-Type: application/json" \
    -d '{"state": {"preferred_language": "English", "visit_count": 5}}'

运行智能体

向你的智能体发送提示。根据需要替换 capital_agent 为你的应用程序名称，并调整用户/会话 ID 和提示。

curl -X POST -H "Authorization: Bearer $TOKEN" \
    $APP_URL/run_sse \
    -H "Content-Type: application/json" \
    -d '{
    "app_name": "capital_agent",
    "user_id": "user_123",
    "session_id": "session_abc",
    "new_message": {
        "role": "user",
        "parts": [{
        "text": "What is the capital of Canada?"
        }]
    },
    "streaming": false
    }'

• 如果你想接收服务器发送事件 (SSE)，请设置 "streaming": true。
• 响应将包含智能体的执行事件，包括最终答案。