使用 Agent2UI 代理构建 Google Chat 应用

本页面解释了如何构建一个可在 Google Chat 中运行并与使用 Agent2UI (A2UI) 协议的 AI 代理交互的 Google Workspace 插件。 您可以使用 Agent Development Kit (ADK) 开发代理，并将其托管在 Vertex AI Agent Engine 中。

人工智能代理能够自主感知环境、进行推理，并执行复杂的多步骤操作以实现既定目标。在本教程中，您将部署一个基本的 AI 代理，该代理返回从工具中检索到的静态配置文件信息。

A2UI 使 AI 代理能够生成自适应、丰富、交互式的原生用户界面。这样你就可以专注于人工智能代理的逻辑，而不是用户界面。

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

如图所示，用户与使用 A2UI 代理实现的聊天应用程序交互时，信息流如下：

1. 用户通过聊天应用发送消息，可以是直接消息，也可以是聊天空间。
2. 聊天应用程序逻辑（无论是用 Apps Script 实现，还是作为具有 HTTP 端点的 Web 服务器实现）接收并处理消息。
3. Vertex AI Agent Engine 托管的 A2UI 代理接收并处理交互。
4. 聊天应用或 AI 代理还可以选择与 Google Workspace 服务（如日历或表格）或其他 Google 服务（如 Google 地图或 YouTube）集成。
5. Chat 应用会异步生成并发送自适应回复，使用 Google Chat API 来传达 AI 代理的进度。
6. 响应结果将发送给用户。

目标

• 设置环境。
• 部署 A2UI 代理。
• 部署聊天应用。
• 配置聊天应用程序。
• 测试聊天应用。

前提条件

• 具有访问 Google Chat 权限的企业或公司 Google Workspace 账号。
• 启用了结算功能的 Google Cloud 项目。要检查现有项目是否已启用计费，请参阅验证项目的计费状态。要创建项目并设置结算，请参阅创建 Google Cloud 项目。
• Python 3.11+：要进行安装，请按照官方 Python 网站 上的说明进行操作。
• Python Poetry：要进行安装，请按照官方 Poetry 网站 上的说明进行操作。
• Google Cloud CLI：要进行安装，请按照官方 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 控制台中，转到“菜单”。menu > Google Auth platform > 品牌推广。

   前往品牌推广

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

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

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

Google Cloud 控制台

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

   转到“服务账号”

2. 点击创建服务账号。
3. 填写服务账号详细信息，然后点击创建并继续。
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 控制台中，依次前往“菜单”图标 menu > IAM 和管理 > 服务账号。

   转到“服务账号”

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

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

5. 点击关闭。

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

部署 A2UI 代理

1. 如果您尚未执行此操作，请使用您的 Google Cloud 账号进行身份验证，并配置 Google Cloud CLI 以使用您的 Google Cloud 项目。

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   将 PROJECT_ID 替换为您的 Cloud 项目 ID。

2. 使用以下按钮下载 googleworkspace/add-ons-samples GitHub 代码库：

   下载代码库

3. 在您偏好的本地开发环境中，解压下载的归档文件并打开 add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui 目录。

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

4. 创建一个专用于 ADK 代理的新 Cloud Storage 存储分区。

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   替换以下内容：

   1. 将 CLOUD_STORAGE_BUCKET_NAME 替换为您要使用的唯一存储分区名称。
   2. 将 PROJECT_ID 替换为您的 Cloud 项目 ID。
   3. 将 PROJECT_LOCATION 替换为您的 Cloud 项目的位置。

5. 设置以下环境变量：

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   替换以下内容：

   1. 将 CLOUD_STORAGE_BUCKET_NAME 替换为您创建的存储分区的名称。
   2. 将 PROJECT_ID 替换为您的 Cloud 项目 ID。
   3. 将 PROJECT_LOCATION 替换为您的 Cloud 项目的位置。

6. 从虚拟环境中安装和部署 ADK 代理。

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. 检索代理 ID。稍后在配置 Chat 应用时，您需要用到它。

   python3 deployment/deploy.py --list

创建和配置 Chat 应用项目

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

   打开项目

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

3. 在您的 Apps Script 项目中，单击 项目设置 > 编辑脚本属性 > 添加脚本属性添加以下脚本属性：

   1. REASONING_ENGINE_RESOURCE_NAME，其中 Vertex AI 代理资源名称已在前面的步骤中复制。
   2. SERVICE_ACCOUNT_KEY 使用从先前步骤中下载的服务账号的 JSON 密钥，例如 { ... }。

4. 点击保存脚本属性。

5. 在 Google Cloud 控制台中，转到“菜单”。menu > 身份与访问管理 > 设置。

   前往“IAM 和管理”设置

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

7. 在您的 Apps Script 项目中，单击 项目设置。

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

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

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

创建测试部署

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

要获取主部署 ID，请执行以下操作：

1. 在聊天应用 Apps Script 项目中，点击部署 > 测试部署。
2. 在 标题部署 ID 下，单击 复制。
3. 点击完成。

配置 Chat 应用

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

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

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

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

4. 点击保存。

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

测试 Chat 应用

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

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

   前往 Google Chat

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

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

5. 在与应用来往的新私信中，输入 Hello! 并按 enter。

   聊天应用会回复一条包含问候语的消息，以及一张包含个人资料名称、图片和 LinkedIn 按钮的卡片。

6. 更新了 A2UI 代理的实现，以开始返回个人资料标题。

   在本地开发环境中，打开文件 a2ui/agent.py，然后取消注释工具中用于向返回的数据添加标题的行。

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   在 GitHub 上查看
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. 使用新版本的实现更新之前部署的 ADK。

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   将 RESOURCE_ID 替换为之前步骤中复制的顶点 AI 代理资源名称。

8. 在应用程序的直接消息中，输入 Hello again! 并按 enter。

   聊天应用会回复一条消息，其中包含一些文本和一个包含个人资料标题的卡片。

要添加受信任的测试人员并了解有关测试交互式功能的更多信息，请参阅 测试 Google Chat 应用的交互式功能。

问题排查

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

虽然错误信息可能不会显示在聊天界面中，但启用聊天应用程序的错误日志记录后，即可查看描述性错误信息和日志数据，以帮助您修复错误。如需帮助查看、调试和修复错误，请参阅排查和修复 Google Chat 错误。

清理

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

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

   前往资源管理器

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

相关主题

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