Tạo một ứng dụng Google Chat bằng tác nhân Agent2UI

Trang này giải thích cách tạo một tiện ích bổ sung Google Workspace hoạt động trong Google Chat và tương tác với một tác nhân AI sử dụng giao thức Agent2UI (A2UI). Bạn phát triển tác nhân bằng Agent Development Kit (ADK) và lưu trữ tác nhân đó trong Vertex AI Agent Engine.

Tác nhân AI tự quản nhận diện môi trường, suy luận và thực hiện các hành động phức tạp, nhiều bước để đạt được một mục tiêu đã xác định. Trong hướng dẫn này, bạn sẽ triển khai một tác nhân AI cơ bản trả về thông tin hồ sơ tĩnh được truy xuất từ một công cụ.

A2UI cho phép các tác nhân AI tạo ra giao diện người dùng thích ứng, đa dạng, mang tính tương tác và hiển thị một cách tự nhiên. Sau đó, bạn có thể tập trung vào logic của các tác nhân AI, chứ không phải giao diện người dùng.

Hình 1. Tác nhân A2UI phản hồi cho người dùng bằng văn bản và một thẻ chứa tên, hình ảnh và nút LinkedIn.
Hình 2. Tác nhân A2UI cũng được cập nhật để trả về tiêu đề hồ sơ.
Hình 3. Tác nhân A2UI phản hồi người dùng bằng một thông báo hiển thị tên hồ sơ trong thẻ.

Sơ đồ sau đây cho thấy cấu trúc và mẫu nhắn tin:

Cấu trúc của một ứng dụng Chat được triển khai bằng tác nhân AI A2UI.

Trong sơ đồ, một người dùng tương tác với ứng dụng Chat được triển khai bằng một tác nhân A2UI sẽ có luồng thông tin như sau:

Người dùng gửi tin nhắn đến một ứng dụng Chat, có thể là tin nhắn trực tiếp hoặc trong một phòng Chat.
Logic của ứng dụng Chat được triển khai trong Apps Script hoặc dưới dạng một máy chủ web có các điểm cuối HTTP sẽ nhận và xử lý thông báo.
Tác nhân A2UI được lưu trữ bằng Vertex AI Agent Engine sẽ nhận và xử lý hoạt động tương tác.
Bạn có thể chọn tích hợp ứng dụng Chat hoặc AI Agent với các dịch vụ của Google Workspace, chẳng hạn như Lịch hoặc Trang tính, hoặc các dịch vụ khác của Google, chẳng hạn như Google Maps hoặc YouTube.
Ứng dụng Chat tạo và gửi các phản hồi thích ứng không đồng bộ, sử dụng Google Chat API để thông báo tiến trình của tác nhân AI.
Các câu trả lời được gửi đến người dùng.

Mục tiêu

Thiết lập môi trường.
Triển khai tác nhân A2UI.
Triển khai ứng dụng Chat.
Định cấu hình ứng dụng Chat.
Kiểm thử ứng dụng Chat.

Điều kiện tiên quyết

Tài khoản Google Workspace Business hoặc Enterprise có quyền truy cập vào Google Chat.
Một dự án trên Google Cloud đã bật tính năng thanh toán. Để kiểm tra xem một dự án hiện có đã bật tính năng thanh toán hay chưa, hãy xem phần Xác minh trạng thái thanh toán của dự án. Để tạo dự án và thiết lập thông tin thanh toán, hãy xem bài viết Tạo dự án trên Google Cloud.
Python 3.11 trở lên: Để cài đặt, hãy làm theo hướng dẫn trên trang web chính thức của Python.
Python Poetry: Để cài đặt, hãy làm theo hướng dẫn trên trang web chính thức của Poetry.
Google Cloud CLI: Để cài đặt, hãy làm theo hướng dẫn trên trang web chính thức của Google Cloud.

Thiết lập môi trường

Bật Google Cloud API

Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.

Trong bảng điều khiển Google Cloud, hãy bật các API Google Chat, Vertex AI và Cloud Resource Manager.

Kích hoạt API

Định cấu hình màn hình xin phép bằng OAuth

Tất cả các ứng dụng sử dụng OAuth 2.0 đều yêu cầu cấu hình màn hình chấp thuận. Việc cấu hình màn hình chấp thuận OAuth của ứng dụng sẽ xác định những gì được hiển thị cho người dùng và người đánh giá ứng dụng, đồng thời đăng ký ứng dụng của bạn để bạn có thể xuất bản sau này.

Trong bảng điều khiển Google Cloud, hãy vào Menu. > Google Auth platform > Xây dựng thương hiệu .
Chuyển đến phần Thương hiệu
Nếu đã định cấu hình Google Auth platform, bạn có thể định cấu hình các chế độ cài đặt sau đây cho Màn hình xin phép bằng OAuth trong phần Thương hiệu, Đối tượng và Quyền truy cập dữ liệu. Nếu bạn thấy thông báo cho biết Google Auth platform chưa được định cấu hình, hãy nhấp vào Bắt đầu:

Trong Thông tin ứng dụng, tại Tên ứng dụng, hãy nhập tên cho ứng dụng.
Trong phần Email hỗ trợ người dùng, hãy chọn một địa chỉ email hỗ trợ mà người dùng có thể liên hệ với bạn nếu họ có thắc mắc về sự đồng ý của mình.
Nhấp vào Tiếp theo.
Trong phần Đối tượng, hãy chọn Nội bộ.
Nhấp vào Tiếp theo.
Trong phần Thông tin liên hệ, hãy nhập Địa chỉ email để bạn có thể nhận thông báo về mọi thay đổi đối với dự án của mình.
Nhấp vào Tiếp theo.
Trong phần Hoàn tất, hãy xem kỹ Chính sách dữ liệu người dùng của dịch vụ API của Google. Nếu bạn đồng ý, hãy chọn Tôi đồng ý với Chính sách dữ liệu người dùng của dịch vụ API của Google.
Nhấp vào Tiếp tục.
Nhấp vào Tạo.

Hiện tại, bạn có thể bỏ qua bước thêm phạm vi. Trong tương lai, khi tạo một ứng dụng để sử dụng bên ngoài tổ chức Google Workspace, bạn phải thay đổi Loại người dùng thành Bên ngoài. Sau đó, hãy thêm các phạm vi uỷ quyền mà ứng dụng của bạn yêu cầu. Để tìm hiểu thêm, hãy xem hướng dẫn đầy đủ về cách Định cấu hình màn hình xin phép bằng OAuth.

Tạo tài khoản dịch vụ trong bảng điều khiển Google Cloud.

Tạo tài khoản dịch vụ mới với vai trò Vertex AI User bằng cách làm theo các bước sau:

Bảng điều khiển Google Cloud

Trong bảng điều khiển Google Cloud, hãy vào Menu. > Quản trị IAM & Quản trị > Tài khoản dịch vụ .
Đi đến Tài khoản Dịch vụ
Nhấp vào Tạo tài khoản dịch vụ.
Điền thông tin chi tiết tài khoản dịch vụ, sau đó nhấp vào Tạo và tiếp tục.
Lưu ý: Theo mặc định, Google tạo một ID tài khoản dịch vụ duy nhất. Nếu bạn muốn thay đổi ID, hãy chỉnh sửa ID trong trường ID tài khoản dịch vụ.
Tùy chọn: Gán vai trò cho tài khoản dịch vụ của bạn để cấp quyền truy cập vào các tài nguyên của dự án Google Cloud. Để biết thêm chi tiết, hãy tham khảo Cấp, thay đổi và thu hồi quyền truy cập tài nguyên.
Nhấp vào Tiếp tục.
Tùy chọn: Nhập người dùng hoặc nhóm có thể quản lý và thực hiện các thao tác với tài khoản dịch vụ này. Để biết thêm chi tiết, hãy tham khảo Quản lý mạo danh tài khoản dịch vụ.
Nhấp vào Xong. Hãy ghi lại địa chỉ email của tài khoản dịch vụ.

gcloud CLI

Tạo tài khoản dịch vụ:

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

Tùy chọn: Gán vai trò cho tài khoản dịch vụ của bạn để cấp quyền truy cập vào các tài nguyên của dự án Google Cloud. Để biết thêm chi tiết, hãy tham khảo Cấp, thay đổi và thu hồi quyền truy cập tài nguyên.

Tài khoản dịch vụ hiển thị trên trang tài khoản dịch vụ.

Tạo khóa riêng tư

Để tạo và tải xuống khóa riêng cho tài khoản dịch vụ, hãy làm theo các bước sau:

Trong bảng điều khiển Google Cloud, hãy vào Menu. > Quản trị IAM & Quản trị > Tài khoản dịch vụ .
Đi đến Tài khoản Dịch vụ
Chọn tài khoản dịch vụ của bạn.
Nhấp chuột Chìa khóa > Thêm khóa > Tạo khóa mới.
Chọn JSON, sau đó nhấp vào Tạo.
Cặp khóa công khai/riêng tư mới của bạn đã được tạo và tải xuống máy tính của bạn dưới dạng một tệp mới. Lưu tệp JSON đã tải xuống dưới dạng credentials.json trong thư mục làm việc của bạn. Tệp này là bản sao duy nhất của khóa này. Để biết thông tin về cách lưu trữ khóa của bạn một cách an toàn, hãy xem Quản lý khóa tài khoản dịch vụ.
Nhấp vào Close (Đóng).

Để biết thêm thông tin về tài khoản dịch vụ, hãy xem tài khoản dịch vụ trong tài liệu Google Cloud IAM.

Triển khai tác nhân A2UI

Nếu bạn chưa làm vậy, hãy xác thực bằng tài khoản Google Cloud của mình và cấu hình Google Cloud CLI để sử dụng dự án Google Cloud của bạn.
```
gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID
```
Thay thế PROJECT_ID bằng ID của dự án Cloud của bạn.
Tải xuống kho lưu trữ GitHub googleworkspace/add-ons-samples bằng nút này:

Tải xuống kho lưu trữ
Trong môi trường phát triển cục bộ mà bạn ưa thích, hãy giải nén tệp lưu trữ đã tải xuống và mở thư mục 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
```
Tạo một bucket Cloud Storage mới dành riêng cho tác nhân ADK.
```
gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION
```
Thay thế nội dung sau:
1. CLOUD_STORAGE_BUCKET_NAME với tên bucket duy nhất mà bạn muốn sử dụng.
2. PROJECT_ID với ID của dự án Cloud của bạn.
3. PROJECT_LOCATION với vị trí của dự án Cloud của bạn.
Thiết lập các biến môi trường sau:
```
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
```
Thay thế nội dung sau:
1. CLOUD_STORAGE_BUCKET_NAME với tên của bucket mà bạn đã tạo.
2. PROJECT_ID với ID của dự án Cloud của bạn.
3. PROJECT_LOCATION với vị trí dự án Cloud của bạn.

Cài đặt và triển khai tác nhân ADK từ môi trường ảo.

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

Lấy ID của đại lý. Bạn sẽ cần nó sau này, khi cấu hình ứng dụng Chat.
```
python3 deployment/deploy.py --list
```

Tạo và định cấu hình dự án ứng dụng Chat

Nhấp vào nút sau để mở dự án A2UI AI Agent Quickstart (Hướng dẫn nhanh về Trợ lý AI A2UI) trong Apps Script.

Mở dự án
Nhấp vào Tổng quan > Tạo bản sao.
Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án > Chỉnh sửa thuộc tính tập lệnh > Thêm thuộc tính tập lệnh để thêm các thuộc tính tập lệnh sau:
1. REASONING_ENGINE_RESOURCE_NAME bằng tên tài nguyên của tác nhân Vertex AI đã sao chép ở các bước trước.
2. SERVICE_ACCOUNT_KEY có khoá JSON từ tài khoản dịch vụ được tải xuống trong các bước trước, chẳng hạn như { ... }.
Nhấp vào Lưu thuộc tính của tập lệnh.
Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > IAM và quản trị > Cài đặt.

Chuyển đến phần IAM và Cài đặt quản trị
Sao chép giá trị trong trường Số dự án.
Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án.
Trong phần Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
Trong mục Số dự án trên Google Cloud, hãy dán số dự án trên Google Cloud mà bạn đã sao chép ở các bước trước.
Nhấp vào Đặt dự án. Dự án trên đám mây và dự án Apps Script hiện đã được kết nối.

Tạo một bản triển khai kiểm thử

Bạn cần có một mã nhận dạng triển khai cho dự án Apps Script này để có thể sử dụng mã đó trong bước tiếp theo.

Để lấy mã nhận dạng triển khai đầu, hãy làm như sau:

Trong dự án Apps Script của ứng dụng Chat, hãy nhấp vào Triển khai > Triển khai thử nghiệm.
Dưới ID triển khai Head, hãy nhấp vào Sao chép.
Nhấp vào Xong.

Cấu hình ứng dụng Trò chuyện

Sử dụng công cụ triển khai Apps Script, hãy làm theo các bước sau để triển khai ứng dụng Google Chat để thử nghiệm:

Trong bảng điều khiển, tìm kiếm Google Chat API và nhấp vào API Google Chat.
Nhấp vào Quản lý.
Nhấp vào Cấu hình và thiết lập ứng dụng Trò chuyện:
1. Trong trường Tên ứng dụng, hãy nhập A2UI Quickstart.
2. Trong trường URL Avatar, hãy nhập https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
3. Trong trường Mô tả, hãy nhập A2UI Quickstart.
4. Trong Chức năng, hãy chọn Tham gia không gian và cuộc trò chuyện nhóm.
5. Trong phần Cài đặt kết nối, chọn Dự án Apps Script.
6. Trong trường ID Triển khai, hãy dán ID triển khai Head mà bạn đã sao chép trước đó.
7. Trong mục Hiển thị, chọn Những người và nhóm cụ thể trong miền của bạn và nhập email của bạn.
Nhấp vào Lưu.

Ứng dụng trò chuyện đã sẵn sàng để trả lời tin nhắn.

Kiểm tra ứng dụng Chat

Để kiểm tra ứng dụng Chat của bạn, hãy mở một cửa sổ nhắn tin trực tiếp trong ứng dụng Chat và gửi một tin nhắn:

Mở Google Chat bằng tài khoản Google Workspace mà bạn đã cung cấp khi thêm mình vào danh sách người thử nghiệm đáng tin cậy.

Chuyển đến Google Chat
Nhấp vào Trò chuyện mới.
Trong trường Thêm 1 người trở lên, hãy nhập tên ứng dụng Chat của bạn.
Chọn ứng dụng trò chuyện của bạn từ kết quả tìm kiếm. Một tin nhắn trực tiếp được mở ra.

Lưu ý: Nếu bạn không thấy ứng dụng Chat của mình trong danh sách kết quả, hãy đảm bảo rằng bạn đã thêm tài khoản Google Workspace của mình vào phần Khả năng hiển thị trong trang Cấu hình API Chat trên bảng điều khiển Google Cloud.
Trong tin nhắn trực tiếp mới trên ứng dụng, hãy nhập Hello! và nhấn enter.

Ứng dụng Chat sẽ trả lời tin nhắn bằng lời chào và một thẻ chứa tên hồ sơ, ảnh đại diện và nút LinkedIn.

Cập nhật việc triển khai tác nhân A2UI để bắt đầu trả về cả tiêu đề hồ sơ.

Trong môi trường phát triển cục bộ, hãy mở tệp a2ui/agent.py và bỏ chú thích dòng trong công cụ thêm tiêu đề vào dữ liệu được trả về.

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

Xem trên 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]
)

Cập nhật ADK đã triển khai trước đó bằng phiên bản triển khai mới.
```
python3 deployment/deploy.py --update --resource_id=RESOURCE_ID
```
Thay thế RESOURCE_ID bằng tên tài nguyên của tác nhân Vertex AI mà bạn đã sao chép ở các bước trước.
Trong tin nhắn trực tiếp với ứng dụng, hãy nhập Hello again! rồi nhấn enter.

Ứng dụng Chat trả lời một tin nhắn bằng một đoạn văn bản và một thẻ chứa tiêu đề hồ sơ.

Để thêm người kiểm thử đáng tin cậy và tìm hiểu thêm về việc kiểm thử các tính năng tương tác, hãy xem bài viết Kiểm thử các tính năng tương tác cho ứng dụng Google Chat.

Khắc phục sự cố

Khi một ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã xảy ra lỗi". hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng Chat không hiển thị bất kỳ thông báo lỗi nào, nhưng ứng dụng hoặc thẻ Chat lại tạo ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.

Mặc dù thông báo lỗi có thể không xuất hiện trong giao diện người dùng Chat, nhưng bạn có thể sử dụng thông báo lỗi mô tả và dữ liệu nhật ký để khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho ứng dụng Chat. Để được trợ giúp xem, gỡ lỗi và khắc phục lỗi, hãy xem bài viết Khắc phục lỗi trong Google Chat.

Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong hướng dẫn này, bạn nên xoá dự án trên Cloud.

Thận trọng: Thao tác xoá dự án sẽ gây ra những tác động sau:

Mọi nội dung trong dự án sẽ bị xoá. Nếu đã dùng một dự án hiện có cho hướng dẫn này, thì khi xoá dự án đó, bạn cũng sẽ xoá mọi công việc khác mà bạn đã thực hiện trong dự án.
Mã dự án tuỳ chỉnh sẽ bị mất. Khi tạo dự án này, có thể bạn đã tạo một mã dự án tuỳ chỉnh mà bạn muốn sử dụng trong tương lai. Để giữ lại những URL sử dụng mã dự án (chẳng hạn như URL trên appspot.com), hãy xoá các tài nguyên đã chọn trong dự án thay vì xoá toàn bộ dự án.

Nếu bạn dự định khám phá nhiều hướng dẫn và hướng dẫn bắt đầu nhanh, thì việc sử dụng lại các dự án có thể giúp bạn tránh vượt quá hạn mức dự án.

Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên. Nhấp vào Trình đơn > IAM và Quản trị viên > Quản lý tài nguyên.
Chuyển đến Resource Manager
Trong danh sách dự án, hãy chọn dự án bạn muốn xoá rồi nhấp vào biểu tượng Xoá .
Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.