部署到 Google Kubernetes Engine (GKE)¶
GKE 是 Google Cloud 托管的 Kubernetes 服务。它允许你使用 Kubernetes 部署和管理容器化应用程序。
要部署你的智能体，你需要在 GKE 上运行一个 Kubernetes 集群。你可以使用 Google Cloud 控制台或 gcloud 命令行工具创建集群。
在此示例中，我们将把一个简单的智能体部署到 GKE。该智能体将是一个使用 Gemini 2.0 Flash 作为 LLM 的 FastAPI 应用程序。我们可以使用环境变量 GOOGLE_GENAI_USE_VERTEXAI 来选择 Agent Platform 或 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 # 如果使用 Agent Platform，请设置为 true
export GOOGLE_CLOUD_PROJECT_NUMBER=$(gcloud projects describe --format json $GOOGLE_CLOUD_PROJECT | jq -r ".projectNumber")
如果你没有安装 jq，可以使用以下命令获取项目编号：
然后从输出中复制项目编号。
启用 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）。
-
这是
capital_agent目录内的 Capital Agent 示例capital_agent/agent.pyfrom 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-flash-latest", name="capital_agent", # 你的智能体名称 description="回答用户关于给定国家首都城市的问题。", instruction="""你是一个提供国家首都城市的智能体...（之前的指令文本）""", tools=[get_capital_city] # 直接提供函数 ) # ADK 将发现 root_agent 实例 root_agent = capital_agent将你的目录标记为 python 包
-
此文件使用 ADK 中的
get_fast_api_app()设置 FastAPI 应用程序：main.pyimport 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__)) # 示例会话服务 URI（例如 SQLite） # 注意：请使用 'sqlite+aiosqlite' 而非 'sqlite'，因为 DatabaseSessionService 需要异步驱动程序 SESSION_SERVICE_URI = "sqlite+aiosqlite:///./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。 -
列出必要的 Python 包：
-
定义容器镜像：
DockerfileFROM 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
为 Agent Platform 配置 Kubernetes 服务账号¶
如果你的智能体使用 Agent Platform，你需要创建一个具有必要权限的 Kubernetes 服务账号。此示例创建一个名为 adk-agent-sa 的服务账号，并将其绑定到 Agent Platform User 角色。
如果你使用 AI Studio 并通过 API key 访问模型，可以跳过此步骤。
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 上部署你的应用程序。
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 集群。
几分钟后，你可以使用以下命令检查部署状态：
此命令列出与你的部署相关的 pod。你应该会看到一个状态为 Running 的 pod。
一旦 pod 运行起来，你可以使用以下命令检查服务状态：
如果输出显示一个 External IP，这意味着你的服务可以从互联网访问。外部 IP 分配可能需要几分钟时间。
你可以使用以下命令获取服务的外部 IP 地址：
选项 2：使用 adk deploy gke 自动部署¶
ADK 提供 CLI 命令来简化 GKE 部署。这避免了手动构建镜像、编写 Kubernetes manifest 或推送到 Artifact Registry 的需要。
前置条件¶
在开始之前，确保你已设置以下内容：
-
运行中的 GKE 集群： 你需要在 Google Cloud 上有一个活跃的 Kubernetes 集群。
-
必需的 CLI：
gcloudCLI： Google Cloud CLI 必须已安装、已认证并配置为使用你的目标项目。运行gcloud auth login和gcloud config set project [YOUR_PROJECT_ID]。- kubectl： 必须安装 Kubernetes CLI 才能将应用程序部署到你的集群。
-
启用的 Google Cloud API： 确保在你的 Google Cloud 项目中启用了以下 API：
- Kubernetes Engine API (
container.googleapis.com) - Cloud Build API (
cloudbuild.googleapis.com) - Container Registry API (
containerregistry.googleapis.com)
- Kubernetes Engine API (
-
必需的 IAM 权限： 运行命令的用户或计算引擎默认服务账号至少需要以下角色：
-
Kubernetes Engine Developer (
roles/container.developer)：与 GKE 集群交互。 -
Storage Object Viewer (
roles/storage.objectViewer)：允许 Cloud Build 从 gcloud builds submit 上传的 Cloud Storage 存储桶下载源代码。 -
Artifact Registry Create on Push Writer (
roles/artifactregistry.createOnPushWriter)：允许 Cloud Build 将构建的容器镜像推送到 Artifact Registry。此角色还允许在首次推送时在 Artifact Registry 内按需创建特殊的 gcr.io 仓库。 -
Logs Writer (
roles/logging.logWriter)：允许 Cloud Build 将构建日志写入 Cloud Logging。
deploy gke 命令¶
该命令接受你的智能体路径和指定目标 GKE 集群的参数。
语法¶
参数和选项¶
| 参数 | 描述 | 必需 |
|---|---|---|
| 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 验证部署：
- 检查 Pod：确保你的智能体的 pod 处于 Running 状态。
你应该在默认命名空间中看到类似 adk-default-service-name-xxxx-xxxx ... 1/1 Running 的输出。
- 查找外部 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 测试¶
如果你部署了启用 UI 的智能体：
你可以通过在 web 浏览器中导航到 kubernetes 服务 URL 来测试你的智能体。
ADK 开发 UI 允许你与你的智能体交互，管理会话，并直接在浏览器中查看执行详情。
要验证你的智能体是否按预期工作，你可以：
- 从下拉菜单中选择你的智能体。
- 输入一条消息并验证你是否收到了来自智能体的预期响应。
如果你遇到任何意外行为，请使用以下命令检查你的智能体的 pod 日志：
API 测试 (curl)¶
你可以使用 curl 等工具与智能体的 API 端点交互。这对于编程交互或如果你没有部署 UI 的情况很有用。
设置应用程序 URL¶
用你部署的 Cloud Run 服务的实际 URL 替换示例 URL。
列出可用应用程序¶
验证部署的应用程序名称。
（如果需要，根据此输出调整以下命令中的 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¶
This usually means that the Kubernetes service account does not have the necessary permission to access the Agent Platform API. Ensure that you have created the service account and bound it to the Agent Platform User role as described in the Configure Kubernetes Service Account for Agent Platform section. If you are using AI Studio, ensure that you have set the GOOGLE_API_KEY environment variable in the deployment manifest and it is valid.
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 数据库。
或者（推荐）你可以在项目目录中添加 .dockerignore 文件，将 SQLite 数据库排除在容器镜像之外。
重新构建容器镜像并再次部署应用。
流式传输日志权限不足 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-flash-latest）不支持 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 仓库以及你创建的其他资源。