部署到 Google Kubernetes Engine (GKE)¶

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

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    # 容器构建说明

在 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())
       }
   }
   

   要使用 Vertex AI 而不是 AI Studio，请设置 genai.ClientConfig 以使用 Vertex AI 后端：

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

使用 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

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}')

列出可用应用¶

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

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

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。
• 响应将包含智能体的执行事件，包括最终答案。