使用 Agent2UI 代理程式建構 Google Chat 應用程式

本頁說明如何建構可在 Google Chat 中運作的 Google Workspace 外掛程式，並透過 Agent2UI (A2UI) 通訊協定與 AI 代理互動。您可以使用 Agent Development Kit (ADK) 開發代理，並在 Vertex AI Agent Engine 中代管。

AI 代理會自主感知環境、推論，並執行複雜的多步驟動作，以達成特定目標。在本教學課程中，您將部署基本 AI 代理程式，傳回從工具擷取的靜態設定檔資訊。

A2UI 可讓 AI 代理程式生成自動調整的豐富互動式 UI，並以原生方式算繪。這樣你就可以專注於人工智慧代理的邏輯，而不是使用者介面。

  • A2UI 代理程式會向使用者發送包含文字和卡片的訊息，卡片中包含個人資料名稱、圖像和 LinkedIn 按鈕。
    圖 1. A2UI 代理程式會傳送文字和一張包含姓名、圖像和 LinkedIn 按鈕的卡片給使用者。
  • A2UI 代理程式也會更新，一併傳回設定檔標題。
    圖 2. A2UI 代理程式已更新，現在也會傳回個人資料標題。
  • A2UI 代理程式會向使用者傳送一則訊息，該訊息會在卡片中顯示設定檔名稱。
    圖 3. A2UI 代理程式會向使用者傳送一則訊息，該訊息會在卡片中顯示設定檔名稱。

下圖展示了架構和訊息傳遞模式：

基於 A2UI AI 代理程式的聊天應用程式架構。

如圖所示，使用者與透過 A2UI 代理程式實作的即時通訊應用程式互動時，資訊流程如下：

  1. 使用者透過即時訊息或 Chat 聊天室傳送訊息給 Chat 應用程式。
  2. 在 Apps Script 或以 HTTP 端點形式實作的網頁伺服器中，Chat 應用程式邏輯會接收及處理訊息。
  3. Vertex AI Agent Engine 代管的 A2UI 代理會接收及處理互動。
  4. 視需要，Chat 應用程式或 AI 代理程式可以與 Google Workspace 服務 (例如 Google 日曆或 Google 試算表) 或其他 Google 服務 (例如 Google 地圖或 YouTube) 整合。
  5. Chat 應用程式會使用 Google Chat API 傳達 AI 代理程式的進度，並以非同步方式生成及傳送適應性回應。
  6. 並將回覆傳送給使用者。

目標

  • 設定環境。
  • 部署 A2UI 代理程式。
  • 部署 Chat 應用程式。
  • 設定 Chat 應用程式。
  • 測試 Chat 應用程式。

必要條件

設定環境

啟用 Google Cloud API

使用 Google API 前，您需要在 Google Cloud 專案中啟用這些 API。 您可以在單一 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 >「Branding」(品牌)。

    前往「Branding」(品牌宣傳)

  2. 如果您已設定 Google Auth platform，可以在「Branding」(品牌)、「Audience」(目標對象) 和「Data Access」(資料存取權) 中設定下列 OAuth 同意畫面設定。如果看到「Get Started」(尚未設定)Google Auth platform 訊息，請按一下「開始使用」：
    1. 在 應用資訊 下的 應用程式名稱 中，輸入應用程式的名稱。
    2. 在「User support email」(使用者支援電子郵件) 中，選擇支援電子郵件地址，方便使用者在同意聲明方面有任何疑問時與您聯絡。
    3. 點選 [Next] (下一步)。
    4. 在「Audience」(目標對象) 下方，選取「Internal」(內部)。
    5. 點選 [Next] (下一步)。
    6. 在「Contact Information」(聯絡資訊) 下方，輸入可接收專案異動通知的電子郵件地址。
    7. 點選 [Next] (下一步)。
    8. 在「Finish」(完成) 部分，請詳閱《Google API 服務使用者資料政策》，然後選取「我同意《Google API 服務：使用者資料政策》」。
    9. 按一下 [Continue] (繼續)。
    10. 按一下「Create」(建立)。
  3. 目前，您可以先跳過新增作用域的步驟。 將來，當您建立要在 Google Workspace 組織之外使用的應用程式時，必須將 使用者類型 變更為 外部。然後新增您的應用程式所需的授權範圍。要瞭解更多信息，請參閱完整的 配置 OAuth 同意 指南。

在 Google Cloud 控制台中建立服務帳號。

請依照下列步驟建立具有 Vertex AI User 角色的新服務帳戶：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往「選單」。 > 身分與存取管理 > 服務帳戶。

    前往「Service Accounts」(服務帳戶) 頁面

  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 & Admin」(IAM 與管理) >「Service Accounts」(服務帳戶)。

    前往「Service Accounts」(服務帳戶) 頁面

  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 bucket。

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

    更改下列內容：

    1. CLOUD_STORAGE_BUCKET_NAME 替換成您要使用的不重複 bucket 名稱。
    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 Quickstart Apps Script 專案。

    開啟專案

  2. 依序點選「總覽」>建立副本的圖示「建立副本」。

  3. 在 Apps Script 專案中，依序點選 專案設定圖示「專案設定」>「編輯指令碼屬性」>「新增指令碼屬性」，加入下列指令碼屬性：

    1. REASONING_ENGINE_RESOURCE_NAME，並貼上先前步驟中複製的 Vertex AI 代理程式資源名稱。
    2. SERVICE_ACCOUNT_KEY，其中 { ... } 是您在先前步驟中下載的服務帳戶 JSON 金鑰。

  4. 按一下「儲存指令碼屬性」。

  5. 在 Google Cloud 控制台中，依序前往「選單」 >「IAM 與管理」>「設定」。

    前往「IAM & Admin Settings」(IAM 與管理員設定)

  6. 在「專案編號」欄位中，複製該值。

  7. 在 Apps Script 專案中，按一下 專案設定圖示「專案設定」。

  8. 點選「Google Cloud Platform (GCP) 專案」下方的「變更專案」。

  9. 在「GCP 專案編號」中，貼上先前步驟複製的 Google Cloud 專案編號。

  10. 點選「設定專案」。Cloud 專案和 Apps Script 專案現已連結。

建立測試部署作業

您需要這個 Apps Script 專案的部署作業 ID，才能在下一個步驟中使用。

如要取得主要部署 ID，請按照下列步驟操作：

  1. 在 Chat 應用程式的 Apps Script 專案中，依序點選「部署」>「測試部署作業」。
  2. 在「Head deployment ID」(主要部署作業 ID) 下方，按一下 建立副本的圖示「複製」。
  3. 按一下 [完成]。

設定 Chat 應用程式

使用 Apps Script 部署作業，按照下列步驟部署 Google Chat 應用程式以進行測試：

  1. 在控制台中搜尋 Google Chat API，然後按一下「Google Chat API」。
  2. 按一下「管理」。

  3. 按一下「設定」，然後設定 Chat 應用程式：

    1. 在「應用程式名稱」欄位中輸入 A2UI Quickstart。
    2. 在「Avatar URL」(大頭貼網址) 欄位中，輸入 https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png。
    3. 在「Description」(說明) 欄位輸入 A2UI Quickstart。
    4. 在 功能 下，選擇 加入空間和群組對話。
    5. 在連線設定下，選擇 Apps Script 項目。
    6. 在 部署 ID 欄位中，貼上您先前複製的 Head 部署 ID。
    7. 在“可見性”下，選擇“您網域中的特定人員和群組”，然後輸入您的電子郵件地址。

  4. 按一下 [儲存]。

聊天應用程式已準備好回覆訊息。

測試聊天應用

如要測試 Chat 應用程式，請開啟與該應用程式互傳的即時訊息，然後傳送訊息：

  1. 使用您在將自己新增為受信任測試人員時提供的 Google Workspace 帳戶開啟 Google Chat。

    前往 Google Chat

  2. 點選 新聊天。
  3. 在增加 1 人或多人在欄位中，輸入您的聊天應用程式名稱。

  4. 從結果中選取 Chat 應用程式。系統會開啟即時訊息。

  5. 在應用程式的新私訊中，輸入 Hello! 並按 enter。

    聊天應用程式會回覆訊息，其中包含問候語和一張卡片，卡片上包含個人資料名稱、圖片和 LinkedIn 按鈕。

  6. 更新 A2UI 代理程式的實現，使其也開始返回個人資料標題。

    在本機開發環境中，開啟檔案 a2ui/agent.py，並取消註解工具中將標題新增至傳回資料的行。

    apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py
    # 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。

    Chat 應用程式會回覆訊息，內容包含一些文字和含有設定檔名稱的資訊卡。

要新增受信任的測試人員並瞭解有關測試互動功能的更多信息，請參閱 測試 Google Chat 應用程式的互動式功能。

疑難排解

如果 Google Chat 應用程式或資訊卡傳回錯誤，Chat 介面會顯示「發生錯誤」訊息。或「無法處理您的要求。」有時 Chat UI 不會顯示任何錯誤訊息，但 Chat 應用程式或資訊卡會產生非預期的結果，例如資訊卡訊息可能不會顯示。

即使 Chat 使用者介面可能不會顯示錯誤訊息，但如果開啟 Chat 應用程式的錯誤記錄功能，系統就會提供說明性錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助，請參閱「排解及修正 Google Chat 錯誤」。

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，建議您刪除 Cloud 專案。

  1. 在 Google Cloud 控制台中，前往「管理資源」頁面。依序點選「選單」「IAM 與管理」「管理資源」。

    前往 Resource Manager

  2. 在專案清單中選取要刪除的專案，然後按一下「刪除」圖示 。
  3. 在對話方塊中輸入專案 ID，然後按一下「Shut down」(關閉) 即可刪除專案。