Menghosting agen A2UI dengan Cloud Run

Tutorial ini menjelaskan cara men-deploy agen Agent-to-Agent (A2A), yang dibangun dengan Google Agent Development Kit (ADK) dan ekstensi A2UI, ke Cloud Run. Anda juga akan mempelajari cara mendaftarkan agen yang di-deploy ke Gemini Enterprise.

Contoh kode untuk tutorial ini memiliki struktur folder berikut.

Struktur folder tutorial

Project memiliki struktur folder berikut:

File/Direktori Deskripsi
examples/0.8/ Direktori yang berisi contoh konfigurasi atau data.
__init__.py Menandai direktori sebagai paket Python.
agent.py Menentukan agen, keterampilan, dan perilakunya.
agent_executor.py Mengelola alur eksekusi dan interaksi alat.
contact_data.json Contoh data yang digunakan oleh agen (misalnya, kontak tiruan).
deploy.sh Skrip untuk membangun dan men-deploy agen ke Cloud Run.
main.py Titik entri aplikasi utama (aplikasi FastAPI).
prompt_builder.py Helper untuk membuat perintah bagi model.
pyproject.toml Konfigurasi dan dependensi project.
tools.py Menentukan alat (fungsi) yang dapat digunakan agen.

Sebelum memulai

Sebelum memulai, pastikan Anda memiliki hal-hal berikut:

  • Peran Admin Discovery Engine.

  • Aplikasi Gemini Enterprise yang sudah ada. Untuk membuat aplikasi, lihat Membuat aplikasi.

  • Buat clone repositori dan buka direktori contoh cloud_run:

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Mengaktifkan API

Aktifkan API berikut untuk project Anda:

Konsol

Mengaktifkan API berikut:

  • Agent Platform API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • Identity and Access Management (IAM) API

Aktifkan API

REST

Anda dapat mengaktifkan API ini dari konsol Google Cloud atau dengan menggunakan perintah gcloud CLI berikut:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Memberikan izin

Berikan izin ke peran Cloud Run Invoker (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Ganti kode berikut:

  • PROJECT_ID : ID project Anda.
  • PROJECT_NUMBER: Nomor project Google Cloud Anda.

Men-deploy agen

Skrip deploy.sh mengotomatiskan proses deployment. Untuk men-deploy agen, jalankan skrip dari direktori project dengan ID Google Cloud dan nama untuk layanan baru Anda. Anda juga dapat secara opsional menentukan model Gemini yang akan digunakan.

Skrip akan melakukan tindakan berikut:

  1. Membangun image container dari kode sumber Anda.
  2. Mengirim image ke Artifact Registry.
  3. Men-deploy image ke Cloud Run.
  4. Menetapkan variabel lingkungan, termasuk MODEL dan AGENT_URL publik layanan itu sendiri.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Ganti kode berikut:

  • PROJECT_ID: ID project Anda.
  • MODEL_NAME: Opsional. Ini adalah argumen ketiga untuk skrip. Nilai yang didukung adalah gemini-2.5-pro dan gemini-2.5-flash. Jika tidak diberikan, skrip akan menggunakan nilai default gemini-2.5-flash.

Setelah skrip selesai, skrip akan mencetak URL layanan agen yang di-deploy. Anda memerlukan URL Layanan ini di langkah berikutnya.

Mendaftarkan agen dengan Gemini Enterprise

Setelah agen Anda di-deploy, Anda harus mendaftarkannya ke Gemini Enterprise agar dapat ditemukan.

Jalankan perintah curl berikut, dengan mengganti placeholder dengan nilai Anda sendiri:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Ganti kode berikut:

  • PROJECT_NUMBER: Nomor project Google Cloud Anda.
  • LOCATION: Multi-region penyimpanan data Anda: global, us, atau eu
  • ENGINE_ID: ID aplikasi yang ingin Anda gunakan untuk mendaftarkan agen.
  • AGENT_URL: URL layanan agen yang di-deploy.

Menggunakan agen di aplikasi web Gemini Enterprise

Setelah agen dibuat dan didaftarkan, Anda dapat mulai menggunakan dan berinteraksi dengannya di aplikasi web Gemini Enterprise.

Mendapatkan URL aplikasi web

Untuk menggunakan agen, Anda harus mendapatkan URL aplikasi web terlebih dahulu. Administrator Gemini Enterprise dapat mendapatkan dan membagikan URL aplikasi web dengan mengikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Gemini Enterprise

  2. Klik nama aplikasi tempat Anda mendaftarkan agen.

  3. Klik Integrations.

  4. Salin Link ke aplikasi web Anda: dan bagikan kepada pengguna di organisasi.

Menggunakan agen

Untuk menggunakan dan berinteraksi dengan agen, lakukan langkah-langkah berikut:

  1. Buka URL aplikasi web di tab browser baru.
  2. Di menu navigasi aplikasi web, klik Agen.
  3. Buka bagian Dari organisasi Anda, lalu klik agen yang Anda buat.
  4. Tindakan ini akan membuka antarmuka percakapan untuk agen. Mulai ajukan pertanyaan dan berinteraksi dengan agen.

Misalnya, Anda dapat meminta agen untuk mencantumkan semua kontak. Agen menggunakan alat list_contacts untuk mengambil kontak dari contact_data.json dan merender daftar dalam chat menggunakan elemen UI kustom, seperti yang ditunjukkan dalam contoh berikut:

Contoh Agen Kontak