部署到 GKE

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

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

智能体示例

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

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

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

环境变量

按照设置和安装指南中的描述设置你的环境变量。你还需要安装 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

部署命令

gcloud CLI

你可以使用 gcloud 和 kubectl 命令行工具以及 Kubernetes 清单文件将智能体部署到 GKE。

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

创建 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

Artifact Registry

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

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

项目结构

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

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
   
   # 获取 main.py 所在的目录
   AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
   # 示例会话数据库 URL（例如，SQLite）
   SESSION_DB_URL = "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(
       agent_dir=AGENT_DIR,
       session_db_url=SESSION_DB_URL,
       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。

2. 列出必要的 Python 包：

   requirements.txt

   google_adk
   # 添加智能体需要的任何其他依赖项
   

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 命令行工具构建容器镜像。此示例构建镜像并将其标记为 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 \
    .

为 Vertex AI 配置 Kubernetes 服务账号

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

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
        image: $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:v0.0.4
        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
          # 添加智能体可能需要的任何其他必要环境变量
---
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}'

测试你的智能体

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

=== "UI 测试" {: #ui-testing}

### UI 测试

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

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

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

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

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

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

```bash
kubectl logs -l app=adk-agent
```

=== "API 测试 (curl)" {: #api-testing-curl}

### API 测试 (curl)

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

#### 设置应用程序 URL

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

```bash
export APP_URL="KUBERNETES_SERVICE_URL"
```

#### 列出可用应用程序

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

```bash
curl -X GET $APP_URL/list-apps
```

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

#### 创建或更新会话

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

```bash
curl -X POST \
    $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 和提示。

```bash
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
    }'
```

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