Membangun aplikasi Google Chat dengan agen Agent2UI

Halaman ini menjelaskan cara membuat add-on Google Workspace yang berfungsi di Google Chat dan berinteraksi dengan agen AI yang menggunakan protokol Agent2UI (A2UI). Anda mengembangkan agen menggunakan Agent Development Kit (ADK), dan menghostingnya di Vertex AI Agent Engine.

Agen AI secara otonom memahami lingkungan, bernalar, dan menjalankan tindakan multi-langkah yang kompleks untuk mencapai sasaran yang ditentukan. Dalam tutorial ini, Anda akan men-deploy agen AI dasar yang menampilkan informasi profil statis yang diambil dari alat.

A2UI memungkinkan agen AI membuat UI interaktif, kaya, dan adaptif yang dirender secara native. Kemudian, Anda dapat berfokus pada logika agen AI, bukan UI.

Diagram berikut menunjukkan arsitektur dan pola pengiriman pesan:

Dalam diagram, pengguna yang berinteraksi dengan aplikasi Chat yang diimplementasikan dengan agen A2UI memiliki alur informasi berikut:

1. Pengguna mengirim pesan ke aplikasi Chat, baik di pesan langsung maupun di ruang Chat.
2. Logika aplikasi Chat yang diterapkan di Apps Script atau sebagai server web dengan endpoint HTTP menerima dan memproses pesan.
3. Agen A2UI yang dihosting dengan Vertex AI Agent Engine menerima dan memproses interaksi.
4. Secara opsional, aplikasi Chat atau agen AI dapat terintegrasi dengan layanan Google Workspace, seperti Kalender atau Spreadsheet, atau Layanan Google lainnya, seperti Google Maps atau YouTube.
5. Aplikasi Chat membuat dan mengirim respons adaptif secara asinkron, menggunakan Google Chat API untuk mengomunikasikan progres agen AI.
6. Respons dikirimkan kepada pengguna.

Tujuan

• Siapkan lingkungan Anda.
• Deploy agen A2UI.
• Deploy aplikasi Chat.
• Konfigurasi aplikasi Chat.
• Uji aplikasi Chat.

Prasyarat

• Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
• Project Google Cloud yang mengaktifkan penagihan. Untuk memeriksa apakah penagihan diaktifkan untuk project yang ada, lihat Memverifikasi status penagihan project Anda. Untuk membuat project dan menyiapkan penagihan, lihat Membuat project Google Cloud.
• Python 3.11+: Untuk penginstalan, ikuti petunjuk di situs Python resmi.
• Python Poetry: Untuk penginstalan, ikuti petunjuk di situs Poetry resmi.
• Google Cloud CLI: Untuk penginstalan, ikuti petunjuk di situs Google Cloud resmi.

Menyiapkan lingkungan Anda

Mengaktifkan Google Cloud API

Sebelum menggunakan Google API, Anda harus mengaktifkannya di project Google Cloud. Anda dapat mengaktifkan satu atau beberapa API dalam satu project Google Cloud.

• Di Konsol Google Cloud, aktifkan Google Chat, Vertex AI, dan Cloud Resource Manager API.

  Aktifkan API

Mengonfigurasi layar izin OAuth

Semua aplikasi yang menggunakan OAuth 2.0 memerlukan konfigurasi layar izin. Mengonfigurasi layar izin OAuth aplikasi Anda menentukan apa yang ditampilkan kepada pengguna dan peninjau aplikasi, serta mendaftarkan aplikasi Anda sehingga Anda dapat memublikasikannya nanti.

1. Di Konsol Google Cloud, buka Menu menu > Google Auth platform > Branding.

   Buka Branding

2. Jika sudah mengonfigurasi Google Auth platform, Anda dapat mengonfigurasi setelan Layar Izin OAuth berikut di Branding, Audiens, dan Akses Data. Jika Anda melihat pesan yang menyatakan Google Auth platform belum dikonfigurasi, klik Mulai:
1. Di bagian Informasi Aplikasi, di Nama aplikasi, masukkan nama untuk aplikasi.
2. Di bagian Email dukungan pengguna, pilih alamat email dukungan yang dapat dihubungi pengguna jika mereka memiliki pertanyaan tentang izin mereka.
3. Klik Berikutnya.
4. Di bagian Audiens, pilih Internal.
5. Klik Berikutnya.
6. Di bagian Informasi Kontak, masukkan Alamat email tempat Anda dapat menerima notifikasi tentang perubahan apa pun pada project Anda.
7. Klik Berikutnya.
8. Di bagian Selesai, tinjau Kebijakan Data Pengguna Layanan Google API dan jika Anda setuju, pilih Saya menyetujui Layanan Google API: Kebijakan Data Pengguna.
9. Klik Lanjutkan.
10. Klik Buat.
3. Untuk saat ini, Anda dapat melewati penambahan cakupan. Pada masa mendatang, saat membuat aplikasi untuk digunakan di luar organisasi Google Workspace Anda, Anda harus mengubah Jenis pengguna menjadi Eksternal. Kemudian tambahkan cakupan otorisasi yang diperlukan aplikasi Anda. Untuk mempelajari lebih lanjut, lihat panduan lengkap Mengonfigurasi izin OAuth.

Buat akun layanan di konsol Google Cloud

Buat akun layanan baru dengan peran Vertex AI User dengan mengikuti langkah-langkah berikut:

Konsol Google Cloud

1. Di Konsol Google Cloud, buka Menu menu > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Klik Create service account.
3. Isi detail akun layanan, lalu klik Buat dan lanjutkan.
4. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.
5. Klik Lanjutkan.
6. Opsional: Masukkan pengguna atau grup yang dapat mengelola dan melakukan tindakan dengan akun layanan ini. Untuk mengetahui detail selengkapnya, lihat Mengelola peniruan identitas akun layanan.
7. Klik Selesai. Catat alamat email untuk akun layanan.

gcloud CLI

1. Buat akun layanan:

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

2. Opsional: Tetapkan peran ke akun layanan Anda untuk memberikan akses ke sumber daya proyek Google Cloud Anda. Untuk detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke sumber daya.

Akun layanan akan muncul di halaman akun layanan.

Buat kunci pribadi

Untuk membuat dan mengunduh kunci pribadi untuk akun layanan, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud, buka Menu.menu > IAM & Admin > Akun Layanan .

   Buka Akun Layanan

2. Pilih akun layanan Anda.
3. Klik Kunci > Tambahkan kunci > Buat kunci baru.
4. Pilih JSON, lalu klik Buat.

   Pasangan kunci publik/pribadi baru Anda telah dibuat dan diunduh ke komputer Anda sebagai file baru. Simpan file JSON yang diunduh sebagai credentials.json di direktori kerja Anda. Berkas ini adalah satu-satunya salinan kunci ini. Untuk informasi tentang cara menyimpan kunci Anda dengan aman, lihat Mengelola kunci akun layanan.

5. Klik Tutup.

Untuk mengetahui informasi selengkapnya tentang akun layanan, lihat akun layanan dalam dokumentasi IAM Google Cloud.

Men-deploy agen A2UI

1. Jika Anda belum melakukannya, lakukan autentikasi dengan akun Google Cloud Anda dan konfigurasi Google Cloud CLI untuk menggunakan project Google Cloud Anda.

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

   Ganti PROJECT_ID dengan ID project Cloud Anda.

2. Download repositori GitHub googleworkspace/add-ons-samples menggunakan tombol ini:

   Download repositori

3. Di lingkungan pengembangan lokal pilihan Anda, ekstrak file arsip yang didownload dan buka direktori 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. Buat bucket Cloud Storage baru yang dikhususkan untuk agen ADK.

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

   Ganti kode berikut:

   1. CLOUD_STORAGE_BUCKET_NAME dengan nama bucket unik yang ingin Anda gunakan.
   2. PROJECT_ID dengan ID project Cloud Anda.
   3. PROJECT_LOCATION dengan lokasi project Cloud Anda.

5. Tetapkan variabel lingkungan berikut:

   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

   Ganti kode berikut:

   1. CLOUD_STORAGE_BUCKET_NAME dengan nama bucket yang Anda buat.
   2. PROJECT_ID dengan ID project Cloud Anda.
   3. PROJECT_LOCATION dengan lokasi project Cloud Anda.

6. Instal dan deploy agen ADK dari lingkungan virtual.

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

7. Ambil ID agen. Anda akan memerlukannya nanti, saat mengonfigurasi aplikasi Chat.

   python3 deployment/deploy.py --list

Membuat dan mengonfigurasi project aplikasi Chat

1. Klik tombol berikut untuk membuka project Apps Script A2UI AI Agent Quickstart.

   Membuka project

2. Klik info_outline Ringkasan > Buat salinan.

3. Di project Apps Script Anda, klik Setelan Project > Edit properti skrip > Tambahkan properti skrip untuk menambahkan properti skrip berikut:

   1. REASONING_ENGINE_RESOURCE_NAME dengan nama resource agen Vertex AI yang disalin di langkah sebelumnya.
   2. SERVICE_ACCOUNT_KEY dengan kunci JSON dari akun layanan yang didownload pada langkah sebelumnya, seperti { ... }.

4. Klik Simpan properti skrip.

5. Di konsol Google Cloud, buka Menu menu > IAM & Admin > Setelan.

   Buka Setelan IAM & Admin

6. Di kolom Project number, salin nilai.

7. Di project Apps Script Anda, klik Project Settings.

8. Pada Google Cloud Platform (GCP) Project, klik Change project.

9. Di GCP project number, tempelkan nomor project Google Cloud yang disalin pada langkah-langkah sebelumnya.

10. Klik Set project. Project Cloud dan project Apps Script kini terhubung.

Membuat deployment pengujian

Anda memerlukan ID deployment untuk project Apps Script ini, sehingga Anda dapat menggunakannya pada langkah berikutnya.

Untuk mendapatkan ID deployment head, lakukan hal berikut:

1. Di project Apps Script aplikasi Chat, klik Deploy > Test deployments.
2. Di bagian ID deployment head, klik Salin.
3. Klik Selesai.

Mengonfigurasi aplikasi Chat

Dengan menggunakan deployment Apps Script, ikuti langkah-langkah berikut untuk men-deploy aplikasi Google Chat untuk pengujian:

1. Di konsol, cari Google Chat API, lalu klik Google Chat API.
2. Klik Manage.

3. Klik Konfigurasi dan siapkan aplikasi Chat:

   1. Di kolom Nama aplikasi, masukkan A2UI Quickstart.
   2. Di kolom Avatar URL, masukkan https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. Di kolom Description, masukkan A2UI Quickstart.
   4. Di bagian Functionality, pilih Join spaces and group conversations.
   5. Di bagian Connection settings, pilih Apps Script project.
   6. Di kolom Deployment ID, tempelkan ID deployment Head yang sebelumnya Anda salin.
   7. Di bagian Visibilitas, pilih Orang dan grup tertentu di domain Anda, lalu masukkan email Anda.

4. Klik Simpan.

Aplikasi Chat siap merespons pesan.

Menguji aplikasi Chat

Untuk menguji aplikasi Chat Anda, buka ruang pesan langsung dengan aplikasi Chat dan kirim pesan:

1. Buka Google Chat menggunakan akun Google Workspace yang Anda berikan saat menambahkan diri Anda sebagai penguji tepercaya.

   Buka Google Chat

2. Klik add Chat baru.
3. Di kolom Tambahkan 1 orang atau lebih, ketik nama aplikasi Chat Anda.

4. Pilih aplikasi Chat Anda dari hasil. Pesan langsung akan terbuka.

5. Di pesan langsung baru dengan aplikasi, ketik Hello!, lalu tekan enter.

   Aplikasi Chat membalas pesan dengan teks ucapan dan kartu yang berisi nama profil, gambar, dan tombol LinkedIn.

6. Perbarui penerapan agen A2UI untuk mulai menampilkan judul profil juga.

   Di lingkungan pengembangan lokal, buka file a2ui/agent.py dan hapus komentar baris di alat yang menambahkan judul ke data yang ditampilkan.

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

   Lihat di 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. Perbarui ADK yang sebelumnya di-deploy dengan penerapan versi baru.

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

   Ganti RESOURCE_ID dengan nama resource agen Vertex AI yang disalin pada langkah sebelumnya.

8. Di pesan langsung dengan aplikasi, ketik Hello again! dan tekan enter.

   Aplikasi obrolan membalas pesan dengan beberapa teks dan kartu yang berisi judul profil.

Untuk menambahkan penguji tepercaya dan mempelajari lebih lanjut tentang pengujian fitur interaktif, lihat Uji fitur interaktif untuk aplikasi Google Chat.

Memecahkan masalah

Ketika aplikasi Google Chat atau card mengembalikan kesalahan, antarmuka Chat menampilkan pesan yang mengatakan "Terjadi kesalahan." atau "Permintaan Anda tidak dapat diproses." Terkadang antarmuka pengguna obrolan tidak menampilkan pesan kesalahan apa pun, tetapi aplikasi atau kartu obrolan menghasilkan hasil yang tidak terduga; misalnya, pesan kartu mungkin tidak muncul.

Meskipun pesan kesalahan mungkin tidak ditampilkan di antarmuka pengguna Obrolan, pesan kesalahan deskriptif dan data log tersedia untuk membantu Anda memperbaiki kesalahan saat pencatatan kesalahan untuk aplikasi Obrolan diaktifkan. Untuk bantuan melihat, men-debug, dan memperbaiki kesalahan, lihat Memecahkan masalah dan memperbaiki kesalahan Google Chat.

Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, sebaiknya hapus project Cloud tersebut.

1. Di Konsol Google Cloud, buka halaman Manage resources. Klik Menu menu > IAM & Admin > Kelola Resource.

   Buka Resource Manager

2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Hapus delete.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Topik terkait

• Membangun aplikasi Google Chat dengan agen AI ADK
• Membangun aplikasi Google Chat dengan agen A2A
• Memeriksa fakta pernyataan dengan agen AI ADK dan model Gemini
• Merencanakan perjalanan dengan agen AI yang dapat diakses di seluruh Google Workspace
• Mengintegrasikan konsep AI dasar di aplikasi Chat
• Menjawab pertanyaan berdasarkan percakapan Chat dengan aplikasi Chat AI Gemini
• Merespons insiden dengan Google Chat, Vertex AI, Apps Script, dan autentikasi pengguna
• Mengelola project dengan Google Chat, Vertex AI, dan Firestore