部署到 Google Kubernetes Engine (GKE)

Supported in ADKPython

GKE 是 Google Cloud 托管的 Kubernetes 服务。它允许你使用 Kubernetes 部署和管理容器化应用程序。

要部署你的智能体，你需要在 GKE 上运行一个 Kubernetes 集群。你可以使用 Google Cloud 控制台或 gcloud 命令行工具创建集群。

在这个示例中，我们将部署一个简单的智能体到 GKE。该智能体将是一个使用 Gemini 2.0 Flash 作为 LLM 的 FastAPI 应用程序。我们可以使用环境变量 GOOGLE_GENAI_USE_VERTEXAI 来使用 Vertex AI 或 AI Studio 作为 LLM 提供者。

环境变量

按照设置和安装指南中的描述设置你的环境变量。你还需要安装 kubectl 命令行工具。你可以在 Google Kubernetes Engine 文档 中找到操作说明。

export GOOGLE_CLOUD_PROJECT=your-project-id # 你的 GCP 项目 ID
export GOOGLE_CLOUD_LOCATION=us-central1 # 或你偏好的位置
export GOOGLE_GENAI_USE_VERTEXAI=true # 如果使用 Vertex AI，设置为 true
export GOOGLE_CLOUD_PROJECT_NUMBER=$(gcloud projects describe --format json $GOOGLE_CLOUD_PROJECT | jq -r ".projectNumber")

如果你没有安装 jq，可以使用以下命令获取项目编号：

gcloud projects describe $GOOGLE_CLOUD_PROJECT

然后从输出中复制项目编号。

export GOOGLE_CLOUD_PROJECT_NUMBER=YOUR_PROJECT_NUMBER

启用 API 和权限

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

为你的项目启用必要的 API。你可以使用 gcloud 命令行工具完成此操作。

gcloud services enable \
    container.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com

为 gcloud builds submit 命令所需的默认计算引擎服务账号授予必要的角色。

ROLES_TO_ASSIGN=(
    "roles/artifactregistry.writer"
    "roles/storage.objectViewer"
    "roles/logging.viewer"
    "roles/logging.logWriter"
)

for ROLE in "${ROLES_TO_ASSIGN[@]}"; do
    gcloud projects add-iam-policy-binding "${GOOGLE_CLOUD_PROJECT}" \
        --member="serviceAccount:${GOOGLE_CLOUD_PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
        --role="${ROLE}"
done

部署内容

当你将 ADK 智能体工作流部署到 Google Cloud GKE 时， 以下内容会上传到服务：

• 你的 ADK 智能体代码
• 你的 ADK 智能体代码中声明的任何依赖项
• 你的智能体使用的 ADK API 服务器代码版本

默认部署 不包含 ADK Web 用户界面库， 除非你将其指定为部署设置，例如 adk deploy gke 命令的 --with_ui 选项。

部署选项

你可以使用 Kubernetes manifest 手动或使用 adk deploy gke 命令自动将你的智能体部署到 GKE。选择最适合你工作流程的方法。

选项 1：使用 gcloud 和 kubectl 手动部署

使用 gcloud 和 kubectl 手动部署

创建 GKE 集群

你可以使用 gcloud 命令行工具创建 GKE 集群。这个例子在 us-central1 区域创建一个名为 adk-cluster 的 Autopilot 集群。

如果创建 GKE Standard 集群，请确保启用 Workload Identity。Workload Identity 在 AutoPilot 集群中默认启用。

gcloud container clusters create-auto adk-cluster \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$GOOGLE_CLOUD_PROJECT

创建集群后，你需要使用 kubectl 连接到它。此命令配置 kubectl 使用新集群的凭证。

gcloud container clusters get-credentials adk-cluster \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$GOOGLE_CLOUD_PROJECT

创建你的智能体

我们将参考LLM 智能体页面中定义的 capital_agent 示例。

要继续，请按照以下方式组织你的项目文件：

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

代码文件

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

1. 这是 capital_agent 目录内的 Capital Agent 示例

   capital_agent/agent.py

   from google.adk.agents import LlmAgent 
   
   # 定义一个工具函数
   def get_capital_city(country: str) -> str:
     """检索给定国家的首都城市。"""
     # 替换为实际逻辑（例如，API 调用、数据库查找）
     capitals = {"france": "Paris", "japan": "Tokyo", "canada": "Ottawa"}
     return capitals.get(country.lower(), f"抱歉，我不知道 {country} 的首都。")
   
   # 将工具添加到智能体
   capital_agent = LlmAgent(
       model="gemini-2.0-flash",
       name="capital_agent", # 你的智能体名称
       description="回答用户关于给定国家首都城市的问题。",
       instruction="""你是一个提供国家首都城市的智能体...（之前的指令文本）""",
       tools=[get_capital_city] # 直接提供函数
   )
   
   # ADK 将发现 root_agent 实例
   root_agent = capital_agent
   

   将你的目录标记为 python 包

   capital_agent/__init__.py

   from . import agent
   

2. 此文件使用 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
   
   # 获取 main.py 所在的目录
   AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
   # 示例会话数据库 URL（例如，SQLite）
   SESSION_SERVICE_URI = "sqlite:///./sessions.db"
   # 用于 CORS 的示例允许源
   ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
   # 设置 web=True 如果你打算提供 web 界面，否则为 False
   SERVE_WEB_INTERFACE = True
   
   # 调用函数获取 FastAPI 应用程序实例
   # 确保智能体目录名称（'capital_agent'）与你的智能体文件夹匹配
   app: FastAPI = get_fast_api_app(
       agents_dir=AGENT_DIR,
       session_service_uri=SESSION_SERVICE_URI,
       allow_origins=ALLOWED_ORIGINS,
       web=SERVE_WEB_INTERFACE,
   )
   
   # 如果需要，你可以在下面添加更多 FastAPI 路由或配置
   # 示例：
   # @app.get("/hello")
   # async def read_root():
   #     return {"Hello": "World"}
   
   if __name__ == "__main__":
       # 使用 Cloud Run 提供的 PORT 环境变量，默认为 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。

3. 列出必要的 Python 包：

   requirements.txt

   google-adk
   # 添加你的智能体需要的任何其他依赖项
   

4. 定义容器镜像：

   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"]
   

构建容器镜像

你需要创建一个 Google Artifact Registry 仓库来存储你的容器镜像。你可以使用 gcloud 命令行工具完成此操作。

gcloud artifacts repositories create adk-repo \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_LOCATION \
    --description="ADK 仓库"

使用 gcloud 命令行工具构建容器镜像。此示例将镜像标记为 adk-repo/adk-agent:latest。

gcloud builds submit \
    --tag $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest \
    --project=$GOOGLE_CLOUD_PROJECT \
    .

验证镜像已构建并推送到 Artifact Registry：

gcloud artifacts docker images list \
  $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo \
  --project=$GOOGLE_CLOUD_PROJECT

为 Vertex AI 配置 Kubernetes 服务账号

如果你的智能体使用 Vertex AI，你需要创建具有必要权限的 Kubernetes 服务账号。此示例创建名为 adk-agent-sa 的服务账号，并将其绑定到 Vertex AI User 角色。

如果你使用 AI Studio 并通过 API key 访问模型，可以跳过此步骤。

kubectl create serviceaccount adk-agent-sa

gcloud projects add-iam-policy-binding projects/${GOOGLE_CLOUD_PROJECT} \
    --role=roles/aiplatform.user \
    --member=principal://iam.googleapis.com/projects/${GOOGLE_CLOUD_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GOOGLE_CLOUD_PROJECT}.svc.id.goog/subject/ns/default/sa/adk-agent-sa \
    --condition=None

创建 Kubernetes manifest 文件

在你的项目目录中创建名为 deployment.yaml 的 Kubernetes 部署清单文件。此文件定义如何在 GKE 上部署你的应用程序。

deployment.yaml

cat <<  EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: adk-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: adk-agent
  template:
    metadata:
      labels:
        app: adk-agent
    spec:
      serviceAccount: adk-agent-sa
      containers:
      - name: adk-agent
        imagePullPolicy: Always
        image: $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"
            ephemeral-storage: "128Mi"
          requests:
            memory: "128Mi"
            cpu: "500m"
            ephemeral-storage: "128Mi"
        ports:
        - containerPort: 8080
        env:
          - name: PORT
            value: "8080"
          - name: GOOGLE_CLOUD_PROJECT
            value: $GOOGLE_CLOUD_PROJECT
          - name: GOOGLE_CLOUD_LOCATION
            value: $GOOGLE_CLOUD_LOCATION
          - name: GOOGLE_GENAI_USE_VERTEXAI
            value: "$GOOGLE_GENAI_USE_VERTEXAI"
          # 如果使用 AI Studio，将 GOOGLE_GENAI_USE_VERTEXAI 设置为 false 并设置以下内容：
          # - name: GOOGLE_API_KEY
          #   value: $GOOGLE_API_KEY
          # 添加你的智能体可能需要的任何其他环境变量
---
apiVersion: v1
kind: Service
metadata:
  name: adk-agent
spec:       
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: adk-agent
EOF

部署应用程序

使用 kubectl 命令行工具部署应用程序。此命令将部署和服务清单文件应用到你的 GKE 集群。

kubectl apply -f deployment.yaml

几分钟后，你可以使用以下命令检查部署状态：

kubectl get pods -l=app=adk-agent

此命令列出与你的部署相关的 pod。你应该会看到一个状态为 Running 的 pod。

一旦 pod 运行起来，你可以使用以下命令检查服务状态：

kubectl get service adk-agent

如果输出显示一个 External IP，这意味着你的服务可以从互联网访问。外部 IP 分配可能需要几分钟时间。

你可以使用以下命令获取服务的外部 IP 地址：

kubectl get svc adk-agent -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'

选项 2：使用 adk deploy gke 自动部署

ADK 提供 CLI 命令来简化 GKE 部署。这避免了手动构建镜像、编写 Kubernetes manifest 或推送到 Artifact Registry 的需要。

前置条件

在开始之前，确保你已设置以下内容：

1. 运行中的 GKE 集群： 你需要在 Google Cloud 上有一个活跃的 Kubernetes 集群。

2. 必需的 CLI：

   • gcloud CLI： Google Cloud CLI 必须已安装、已认证并配置为使用你的目标项目。运行 gcloud auth login 和 gcloud config set project [YOUR_PROJECT_ID]。
   • kubectl： 必须安装 Kubernetes CLI 才能将应用程序部署到你的集群。

3. 启用的 Google Cloud API： 确保在你的 Google Cloud 项目中启用了以下 API：

   • Kubernetes Engine API (container.googleapis.com)
   • Cloud Build API (cloudbuild.googleapis.com)
   • Container Registry API (containerregistry.googleapis.com)

4. 必需的 IAM 权限： 运行命令的用户或计算引擎默认服务账号至少需要以下角色：

5. Kubernetes Engine Developer (roles/container.developer)：与 GKE 集群交互。

6. Storage Object Viewer (roles/storage.objectViewer)：允许 Cloud Build 从 gcloud builds submit 上传的 Cloud Storage 存储桶下载源代码。

7. Artifact Registry Create on Push Writer (roles/artifactregistry.createOnPushWriter)：允许 Cloud Build 将构建的容器镜像推送到 Artifact Registry。此角色还允许在首次推送时在 Artifact Registry 内按需创建特殊的 gcr.io 仓库。

8. Logs Writer (roles/logging.logWriter)：允许 Cloud Build 将构建日志写入 Cloud Logging。

deploy gke 命令

该命令接受你的智能体路径和指定目标 GKE 集群的参数。

语法

adk deploy gke [OPTIONS] AGENT_PATH

参数和选项

参数	描述	必需
AGENT_PATH	你的智能体根目录的本地文件路径。	是
--project	你的 GKE 集群所在的 Google Cloud 项目 ID。	是
--cluster_name	你的 GKE 集群的名称。	是
--region	你的集群的 Google Cloud 区域（例如，us-central1）。	是
--with_ui	部署智能体的后端 API 和配套的前端用户界面。	否
--log_level	设置部署过程的日志级别。选项：debug、info、warning、error。	否

工作原理

当你运行 adk deploy gke 命令时，ADK 会自动执行以下步骤：

• 容器化：从你的智能体源代码构建 Docker 容器镜像。

• 镜像推送：为容器镜像打标签并推送到你的项目的 Artifact Registry。

• Manifest 生成：动态生成必要的 Kubernetes manifest 文件（Deployment 和 Service）。

• 集群部署：将这些 manifest 应用到你指定的 GKE 集群，这会触发以下操作：

Deployment 指示 GKE 从 Artifact Registry 拉取容器镜像并在一个或多个 Pod 中运行。

Service 为你的智能体创建稳定的网络端点。默认情况下，这是一个 LoadBalancer 服务，它提供公共 IP 地址以将你的智能体暴露到互联网。

示例使用

这是将位于 ~/agents/multi_tool_agent/ 的智能体部署到名为 test 的 GKE 集群的实际示例。

adk deploy gke \
    --project myproject \
    --cluster_name test \
    --region us-central1 \
    --with_ui \
    --log_level info \
    ~/agents/multi_tool_agent/

验证你的部署

如果你使用了 adk deploy gke，使用 kubectl 验证部署：

1. 检查 Pod：确保你的智能体的 pod 处于 Running 状态。

kubectl get pods

你应该在默认命名空间中看到类似 adk-default-service-name-xxxx-xxxx ... 1/1 Running 的输出。

1. 查找外部 IP：获取你智能体服务的公共 IP 地址。

kubectl get service
NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)        AGE
adk-default-service-name   LoadBalancer   34.118.228.70   34.63.153.253   80:32581/TCP   5d20h

我们可以导航到外部 IP 并通过 UI 与智能体交互

测试你的智能体

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

UI 测试API 测试 (curl)

UI 测试

如果你部署了启用 UI 的智能体：

你可以通过在 web 浏览器中导航到 kubernetes 服务 URL 来测试你的智能体。

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

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

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

如果你遇到任何意外行为，请使用以下命令检查你的智能体的 pod 日志：

kubectl logs -l app=adk-agent

API 测试 (curl)

你可以使用 curl 等工具与智能体的 API 端点交互。这对于编程交互或如果你没有部署 UI 的情况很有用。

设置应用程序 URL

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

export APP_URL=$(kubectl get service adk-agent -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

列出可用应用程序

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

curl -X GET $APP_URL/list-apps

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

创建或更新会话

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

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

运行智能体

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

curl -X POST $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": "加拿大的首都是什么？"
        }]
    },
    "streaming": false
    }'

• 设置 "streaming": true 如果你想接收 Server-Sent Events (SSE)。
• 响应将包含智能体的执行事件，包括最终答案。

故障排查

以下是你在将智能体部署到 GKE 时可能遇到的一些常见问题：

403 Permission Denied for Gemini 2.0 Flash

这通常意味着 Kubernetes 服务账号没有访问 Vertex AI API 的必要权限。请确保你已按照为 Vertex AI 配置 Kubernetes 服务账号部分创建服务账号并绑定到 Vertex AI User 角色。如果你使用 AI Studio，请确保你在部署 manifest 中设置了有效的 GOOGLE_API_KEY 环境变量。

404 或 Not Found 响应

这通常意味着你的请求中有错误。检查应用程序日志以诊断问题。

export POD_NAME=$(kubectl get pod -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs $POD_NAME

尝试写入只读数据库

你可能会发现 UI 中没有创建 session id，且智能体不响应任何消息。这通常是由于 SQLite 数据库为只读导致的。如果你在本地运行智能体后再创建容器镜像，镜像会将 SQLite 数据库文件复制到容器中，导致数据库为只读。

sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) attempt to write a readonly database
[SQL: UPDATE app_states SET state=?, update_time=CURRENT_TIMESTAMP WHERE app_states.app_name = ?]

要解决此问题，你可以：

在构建容器镜像前从本地删除 SQLite 数据库文件。这样容器启动时会创建新的 SQLite 数据库。

rm -f sessions.db

或者（推荐）你可以在项目目录中添加 .dockerignore 文件，将 SQLite 数据库排除在容器镜像之外。

.dockerignore

sessions.db

重新构建容器镜像并再次部署应用。

流式传输日志权限不足 ERROR: (gcloud.builds.submit)

当你没有足够的权限流式传输构建日志，或者你的 VPC-SC 安全策略限制了对默认日志桶的访问时，可能会出现此错误。

要检查构建进度，请按照错误消息中提供的链接或导航到 Google Cloud 控制台中的 Cloud Build 页面。

你还可以使用构建容器镜像部分下的命令验证镜像是否已构建并推送到 Artifact Registry。

Gemini-2.0-Flash 在 Live API 中不支持

当你使用 ADK Dev UI 进行已部署的智能体时，基于文本的聊天工作正常，但语音（例如，点击麦克风按钮）会失败。你可能会在 pod 日志中看到 websockets.exceptions.ConnectionClosedError，表明你的模型"在 live api 中不支持"。

此错误发生是因为智能体配置的模型（如示例中的 gemini-2.0-flash）不支持 Gemini Live API。Live API 是实时、双向音频和视频流所必需的。

清理

要删除 GKE 集群及所有相关资源，运行：

gcloud container clusters delete adk-cluster \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$GOOGLE_CLOUD_PROJECT

要删除 Artifact Registry 仓库，运行：

gcloud artifacts repositories delete adk-repo \
    --location=$GOOGLE_CLOUD_LOCATION \
    --project=$GOOGLE_CLOUD_PROJECT

如果你不再需要该项目，也可以删除整个项目。这将删除与该项目相关的所有资源，包括 GKE 集群、Artifact Registry 仓库以及你创建的其他资源。

gcloud projects delete $GOOGLE_CLOUD_PROJECT