Menghosting agen A2UI dengan Cloud Run

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

Contoh ini menggunakan kode contoh yang tersedia secara publik. Kode contoh untuk tutorial ini memiliki struktur folder berikut.

Struktur folder tutorial

Project ini memiliki struktur folder berikut:

File/Direktori Deskripsi
/samples/community/agent/adk/gemini_enterprise/v0_9 Direktori yang berisi contoh konfigurasi dan data untuk tutorial ini.
__init__.py Menandai direktori sebagai paket Python.
__main__.py Titik entri untuk menjalankan agen secara lokal.
agent.py Menentukan agen, kemampuannya, dan perilakunya.
agent_executor.py Mengelola alur eksekusi dan interaksi alat.
deploy.sh Skrip untuk mem-build dan men-deploy agen ke Cloud Run.
examples/ Direktori yang berisi contoh template komponen.
gemini_enterprise_composite_catalog.json Katalog komponen yang menentukan komponen Material standar dan Gemini Enterprise kustom.
main.py Titik entri aplikasi utama (aplikasi FastAPI).
prompt_builder.py Helper untuk membuat perintah untuk model.
pyproject.toml Konfigurasi dan dependensi project.
examples/0.9/material_table_orders.json Template UI contoh yang berisi tata letak dan data tiruan untuk demo pesanan terbaru.
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 ada. Untuk membuat aplikasi, lihat Membuat aplikasi.

  • Buat clone repositori dan buka direktori contoh v0_9:

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

Mengaktifkan API

Aktifkan API berikut untuk project Anda:

Konsol

Aktifkan API berikut:

  • Vertex AI 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

Mengaktifkan API

REST

Anda dapat mengaktifkan API ini dari Google Cloud konsol atau 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 Google Cloud project Anda.

Men-deploy agen

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

Skrip ini melakukan tindakan berikut:

  1. Mem-build image container dari kode sumber Anda.
  2. Mendorong image ke Artifact Registry.
  3. Men-deploy image ke Cloud Run.
  4. Menetapkan variabel lingkungan, termasuk MODEL dan AGENT_URL publik dari layanan itu sendiri.
chmod +x deploy.sh
./deploy.sh PROJECT_ID a2ui-demo-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 gemini-2.5-flash secara default.

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 di-deploy, Anda harus mendaftarkannya dengan Gemini Enterprise agar dapat ditemukan.

Jalankan perintah curl berikut, ganti 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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

Ganti kode berikut:

  • PROJECT_NUMBER: Nomor Google Cloud project 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.

Membatalkan pendaftaran agen (Opsional)

Jika ingin membatalkan pendaftaran agen, jalankan perintah curl berikut:

curl -X DELETE -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/AGENT_ID

Ganti kode berikut:

  • PROJECT_NUMBER: Nomor Google Cloud project Anda.
  • LOCATION: Multi-region penyimpanan data Anda: global, us, atau eu
  • ENGINE_ID: ID aplikasi yang digunakan untuk mendaftarkan agen.
  • AGENT_ID: ID agen yang ingin Anda hapus.

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 memperoleh dan membagikan URL aplikasi web dengan mengikuti langkah-langkah berikut:

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

    Gemini Enterprise

  2. Klik nama aplikasi yang Anda gunakan untuk 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 hal berikut:

  1. Buka URL aplikasi web di tab browser baru.
  2. Di menu navigasi aplikasi web, klik Agents.
  3. Buka bagian From your organization, 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 menggunakan perintah seperti Show me the recent orders table untuk mendapatkan informasi tentang pesanan terbaru yang merupakan bagian dari data contoh. Agen mengambil informasi pesanan dari material_table_orders.json dan merender daftar dalam chat menggunakan komponen UI kustom, seperti yang ditunjukkan dalam contoh berikut:

Contoh tabel pesanan terbaru