部署到 Google Kubernetes Engine (GKE)

Supported in ADK Python Go

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

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

以下示例展示如何将一个简单的智能体部署到 GKE。Python 智能体是一个使用 Gemini Flash 作为 LLM 的 FastAPI 应用程序。Go 智能体使用 ADK 启动器和一个 静态链接的二进制文件，运行在极简容器中。你可以通过环境变量 GOOGLE_GENAI_USE_ENTERPRISE 使用 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_ENTERPRISE=true # 使用 Agent Platform 时设置为 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 清单或使用 adk deploy gke 命令自动部署的方式将智能体部署到 GKE。 选择最适合你工作流程的方式。

选项 1：使用 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 示例作为参考。

PythonGo

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

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

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

your-project-directory/
├── main.go       # 智能体代码和启动器入口点
├── go.mod        # Go 模块定义
├── go.sum        # Go 模块校验和
└── Dockerfile    # 容器构建说明

代码文件

PythonGo

在 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-flash-latest",
       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__))
   # 示例会话服务 URI（例如 SQLite）
   # 注意：使用 'sqlite+aiosqlite' 而不是 'sqlite'，因为 DatabaseSessionService 需要异步驱动
   SESSION_SERVICE_URI = "sqlite+aiosqlite:///./sessions.db"
   # 示例 CORS 允许的来源
   ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
   # 如果你打算提供 Web 界面则设置为 True，否则设置为 False
   SERVE_WEB_INTERFACE = True
   
   # 调用函数获取 FastAPI 应用实例
   # 确保 agent 目录名称（'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,
   )
   
   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"]
   

在 your-project-directory/ 根目录下创建以下文件。

1. 定义智能体并嵌入 ADK 启动器。启动器处理 web、api 和 webui 子命令，用于启动 REST API 服务器和 Web 界面：

   main.go

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "os"
       "strings"
   
       "google.golang.org/adk/v2/agent"
       "google.golang.org/adk/v2/agent/llmagent"
       "google.golang.org/adk/v2/cmd/launcher"
       "google.golang.org/adk/v2/cmd/launcher/full"
       "google.golang.org/adk/v2/model/gemini"
       "google.golang.org/adk/v2/tool"
       "google.golang.org/adk/v2/tool/functiontool"
       "google.golang.org/genai"
   )
   
   type getCapitalCityArgs struct {
       Country string `json:"country" jsonschema:"The country to look up."`
   }
   
   func getCapitalCity(_ tool.Context, args getCapitalCityArgs) (string, error) {
       capitals := map[string]string{
           "france":  "Paris",
           "japan":   "Tokyo",
           "canada":  "Ottawa",
       }
       capital, ok := capitals[strings.ToLower(args.Country)]
       if !ok {
           return "", fmt.Errorf("capital not found for %s", args.Country)
       }
       return capital, nil
   }
   
   func main() {
       ctx := context.Background()
   
       model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
           APIKey: os.Getenv("GOOGLE_API_KEY"),
       })
       if err != nil {
           log.Fatalf("Failed to create model: %v", err)
       }
   
       capitalTool, err := functiontool.New(
           functiontool.Config{
               Name:        "get_capital_city",
               Description: "Retrieves the capital city for a given country.",
           },
           getCapitalCity,
       )
       if err != nil {
           log.Fatalf("Failed to create tool: %v", err)
       }
   
       capitalAgent, err := llmagent.New(llmagent.Config{
           Name:        "capital_agent",
           Model:       model,
           Description: "Answers questions about capital cities.",
           Instruction: "You are an agent that provides the capital city of a country.",
           Tools:       []tool.Tool{capitalTool},
       })
       if err != nil {
           log.Fatalf("Failed to create agent: %v", err)
       }
   
       config := &launcher.Config{
           AgentLoader: agent.NewSingleLoader(capitalAgent),
       }
   
       l := full.NewLauncher()
       if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
           log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
       }
   }
   

   要使用 Agent Platform 而不是 AI Studio，请将 genai.ClientConfig 设置为使用 Agent Platform 后端：

   model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
       Backend:  genai.BackendVertexAI,
       Project:  os.Getenv("GOOGLE_CLOUD_PROJECT"),
       Location: os.Getenv("GOOGLE_CLOUD_LOCATION"),
   })
   

2. 定义容器镜像。Go 编译为自包含的静态二进制文件，因此容器使用极简的 distroless 基础镜像——无需运行时依赖或包管理器：

   Dockerfile

   # 阶段 1：构建 Go 二进制文件
   FROM golang:1.25 AS builder
   WORKDIR /app
   
   COPY go.mod go.sum ./
   RUN go mod download
   
   COPY . .
   # 编译静态链接的 Linux/amd64 二进制文件
   RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
       go build -ldflags="-s -w" -o capital_agent .
   
   # 阶段 2：将二进制文件复制到极简运行时镜像中
   FROM gcr.io/distroless/static-debian12
   COPY --from=builder /app/capital_agent /app/capital_agent
   EXPOSE 8080
   
   # 启动 API 服务器和 Web UI
   CMD ["/app/capital_agent", "web", "-port", "8080", "api", "webui"]
   

构建容器镜像

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

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

构建容器镜像并将其推送到 Artifact Registry：

PythonGo

使用 Cloud Build 从你的源目录直接构建并推送镜像：

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

多阶段 Dockerfile 在构建器阶段内处理编译，因此你可以 使用 Cloud Build 而无需本地 Go 工具链：

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

或者，你可以在本地编译二进制文件并构建一个不使用多阶段 Dockerfile 的更小镜像——如果你已经安装了 Go，这很有用：

# 交叉编译 linux/amd64
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o capital_agent .

# 构建并推送镜像
docker build -t $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest .
docker push $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest

验证镜像是否已构建并推送到 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 时可跳过

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

kubectl create serviceaccount adk-agent-sa

PROJECT_ID=${GOOGLE_CLOUD_PROJECT}
PROJECT_NUM=${GOOGLE_CLOUD_PROJECT_NUMBER}
IAM_URL="principal://[iam.googleapis.com/projects/$](https://iam.googleapis.com/projects/$){PROJECT_NUM}"
WIP="locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog"
SA="subject/ns/default/sa/adk-agent-sa"

gcloud projects add-iam-policy-binding projects/${PROJECT_ID} \
    --role=roles/aiplatform.user \
    --member="${IAM_URL}/${WIP}/${SA}" \
    --condition=None

创建 Kubernetes 清单文件

在你的项目目录中创建一个名为 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_ENTERPRISE
            value: "$GOOGLE_GENAI_USE_ENTERPRISE"
          # 如果使用 AI Studio，将 GOOGLE_GENAI_USE_ENTERPRISE 设置为 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 自动部署

仅限 Python

adk deploy gke 命令仅适用于 Python。Go 没有等效的 CLI 命令。Go 智能体必须使用选项 1 中描述的手动方式部署。

ADK 提供了一个 CLI 命令来简化 GKE 部署。这样就无需手动构建镜像、编写 Kubernetes 清单或推送到 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。

为 Agent Platform 配置 Workload Identity

如果你的智能体使用 Agent Platform，集群中运行的工作负载需要调用 Agent Platform API 的权限。与手动方式不同，adk deploy gke 生成的清单使用 default 命名空间中的 default Kubernetes 服务账号。通过 Workload Identity 将 Agent Platform User 角色授予该服务账号，以便智能体可以访问 Gemini 等模型。

使用 AI Studio 时可跳过

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

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/default \
    --condition=None

如果你使用的是 Google Cloud 项目并跳过此步骤，智能体的 Pod 会成功启动，但在验证部署时，对模型的请求会因 403 PERMISSION_DENIED 错误而失败。

deploy gke 命令

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

语法

adk deploy gke [OPTIONS] AGENT_PATH

参数和选项

参数	描述	必需
AGENT_PATH	智能体根目录的本地文件路径。	是
--project	你的 GKE 集群所在的 Google Cloud 项目 ID。	是
--cluster_name	你的 GKE 集群名称。	是
--region	你的集群所在的 Google Cloud 区域（例如 us-central1）。	是
--service_type	要创建的 Kubernetes 服务类型。接受 ClusterIP（默认）或 LoadBalancer。	否
--with_ui	同时部署智能体的后端 API 和配套的前端用户界面。	否
--log_level	设置部署过程的日志级别。选项：debug、info、warning、error、critical。	否

工作原理

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

• 容器化： 从你的智能体源代码构建 Docker 容器镜像。
• 镜像推送： 为容器镜像打标签并将其推送到你项目的 Artifact Registry。
• 清单生成： 动态生成必要的 Kubernetes 清单文件（一个 Deployment 和一个 Service）。

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

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

Service 会为你的智能体创建一个稳定的网络端点。它默认使用 ClusterIP 服务，仅在集群内部可访问。要通过公共 IP 地址将你的智能体暴露到互联网，必须指定 --service_type=LoadBalancer。

使用示例

以下是将位于 ~/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 状态。

kubectl get pods

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

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

kubectl get service

默认情况下，服务类型为 ClusterIP，EXTERNAL-IP 为 <none>。

NAME                       TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
adk-default-service-name   ClusterIP   10.12.1.2       <none>        80/TCP    2m

要测试你的智能体，可以使用端口转发：

kubectl port-forward svc/adk-default-service-name 8080:80

然后你可以在 http://localhost:8080 访问你的智能体。

如果你使用 --service_type=LoadBalancer 部署，分配外部 IP 可能需要几分钟时间。 一旦 EXTERNAL-IP 可用，你就可以导航到该地址与你的智能体交互。

测试你的智能体

将智能体部署到 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

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

Go：API 路径前缀

Go ADK 服务器默认在 /api 路径前缀下提供所有 REST 端点。 在测试 Go 部署时，请在以下示例中的每个路径前加上 /api。例如：

Python	Go
$APP_URL/list-apps	$APP_URL/api/list-apps
$APP_URL/apps/…	$APP_URL/api/apps/…
$APP_URL/run_sse	$APP_URL/api/run_sse

该前缀可以在启动时通过 api 子命令的 -path_prefix 修改， 例如 CMD ["/app/capital_agent", "web", "-port", "8080", "api", "-path_prefix", ""] 会完全移除前缀。

列出可用应用

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

curl -X GET $APP_URL/list-apps

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

创建或更新会话

初始化或更新特定用户和会话的状态。如果不同，请将 capital_agent 替换为你的实际应用名称。

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 和提示内容。

Go：JSON 字段名使用驼峰命名

Python ADK REST API 在 JSON 请求体中使用 snake_case 字段名 （例如 app_name、user_id、new_message）。Go ADK REST API 使用 camelCase（例如 appName、userId、newMessage）。请使用 与你的部署语言对应的正确格式。

PythonGo

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": "What is the capital of Canada?"
        }]
    },
    "streaming": false
    }'

curl -X POST $APP_URL/api/run_sse \
    -H "Content-Type: application/json" \
    -d '{
    "appName": "capital_agent",
    "userId": "user_123",
    "sessionId": "session_abc",
    "newMessage": {
        "role": "user",
        "parts": [{
        "text": "What is the capital of Canada?"
        }]
    },
    "streaming": false
    }'

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

故障排查

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

Gemini 模型的 403 权限被拒绝

这通常意味着 Kubernetes 服务账号没有访问 Agent Platform API 的必要权限。请确保你已创建服务账号并将其绑定到 Agent Platform User 角色，如为 Agent Platform 配置 Kubernetes 服务账号部分所述。 如果你使用 adk deploy gke 部署，请改为绑定 default 服务账号，如为 Agent Platform 配置 Workload Identity部分所述。如果你使用的是 AI Studio，请确保你已在部署清单中设置了 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

尝试写入只读数据库

仅限 Python

此错误适用于使用 SQLite 进行会话存储的 Python 部署。 Go 部署默认使用内存会话服务，不受此问题影响。

你可能会看到 UI 中没有创建会话 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 模型在 Live API 中不受支持

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

此错误是因为智能体配置了一个不支持 Gemini Live API 的模型（例如示例中的 gemini-flash-latest）。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