Membangun aplikasi Google Chat dengan agen Agent2Agent

Pratinjau Vertex AI Agent Builder: Pengembangan dan penggunaan agen Agent2Agent (A2A) dalam Pratinjau. Lihat dokumentasi lengkap.

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

Catatan: Di Google Chat, add-on muncul kepada pengguna sebagai aplikasi Google Chat. Anda juga dapat membuat aplikasi Chat menggunakan peristiwa interaksi Google Chat API. Untuk mempelajari lebih lanjut, lihat Ringkasan cara memperluas Google Chat.

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 contoh multi-agen LLM Auditor yang mengkritik dan merevisi fakta menggunakan perujukan Gemini dan Google Penelusuran.

Diagram berikut menunjukkan arsitektur dan pola pengiriman pesan:

Dalam diagram, pengguna yang berinteraksi dengan aplikasi Chat yang diimplementasikan dengan agen A2A 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 A2A 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 mengirimkan respons secara asinkron, menggunakan Google Chat API untuk mengomunikasikan progres agen AI.
6. Respons dikirimkan kepada pengguna.

Tujuan

• Siapkan lingkungan Anda.
• Deploy agen A2A.
• 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.
• Prasyarat agen ADK LLM Auditor
  • 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 > 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 bertuliskan 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.

Membuat 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 > IAM & Admin > Service Accounts.

   Buka Akun Layanan

2. Klik Create service account.
3. Isi detail akun layanan, lalu klik Buat dan lanjutkan.
   Catatan: Secara default, Google membuat ID akun layanan yang unik. Jika Anda ingin mengubah ID, ubah ID di kolom ID akun layanan.
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 resource project Google Cloud Anda. Untuk mengetahui detail selengkapnya, lihat Memberikan, mengubah, dan mencabut akses ke resource.

Akun layanan akan muncul di halaman akun layanan.

Buat kunci pribadi

Peringatan: Contoh ini menggunakan kunci akun layanan yang diekspor agar lebih mudah. Mengekspor kunci pribadi tidak direkomendasikan dalam produksi karena kunci tersebut tidak boleh disimpan di lokasi yang tidak aman, seperti kontrol sumber.

Untuk mempelajari lebih lanjut penerapan akun layanan yang aman dan praktik terbaik, lihat Memilih waktu penggunaan akun layanan.

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

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

   Buka Akun Layanan

2. Pilih akun layanan Anda.
3. Klik Keys > Add key > Create new key.
4. Pilih JSON, lalu klik Buat.

   Pasangan kunci umum/pribadi baru Anda dibuat dan didownload ke komputer Anda sebagai file baru. Simpan file JSON yang didownload sebagai credentials.json di direktori kerja Anda. File ini adalah satu-satunya salinan kunci ini. Untuk mengetahui 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 Google Cloud IAM.

Men-deploy agen A2A

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 contoh ADK menggunakan tombol ini:

   Download adk-samples

3. Di lingkungan pengembangan lokal pilihan Anda, ekstrak file arsip yang didownload dan buka direktori adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Perbarui implementasi untuk men-deploy agen ADK sebagai agen jarak jauh A2A:

   1. pyproject.toml: Tambahkan dependensi ADK dan A2A SDK dalam grup deployment.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml

      Lihat di GitHub
      [project]
      name = "llm-auditor"
      version = "0.1.0"
      description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
      authors = [
          { name = "Chun-Sung Ferng", email = "[e-mail]" },
          { name = "Cyrus Rashtchian", email = "[e-mail]" },
          { name = "Da-Cheng Juan", email = "[e-mail]" },
          { name = "Ivan Kuznetsov", email = "[e-mail]" },
      ]
      license = "Apache License 2.0"
      readme = "README.md"
      
      [tool.poetry.dependencies]
      python = "^3.10"
      google-adk = "^1.0.0"
      google-cloud-aiplatform = { extras = [
          "adk",
          "agent-engines",
      ], version = "^1.93.0" }
      google-genai = "^1.9.0"
      pydantic = "^2.10.6"
      python-dotenv = "^1.0.1"
      
      [tool.poetry.group.dev]
      optional = true
      
      [tool.poetry.group.dev.dependencies]
      google-adk = { version = "^1.0.0", extras = ["eval"] }
      pytest = "^8.3.5"
      pytest-asyncio = "^0.26.0"
      
      [tool.poetry.group.deployment]
      optional = true
      
      [tool.poetry.group.deployment.dependencies]
      absl-py = "^2.2.1"
      google-adk = "^1.0.0"
      a2a-sdk = "^0.3.0"
      
      [build-system]
      requires = ["poetry-core>=2.0.0,<3.0.0"]
      build-backend = "poetry.core.masonry.api"

   2. deployment/deploy.py: Mengganti deployment aplikasi ADK dengan agen dan kartu A2A.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py

      Lihat di GitHub
      # Copyright 2025 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.
      
      """Deployment script for LLM Auditor."""
      
      import os
      
      from absl import app
      from absl import flags
      from dotenv import load_dotenv
      from llm_auditor.agent import root_agent
      import vertexai
      from vertexai import agent_engines
      
      # A2A wrapping
      from a2a.types import AgentSkill
      from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
      from google.adk.runners import InMemoryRunner
      from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
      from vertexai.preview.reasoning_engines import A2aAgent
      
      FLAGS = flags.FLAGS
      flags.DEFINE_string("project_id", None, "GCP project ID.")
      flags.DEFINE_string("location", None, "GCP location.")
      flags.DEFINE_string("bucket", None, "GCP bucket.")
      flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")
      
      flags.DEFINE_bool("list", False, "List all agents.")
      flags.DEFINE_bool("create", False, "Creates a new agent.")
      flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
      flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])
      
      
      def create() -> None:
          """Creates an agent engine for LLM Auditor."""
          agent_card = create_agent_card(
              agent_name=root_agent.name,
              description=root_agent.description,
              skills=[AgentSkill(
                  id='audit_llm_output',
                  name='Audit LLM Output',
                  description='Critiques and revises outputs from large language models.',
                  tags=['LLM', 'Audit', 'Revision'],
                  examples=[
                      'The earth is flat.',
                      'The capital of France is Berlin.',
                      'The last winner of the Super Bowl was the New England Patriots in 2020.',
                  ],
              )]
          )
          a2a_agent = A2aAgent(
              agent_card=agent_card,
              agent_executor_builder=lambda: A2aAgentExecutor(
                  runner=InMemoryRunner(
                      app_name=root_agent.name,
                      agent=root_agent,
                  )
              )
          )
          a2a_agent.set_up()
      
          remote_agent = agent_engines.create(
              a2a_agent,
              display_name=root_agent.name,
              requirements=[
                      "google-adk (>=0.0.2)",
                      "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                      "google-genai (>=1.5.0,<2.0.0)",
                      "pydantic (>=2.10.6,<3.0.0)",
                      "absl-py (>=2.2.1,<3.0.0)",
                      "a2a-sdk>=0.3.22",
                      "uvicorn",
              ],
              # In-memory runner
              max_instances=1,
              env_vars ={
                  "NUM_WORKERS": "1"
              },
              extra_packages=["./llm_auditor"],
          )
          print(f"Created remote agent: {remote_agent.resource_name}")
      
      
      def delete(resource_id: str) -> None:
          remote_agent = agent_engines.get(resource_id)
          remote_agent.delete(force=True)
          print(f"Deleted remote agent: {resource_id}")
      
      
      def list_agents() -> None:
          remote_agents = agent_engines.list()
          TEMPLATE = '''
      {agent.name} ("{agent.display_name}")
      - Create time: {agent.create_time}
      - Update time: {agent.update_time}
      '''
          remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
          print(f"All remote agents:\n{remote_agents_string}")
      
      def main(argv: list[str]) -> None:
          del argv  # unused
          load_dotenv()
      
          project_id = (
              FLAGS.project_id
              if FLAGS.project_id
              else os.getenv("GOOGLE_CLOUD_PROJECT")
          )
          location = (
              FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
          )
          bucket = (
              FLAGS.bucket if FLAGS.bucket
              else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
          )
      
          print(f"PROJECT: {project_id}")
          print(f"LOCATION: {location}")
          print(f"BUCKET: {bucket}")
      
          if not project_id:
              print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
              return
          elif not location:
              print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
              return
          elif not bucket:
              print(
                  "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
              )
              return
      
          vertexai.init(
              project=project_id,
              location=location,
              staging_bucket=f"gs://{bucket}",
          )
      
          if FLAGS.list:
              list_agents()
          elif FLAGS.create:
              create()
          elif FLAGS.delete:
              if not FLAGS.resource_id:
                  print("resource_id is required for delete")
                  return
              delete(FLAGS.resource_id)
          else:
              print("Unknown command")
      
      
      if __name__ == "__main__":
          app.run(main)

5. 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.

6. 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.

7. 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

8. 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 Panduan Memulai Agen AI A2A.

   Membuka project

2. Klik 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 > IAM & Admin > Settings.

   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 A2A Quickstart.
   2. Di kolom Avatar URL, masukkan https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. Di kolom Description, masukkan A2A 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 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.

   Catatan: Jika Anda tidak melihat aplikasi Chat di daftar hasil, pastikan Anda telah menyertakan akun Google Workspace di setelan Visibilitas pada halaman Konfigurasi Chat API di konsol Google Cloud.

5. Di pesan langsung baru dengan aplikasi, ketik The Eiffel Tower was completed in 1900, lalu tekanenter.

   Aplikasi Chat akan membalas dengan respons sub-agen Pengkritik dan Pengubah.

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

Memecahkan masalah

Saat aplikasi atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang mengatakan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi atau kartu Chat menghasilkan hasil yang tidak terduga; misalnya, pesan kartu mungkin tidak muncul.

Meskipun pesan error mungkin tidak ditampilkan di UI Chat, pesan error deskriptif dan data log tersedia untuk membantu Anda memperbaiki error jika logging error untuk aplikasi Chat diaktifkan. Untuk mendapatkan bantuan dalam melihat, men-debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.

Pembersihan

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

Perhatian: Menghapus project akan mengakibatkan:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tutorial ini, saat menghapusnya, Anda juga akan menghapus pekerjaan lain yang telah dilakukan dalam project tersebut.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang masih ingin Anda gunakan pada masa mendatang. Untuk mempertahankan URL yang menggunakan project ID tersebut, seperti URL di appspot.com, hapus resource yang dipilih di dalam project, alih-alih menghapus seluruh project.

Jika Anda berencana mempelajari beberapa tutorial dan panduan memulai, menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

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

   Buka Resource Manager

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

Topik terkait

• Membangun aplikasi Google Chat dengan agen AI ADK
• 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