Skip to content

连接 Google Cloud 和 Agent Platform

本指南介绍如何将你的 ADK 智能体连接到 Google Cloud Platform (GCP) 服务、Google Cloud Agent Platform 上运行的模型以及 Agent Platform 服务并进行身份验证。

设置 Google Cloud Agent Platform

在尝试将智能体连接到 Google Cloud 或 Agent Platform 服务之前，请确保你已完成以下前置条件：

  • 一个已启用 Agent Platform API（aiplatform.googleapis.com）的 Google Cloud 项目。
  • 安装 gcloud CLI 工具。

Google Cloud 身份验证选项

将 ADK 智能体连接到 Google Cloud 时，你有几种身份验证选项，如下表所述。

方法 最适用于 身份验证机制 环境
用户凭据 本地开发和测试 通过 gcloud 的应用程序默认凭据 本地工作站
服务账号 生产部署和 CI/CD Google IAM 服务账号密钥 / Workload Identity Google Cloud（Agent Runtime、Cloud Run、GKE）或外部服务器
Express Mode 快速原型设计和测试 API 密钥 本地或云端环境
智能体身份 生产部署和 CI/CD Google IAM 服务账号密钥 / Workload Identity Google Cloud（Agent Runtime、Cloud Run、GKE）

警告：保护你的凭据

用户凭据、服务账号凭据和 API 密钥高度敏感。切勿将凭据文件或密钥直接提交到代码库。尽可能使用安全的密钥管理器，如 Google Cloud Agent Identity、Google Cloud Secret Manager 或其他类似产品。

本地开发用用户凭据

使用用户凭据身份验证方法将本地开发环境连接到 Google Cloud。

  1. 在运行 ADK 智能体应用程序之前，使用应用程序默认凭据 (ADC) 对你的本地工作站进行身份验证： 
    gcloud auth application-default login

  2. 设置环境变量以启用 Agent Platform 并指定你的项目详情：

    # 添加到 ADK 代码项目中，但不要添加到版本控制
GOOGLE_GENAI_USE_ENTERPRISE=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=cloud-location   # 示例：us-central1

    export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="cloud-location"   # 示例：us-central1

GOOGLE_GENAI_USE_ENTERPRISE 以前是 GOOGLE_GENAI_USE_VERTEXAI

这两个变量名称是等效的，功能相同。 如果你设置了 GOOGLE_GENAI_USE_ENTERPRISE 但你的智能体无法连接到 Agent Platform，说明你使用的是较旧的 ADK 版本。请改用 GOOGLE_GENAI_USE_VERTEXAI，或更新到较新版本的 ADK。

生产环境用服务账号

部署到安全托管环境时，使用服务账号进行连接身份验证：

  1. 创建一个服务账号并为其授予 Agent Platform User 角色。
  2. 根据你的部署策略将凭据提供给你的智能体应用程序：
    • 部署在 Google Cloud 上（Agent Runtime、Cloud Run、GKE）： 环境会自动提供凭据。无需配置密钥文件。
    • 在外部运行： 生成一个服务账号密钥文件（.json）并配置 GOOGLE_APPLICATION_CREDENTIALS 环境变量： 
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Workload Identity 选项

除了密钥文件，你也可以使用 Workload Identity 对服务账号进行身份验证。

Agent Platform Express Mode 测试模式

Express Mode 提供了一种简化的、基于 API 密钥的设置，无需完整的 gcloud 身份验证即可进行原型设计。

  1. 注册 express mode 以获取 API 密钥。

  2. 设置以下环境变量：

    # 添加到 ADK 代码项目中，但不要添加到版本控制
GOOGLE_GENAI_USE_ENTERPRISE=TRUE
GOOGLE_GENAI_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE

    export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_GENAI_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"

Google Cloud 托管模型

Google Cloud Agent Platform 托管了大量你可以连接到 ADK 智能体的 AI 模型，包括 Gemini 模型、第三方 AI 模型、开源权重模型以及为你的组织自定义微调的模型。一旦你将 ADK 智能体连接到 Google Cloud 和 Agent Platform，你就可以访问适合你应用需求的 AI 模型。查看以下资源以探索和查找适合你项目的模型：

其他 Google Cloud 服务连接

许多 Google Cloud 服务为 ADK 集成提供了身份验证帮助程序，用于访问 GCP API 或资源。有关更多信息，请参阅以下页面：