使用 ADK AI 代理构建 Google Chat 应用

本页面介绍了如何构建可在 Google Chat 中运行并与托管在 Vertex AI Agent Engine 中的智能体开发套件 (ADK) AI 代理进行交互的 Google Workspace 加载项。

注意：在 Google Chat 中，插件会作为 Google Chat 应用显示给用户。您还可以使用 Google Chat API 互动事件来构建 Chat 应用。如需了解详情，请参阅扩展 Google Chat 概览。

AI 智能体能够自主感知环境、进行推理并执行复杂的多步骤操作，以实现既定目标。在本教程中，您将部署 ADK LLM Auditor 多代理示例，该示例使用 Gemini 和 Google 搜索基础来评判和修订事实。

下图展示了架构和消息传递模式：

在上图中，用户与使用 ADK AI 代理实现的聊天应用互动时，信息流如下所示：

1. 用户通过私信或 Chat 聊天室向 Chat 应用发送消息。
2. 在 Apps 脚本中或作为具有 HTTP 端点的 Web 服务器实现的 Chat 应用逻辑会接收并处理消息。
3. 使用 ADK 实现并由 Vertex AI Agent Engine 托管的 AI 代理会接收并处理互动。
4. 聊天应用或 AI 代理可以与 Google Workspace 服务（例如 Google 日历或 Google 表格）或其他 Google 服务（例如 Google 地图或 YouTube）集成。
5. Chat 应用使用 Google Chat API 异步发送响应，以传达 AI 代理的进度。
6. 系统会将回答发送给用户。

目标

• 设置环境。
• 部署 ADK AI 代理。
• 部署 Chat 应用。
• 配置 Chat 应用。
• 测试 Chat 应用。

前提条件

• 拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
• 启用了结算功能的 Google Cloud 项目。如需检查现有项目是否已启用结算功能，请参阅验证项目的结算状态。如需创建项目并设置结算，请参阅创建 Google Cloud 项目。

设置环境

启用 Google Cloud API

在使用 Google API 之前，您需要在 Google Cloud 项目中启用它们。 您可以在单个 Google Cloud 项目中启用一个或多个 API。

• 在 Google Cloud 控制台中，启用 Google Chat、Vertex AI 和 Cloud Resource Manager API。

  启用 API

配置 OAuth 权限请求页面

所有使用 OAuth 2.0 的应用都需要配置权限请求页面。通过配置应用的 OAuth 权限请求页面，您可以定义向用户和应用审核者显示哪些内容，还可以注册应用以便以后发布。

1. 在 Google Cloud 控制台中，依次前往菜单 > Google Auth platform > 品牌推广。

   前往“品牌推广”

2. 如果您已配置 Google Auth platform，则可以在品牌推广、受众群体和数据访问中配置以下 OAuth 权限请求页面设置。如果您看到一条消息，指出Google Auth platform 尚未配置，请点击开始：
1. 在应用信息下的应用名称中，输入应用的名称。
2. 在用户支持电子邮件中，选择一个支持电子邮件地址，以便用户在同意方面有疑问时与您联系。
3. 点击下一步。
4. 在受众群体下，选择内部。
5. 点击下一步。
6. 在联系信息下，输入一个电子邮件地址，以便您接收有关项目变更的通知。
7. 点击下一步。
8. 在完成部分，查看 Google API 服务用户数据政策，如果您同意该政策，请选择我同意 Google API 服务：用户数据政策。
9. 点击继续。
10. 点击创建。
3. 目前，您可以跳过添加范围的步骤。 未来，如果您创建的应用供 Google Workspace 组织以外的用户使用，则必须将用户类型更改为外部。然后，添加应用所需的授权范围。如需了解详情，请参阅完整的配置 OAuth 同意指南。

在 Google Cloud 控制台中创建服务账号

按照以下步骤创建具有 Vertex AI User 角色的新服务账号：

Google Cloud 控制台

1. 在 Google Cloud 控制台中，依次前往菜单 > IAM 和管理 > 服务账号。

   转到“服务账号”

2. 点击创建服务账号。
3. 填写服务账号详细信息，然后点击创建并继续。
   注意：默认情况下，Google 会创建一个唯一的服务账号 ID。如果您想更改 ID，请修改“服务账号 ID”字段中的 ID。
4. 可选：向您的服务账号分配角色，以授予对 Google Cloud 项目资源的访问权限。如需了解详情，请参阅授予、更改和撤消对资源的访问权限。
5. 点击继续。
6. 可选：输入可管理此服务账号并使用此服务账号执行操作的用户或群组。如需了解详情，请参阅管理服务账号模拟。
7. 点击完成。记下服务账号的电子邮件地址。

gcloud CLI

1. 创建服务账号：

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. 可选：向您的服务账号分配角色，以授予对 Google Cloud 项目资源的访问权限。如需了解详情，请参阅授予、更改和撤消对资源的访问权限。

该服务账号会显示在服务账号页面上。

创建一个私钥

警告： 为简单起见，此示例使用了导出的服务账号密钥。不建议在生产环境中导出私钥，因为私钥不应存储在不安全的位置（例如源代码控制系统）中。

如需详细了解安全的服务账号实现和最佳实践，请参阅选择何时使用服务账号。

如需为服务账号创建并下载私钥，请按以下步骤操作：

1. 在 Google Cloud 控制台中，依次前往菜单 > IAM 和管理 > 服务账号。

   转到“服务账号”

2. 选择您的服务账号。
3. 依次点击密钥 > 添加密钥 > 创建新密钥。
4. 选择 JSON，然后点击创建。

   系统会生成新的公钥/私钥对，并以新文件的形式下载到您的计算机。将下载的 JSON 文件以 credentials.json 的名称保存到工作目录中。此文件是相应密钥的唯一副本。如需了解如何安全地存储密钥，请参阅管理服务账号密钥。

5. 点击关闭。

如需详细了解服务账号，请参阅 Google Cloud IAM 文档中的服务账号。

部署 ADK AI 代理

1. 在 Vertex AI Agent Garden 中打开 LLM Auditor 示例：

   打开示例

2. 点击部署。

3. 如果系统询问，请选择您的 Google Cloud 项目。

4. 点击在 Cloud Shell 中部署。

5. 如果系统要求您授权，请点击授权，然后完成 Cloud Shell 的 OAuth 流程。

6. 当 Cloud Shell 完全加载后，按 Enter 键运行预加载的命令行并开始部署。

7. 如果系统要求您输入区域，请按 Enter 键以使用默认区域。

8. 完成后，前往 Vertex AI Agent Engine：

   打开 Vertex AI Agent Engine

9. 点击 从表格中复制新部署的代理的资源名称。

创建和配置 Chat 应用项目

1. 点击以下按钮，打开 ADK AI 代理快速入门 Apps 脚本项目。

   打开项目

2. 依次点击 概览 > 制作副本。

3. 在您的 Apps 脚本项目中，依次点击 项目设置 > 修改脚本属性 > 添加脚本属性，以添加以下脚本属性：

   1. 将 REASONING_ENGINE_RESOURCE_NAME 替换为在之前的步骤中复制的 Vertex AI 代理资源名称。
   2. SERVICE_ACCOUNT_KEY 替换为在之前的步骤中下载的服务账号的 JSON 密钥，例如 { ... }。

4. 点击保存脚本属性

5. 在 Google Cloud 控制台中，依次前往“菜单”图标 > IAM 和管理 > 设置。

   前往“IAM 和管理”设置

6. 在项目编号字段中，复制相应值。

7. 在您的 Apps 脚本项目中，点击 项目设置。

8. 在 Google Cloud Platform (GCP) 项目下，点击更改项目。

9. 在 GCP 项目编号中，粘贴在之前的步骤中复制的 Google Cloud 项目编号。

10. 点击设置项目。现在，Cloud 项目和 Apps 脚本项目已关联。

创建测试部署

您需要此 Apps 脚本项目的部署 ID，以便在下一步中使用。

如需获取头部署 ID，请执行以下操作：

1. 在 Chat 应用的 Apps 脚本项目中，依次点击部署 > 测试部署。
2. 在主部署 ID 下，点击 复制。
3. 点击完成。

配置 Chat 应用

使用 Apps 脚本部署，按以下步骤部署 Google Chat 应用以进行测试：

1. 在控制台中，搜索 Google Chat API，然后点击 Google Chat API。
2. 点击管理。

3. 点击配置并设置 Chat 应用：

   1. 在应用名称字段中，输入 ADK Quickstart。
   2. 在头像网址字段中，输入 https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png。
   3. 在说明字段中，输入 ADK Quickstart。
   4. 在功能下，选择加入聊天室和群组对话。
   5. 在“连接设置”下，选择 Apps 脚本项目。
   6. 在 Deployment ID（部署 ID）字段中，粘贴您之前复制的 Head 部署 ID。
   7. 在“查看权限”下方，选择您网域中的特定人员和群组，然后输入您的电子邮件地址。

4. 点击保存。

Chat 应用已准备好回复消息。

测试 Chat 应用

如需测试 Chat 应用，请打开与该 Chat 应用的私信对话，然后发送消息：

1. 使用您在添加自己为可信测试人员时提供的 Google Workspace 账号打开 Google Chat。

   前往 Google Chat

2. 点击 发起新聊天。
3. 在添加 1 位或多位用户字段中，输入 Chat 应用的名称。

4. 从结果中选择您的 Chat 应用。系统会打开私信对话。

   注意：如果您在结果列表中没有看到自己的 Chat 应用，请确保您已在 Google Cloud 控制台的 Chat API 配置页面的公开范围设置中添加了您的 Google Workspace 账号。

5. 在与应用来往的新私信中，输入 The Eiffel Tower was completed in 1900 并按 enter。

   Chat 应用会回复 Critic 和 Reviser 子代理的回答。

如需添加可信测试员并详细了解如何测试互动功能，请参阅测试 Google Chat 应用的互动功能。

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示一条消息，提示“出了点问题”。 或“无法处理您的请求”。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然聊天界面中可能不会显示错误消息，但当您为聊天应用启用错误日志记录功能后，系统会提供描述性错误消息和日志数据，帮助您修复错误。如需有关查看、调试和修复错误的帮助，请参阅排查和修复 Google Chat 错误。

清理

为避免系统因本教程中使用的资源向您的 Google Cloud 账号收取费用，我们建议您删除 Cloud 项目。

警告：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您在本教程使用现有项目，则删除该项目后，还将删除您已在该项目中完成的其他所有工作。
• 自定义项目 ID 会丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。如需保留使用该项目 ID 的网址（例如 appspot.com 上的网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算浏览多个教程和快速入门，重复使用项目可以帮助您避免超出项目配额上限。

1. 在 Google Cloud 控制台中，前往管理资源页面。依次点击 菜单 > IAM 和管理 > 管理资源。

   前往资源管理器

2. 在项目列表中，选择要删除的项目，然后点击删除 。
3. 在对话框中输入项目 ID，然后点击关停以删除项目。

相关主题

• 使用 ADK AI 代理和 Gemini 模型对陈述进行事实核查
• 借助可在整个 Google Workspace 中使用的 AI 代理规划行程
• 在 Chat 应用中集成基本 AI 概念
• 使用 Gemini AI Chat 应用，根据 Chat 对话内容回答问题
• 使用 Google Chat、Vertex AI、Apps 脚本和用户身份验证来应对突发事件
• 使用 Google Chat、Vertex AI 和 Firestore 管理项目