Mendaftarkan dan mengelola agen A2A

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Protokol Agent2Agent (A2A) adalah protokol komunikasi terbuka dan bahasa universal untuk agen. Protokol ini memungkinkan agen dari berbagai pembuat dan platform untuk saling menemukan, berkolaborasi, dan mendelegasikan tugas dengan aman. Dokumen ini menjelaskan cara administrator Gemini Enterprise dapat menghubungkan agen yang dibuat menggunakan A2A dan dihosting di platform mana pun ke Gemini Enterprise, sehingga agen tersebut tersedia bagi pengguna di aplikasi web Gemini Enterprise.

Catatan: Untuk mengamankan agen A2A, developer harus mengonfigurasi Model Armor menggunakan REST API dalam kode aplikasi agen mereka. Setelan Model Armor di konsol Google Cloud untuk Gemini Enterprise tidak otomatis melindungi agen A2A.

Sebelum memulai

Pastikan Anda memiliki:

• Peran Gemini Enterprise Admin.

• Aktifkan Discovery Engine API. Untuk mengaktifkan Discovery Engine API untuk project Google Cloud, di konsol Google Cloud , buka halaman Discovery Engine API.

  Buka Discovery Engine API

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

• Agen yang menggunakan protokol A2A.

  Gemini Enterprise mendukung mekanisme streaming A2A v0.3.

  Jika Anda menggunakan A2A v1.0.0 atau yang lebih baru, gunakan paket kompatibilitas yang disediakan oleh SDK untuk memastikan agen Anda berfungsi dengan mekanisme sebelumnya (misalnya, paket a2acompat/a2av0 untuk Go atau paket a2a.compat.v0_3 untuk Python).

  Tips: Anda harus menghosting dan mengelola agen A2A agar dapat berfungsi dalam Gemini Enterprise.

• Jika agen A2A Anda dihosting di Cloud Run, menggunakan URL .run.app default secara langsung, dan memerlukan autentikasi, berikan peran Cloud Run Invoker (roles/run.invoker) ke agen layanan Discovery Engine (ini tidak berlaku jika Cloud Run berada di belakang Apigee, load balancer, atau domain kustom):

  gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \
     --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@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.

Mengonfigurasi autentikasi dan otorisasi

Bergantung pada lingkungan hosting agen dan persyaratan keamanan, Anda dapat mengonfigurasi cara Gemini Enterprise melakukan autentikasi dengan agen, cara agen mengakses resource atas nama pengguna akhir, dan cara mengamankan endpoint agen.

Cara Gemini Enterprise melakukan autentikasi dengan agen Anda

Saat memanggil agen A2A, Gemini Enterprise dapat mengirim data autentikasi dan otorisasi di header permintaan, bergantung pada konfigurasi hosting dan keamanan Anda:

Header	Deskripsi
X-Serverless-Authorization	Autentikasi IAM service-to-service (untuk Cloud Run). Jika agen A2A Anda dihosting di Cloud Run dan URL agen Anda adalah URL .run.app default, Gemini Enterprise akan otomatis membuat token ID OIDC yang ditandatangani Google untuk agen layanan Discovery Engine ([e-mail]) dengan URL agen Anda sebagai audiens, dan melampirkannya di header X-Serverless-Authorization. Jika URL agen Anda menggunakan Apigee, load balancer, atau domain kustom, Gemini Enterprise tidak akan mengirim header ini. Saat Gemini Enterprise memanggil URL .run.app default secara langsung, infrastruktur ingress Cloud Run menggunakan header ini untuk memverifikasi bahwa agen layanan memiliki peran IAM roles/run.invoker (lihat Sebelum memulai) sebelum meneruskan permintaan ke container aplikasi Anda.
Authorization	Otorisasi OAuth 2.0 pengguna akhir (untuk konteks pengguna dan akses API). Jika Anda mengonfigurasi kredensial OAuth 2.0 untuk agen A2A (lihat Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir), Gemini Enterprise akan memperoleh token akses atau token ID OAuth 2.0 atas nama pengguna akhir yang login setelah mereka memberikan izin, dan mengirimkannya di header Authorization standar (misalnya, Bearer USER_OAUTH_TOKEN). Cloud Run meneruskan header Authorization langsung ke container Anda, sehingga kode aplikasi agen Anda dapat membaca token pengguna dan memanggil API downstream atas nama pengguna.

Catatan: Karena Cloud Run menggunakan X-Serverless-Authorization untuk autentikasi IAM tingkat layanan dan membiarkan header Authorization standar tetap utuh untuk kode container Anda, Anda dapat mengamankan agen sebagai layanan Cloud Run pribadi sekaligus menerima token OAuth pengguna akhir tanpa tabrakan header.

Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional)

Untuk agen A2A, konfigurasikan kredensial OAuth 2.0 jika agen Anda harus mengakses resourceGoogle Cloud atau melakukan operasi atas nama pengguna akhir. Untuk mengetahui informasi selengkapnya tentang cara kerja header autentikasi dan otorisasi, lihat Cara Gemini Enterprise melakukan autentikasi dengan agen Anda.

Ikuti langkah-langkah berikut untuk membuat client ID OAuth:

1. Di konsol Google Cloud , di halaman APIs & Services, buka halaman Credentials.

   Buka Kredensial

2. Pilih project Google Cloud , yang memiliki sumber data yang ingin diakses oleh agen. Misalnya, pilih project yang berisi set data BigQuery yang ingin Anda kueri oleh agen.

3. Klik Create credentials, lalu pilih OAuth client ID.

4. Di Application type, pilih aplikasi web.

5. Di bagian Authorized redirect URIs, tambahkan URI berikut:

   • https://vertexaisearch.cloud.google.com/oauth-redirect
   • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

6. Klik Create.

7. Di panel OAuth client created, klik Download JSON. JSON yang didownload mencakup Client ID, Authorization URI, Token URI, dan Client secret untuk project Google Cloud yang dipilih. Anda memerlukan detail ini untuk membuat resource otorisasi.

Mengamankan endpoint agen A2A Anda

Untuk header autentikasi yang dikirim Gemini Enterprise ke agen A2A Anda, lihat Cara Gemini Enterprise melakukan autentikasi dengan agen Anda. Saat Anda mengamankan endpoint agen, atau gateway API di depannya, pertimbangkan hal berikut:

• Skema keamanan kartu agen: Gemini Enterprise tidak menggunakan kolom securitySchemes dan security kartu agen Anda untuk melakukan autentikasi dengan agen Anda.
• Kunci API dan header kustom: Gemini Enterprise tidak mendukung skema keamanan apiKey, dan tidak menyediakan cara untuk menambahkan kunci API statis atau nilai header kustom lainnya ke permintaan yang dikirim ke agen Anda.
• Token ID agen layanan: Gemini Enterprise mengirimkan header X-Serverless-Authorization hanya jika URL agen Anda adalah URL Cloud Run default yang diakhiri dengan .run.app. Jika URL agen Anda menggunakan domain kustom, load balancer, atau gateway API, Gemini Enterprise tidak akan mengirim header ini.
• Token pengguna akhir: Jika Anda mengonfigurasi OAuth 2.0 untuk agen Anda, Gemini Enterprise akan mengirimkan token pengguna akhir dari penyedia OAuth 2.0 Anda di header Authorization.

Mengamankan endpoint agen dengan Apigee

Jika Anda mengekspos agen A2A melalui proxy API Apigee, proxy akan menerima token pengguna akhir di header Authorization, tetapi tidak menerima header X-Serverless-Authorization. Untuk mengamankan proxy, lakukan hal berikut:

1. Konfigurasikan OAuth 2.0 untuk otorisasi pengguna akhir untuk agen Anda (menggunakan Google Cloud client ID OAuth 2.0 atau penyedia OAuth 2.0 pihak ketiga), dan berikan detail OAuth 2.0 tersebut saat Anda mendaftarkan agen. Mengonfigurasi OAuth 2.0 diperlukan saat mengamankan proxy API Apigee; jangan lewati langkah otorisasi selama pendaftaran.
2. Di kartu agen, tetapkan url ke URL proxy API Apigee Anda.
3. Di proxy API, validasi token pengguna akhir di header Authorization sebelum Anda meneruskan permintaan ke agen. Pilih kebijakan Apigee berdasarkan format token yang dikeluarkan oleh penyedia OAuth 2.0 Anda:
   • Penyedia OAuth 2.0 pihak ketiga yang menerbitkan token akses JWT yang ditandatangani: Gunakan kebijakan VerifyJWT untuk memverifikasi tanda tangan token terhadap URI JSON Web Key Set (JWKS) publik penyedia Anda dan memvalidasi klaim penerbit (iss) dan audiens (aud).
   • Google OAuth 2.0 (accounts.google.com): Token akses Google OAuth 2.0 (ya29...) adalah token buram, bukan JWT yang ditandatangani. Gunakan kebijakan ServiceCallout untuk memanggil https://oauth2.googleapis.com/tokeninfo dan memverifikasi kolom audiens (aud) dan scope.

Mendaftarkan agen A2A ke Gemini Enterprise

Anda dapat mendaftarkan agen A2A ke Gemini Enterprise menggunakan konsolGoogle Cloud atau REST API. Tindakan ini akan membuat agen tersedia bagi pengguna dalam aplikasi Gemini Enterprise.

Penting: Traffic ke Agen A2A yang ditambahkan melalui metode ini tidak melewati Agent Gateway dan kebijakan Agent Gateway tidak berlaku.

Kuota pendaftaran agen dan pemberian lisensi: Mendaftarkan agen ke aplikasi akan menggunakan satu unit kuota pembuatan agen harian gabungan project Anda (discoveryengine.googleapis.com/agents_tier_enterprise_regional). Kuota ditentukan oleh jumlah lisensi Gemini Enterprise Standard (1 pembuatan per pengguna per hari, digabungkan) atau lisensi Plus (10 per pengguna per hari, digabungkan) yang didistribusikan ke project. Lisensi Frontline memberikan kuota pembuatan 0.

Jika Anda mendaftarkan agen backend di beberapa aplikasi atau mesin Gemini Enterprise dalam project yang sama, setiap panggilan API pendaftaran (agents.create) akan dihitung sebagai pembuatan agen terhadap kuota harian ini. Skrip deployment otomatis atau pipeline CI/CD yang mendaftarkan agen di banyak aplikasi dapat mengalami HTTP 429 RESOURCE_EXHAUSTED: Agent creation quota exceeded jika jumlah panggilan pendaftaran dalam sehari melebihi jumlah lisensi Standard yang didistribusikan. Pastikan project Anda memiliki lisensi Standard yang cukup yang didistribusikan sebelum menjalankan peluncuran multi-aplikasi. Untuk mengetahui detail selengkapnya, lihat Kuota pembuatan harian.

Konsol

Untuk mendaftarkan agen A2A menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:

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

   Gemini Enterprise

2. Klik nama aplikasi yang ingin Anda daftarkan dengan agen.

3. Klik Agents > Add Agents.

4. Di bagian Choose an agent type, klik Add untuk Custom agent via A2A.

5. Di kolom JSON kartu agen, masukkan detail kartu agen dalam format JSON. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A). Contoh berikut hanya menggunakan kolom wajib diisi.

   Contoh:

   {
     "protocolVersion": "0.3",
     "name": "Hello World Agent",
     "description": "Just a hello world agent",
     "url": "https://example.com/myagent",
     "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
     "version": "1.0.0",
     "capabilities": {
     },
     "skills": [
       {
         "id": "data-analysis",
         "name": "Data Analysis",
         "description": "Data analysis",
         "tags": []
       }
     ],
     "defaultInputModes": [
       "text/plain"
     ],
     "defaultOutputModes": [
       "text/plain"
     ]
   }
   

6. Klik Preview agent details > Next.

7. Selesaikan penyiapan menggunakan salah satu metode berikut:

   • Jika Anda ingin agen mengakses resource Google Cloud atas nama Anda, atau jika endpoint agen Anda memerlukan header Authorization (misalnya, saat mengamankan proxy API Apigee), ikuti langkah-langkah berikut:

     1. Masukkan Client ID, Client secret, Authorization URI, dan Token URI yang Anda buat di Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional).

     2. Masukkan Cakupan.

     3. Klik Selesai.

   • Jika Anda tidak ingin agen mengakses resource Google Cloud atas nama Anda dan endpoint agen Anda tidak memerlukan header Authorization, klik Lewati & Selesaikan.

REST

Untuk mendaftarkan agen A2A menggunakan REST API, ikuti langkah-langkah berikut:

• Menambahkan resource otorisasi ke Gemini Enterprise (opsional)
• Mendaftarkan agen A2A Anda

Menambahkan resource otorisasi ke Gemini Enterprise (opsional)

Jika agen harus mengakses resource Google Cloud atas nama pengguna, jalankan perintah berikut untuk mendaftarkan resource otorisasi yang Anda buat di bagian Mengonfigurasi detail otorisasi (opsional) dengan Gemini Enterprise:

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

Ganti kode berikut:

• PROJECT_ID: ID project Anda.
• PROJECT_NUMBER: nomor project Google Cloud Anda.
• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• LOCATION: multi-region penyimpanan data Anda: global, us, atau eu
• AUTH_ID: ID resource otorisasi. Ini adalah ID alfanumerik arbitrer yang Anda tentukan. Anda harus merujuk ID ini nanti saat mendaftarkan Agen yang memerlukan dukungan OAuth.
• OAUTH_CLIENT_ID: ID klien OAuth 2.0 yang Anda peroleh saat membuat kredensial OAuth.
• OAUTH_CLIENT_SECRET: rahasia klien OAuth 2.0 yang Anda peroleh saat membuat kredensial OAuth.

• OAUTH_AUTH_URI: URI Otorisasi. Untuk mengizinkan aplikasi Anda, buat URI Otorisasi tertentu menggunakan detail dari file JSON kredensial OAuth Anda. Salin template berikut, dan ganti placeholder dengan nilai spesifik Anda.

  https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  

  • YOUR_CUSTOM_SCOPES: Anda dapat menambahkan cakupan yang diperlukan. Misalnya, string cakupan OAuth berikut meminta akses hanya baca ke Google Drive dan Google Dokumen Anda.

    scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
    

• OAUTH_TOKEN_URI: URI token yang Anda peroleh saat membuat kredensial OAuth.

Informasi selengkapnya tentang parameter URI Otorisasi.

Untuk membantu memastikan URI berfungsi dengan benar, verifikasi kolom berikut:

Parameter	Nilai atau tindakan
client_id	Ganti dengan client_id yang ditemukan di JSON yang Anda download.
redirect_uri	Jangan ubah. Harus berupa https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope	Cantumkan cakupan Google API yang perlu diakses aplikasi Anda atas nama pengguna. Misalnya, untuk memberikan akses ke BigQuery, gunakan cakupan https://www.googleapis.com/auth/bigquery dan untuk akses hanya baca ke Google Dokumen, gunakan https://www.googleapis.com/auth/documents.readonly. Jika Anda menggunakan beberapa cakupan, pisahkan dengan spasi, yang menjadi %20 di URL. Catatan: Jika agen A2A Anda dihosting di Agent Runtime di Gemini Enterprise Agent Platform, Anda harus membuat otorisasi dengan cakupan cloud-platform. Misalnya, &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform. Untuk mengetahui informasi selengkapnya, lihat Menggunakan agen Agent2Agent.
include_granted_scopes	Harus berupa true.
response_type	Harus berusia code tahun untuk menerima kode otorisasi.
access_type	Tetapkan ke offline untuk membantu memastikan bahwa Anda menerima token refresh.
prompt	Setel ke consent untuk membantu memastikan bahwa pengguna selalu ditampilkan layar izin.

Mendaftarkan agen A2A Anda

Untuk membuat dan mendaftarkan agen ke Gemini Enterprise, gunakan metode agents.create. Perintah berikut hanya menggunakan kolom yang wajib diisi. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A).

Jalankan perintah ini untuk mendaftarkan agen A2A Anda ke Gemini Enterprise:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Ganti kode berikut:

• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• LOCATION: multi-region penyimpanan data Anda: global, us, atau eu
• PROJECT_ID: ID project Anda.
• APP_ID: ID aplikasi yang ingin Anda daftarkan ke agen.
• AGENT_NAME: ID unik untuk agen.
• AGENT_DISPLAY_NAME: nama agen yang ditampilkan di aplikasi web.
• AGENT_DESCRIPTION: deskripsi tentang hal yang dapat dilakukan agen.
• PROTOCOLVERSION: versi protokol A2A yang didukung agen. Untuk mengetahui informasi selengkapnya tentang versi yang didukung, lihat catatan rilis A2A.
• AGENT_URL: URL endpoint agen.
• AGENT_VERSION: versi agen.
• INPUT_MODE: jenis media input default. Misalnya, application/json atau text/plain.
• OUTPUT_MODE: jenis media output default. Misalnya, text/plain" atau image/png.
• CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya \"streaming\": true atau \"pushNotifications\": false.
• SKILLS: daftar objek AgentSkill yang ditawarkan agen.
• authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolom authorization_config ke resource JSON Anda.
  • AUTH_ID: nilai yang Anda gunakan untuk AUTH_ID di bagian Menambahkan resource otorisasi ke Gemini Enterprise.

Contoh perintah dan hasil

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{},\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

Mencantumkan agen yang terhubung ke aplikasi

Contoh kode berikut menunjukkan cara mendapatkan detail semua agen yang terhubung ke aplikasi Anda:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Ganti variabel dengan nilai:

• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: multi-region aplikasi Anda: global, us, atau eu.
• APP_ID: ID aplikasi Gemini Enterprise Anda.

Jika agen Anda tidak dibuat otomatis oleh Google, respons akan menyertakan kolom name di beberapa baris pertama. Nilai kolom ini berisi ID Agen di akhir jalur. Misalnya, dalam respons berikut, ID Agen adalah 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Contoh perintah dan hasil

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

Melihat detail agen A2A

Contoh kode berikut menunjukkan cara mengambil detail agen yang terdaftar di Gemini Enterprise:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Ganti variabel dengan nilai:

• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: multi-region aplikasi Anda: global, us, atau eu.
• APP_ID: ID aplikasi Gemini Enterprise Anda.
• AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Contoh perintah dan hasil

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

Mengupdate agen A2A

Anda dapat mengubah detail agen A2A yang ada yang terdaftar di Gemini Enterprise menggunakan konsol Google Cloud atau REST API.

Konsol

Untuk mengupdate agen A2A menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:

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

   Gemini Enterprise

2. Klik nama aplikasi yang menyertakan agen yang ingin Anda update.

3. Klik Agents.

4. Klik nama agen A2A (Custom) yang akan diperbarui, lalu klik Edit.

5. Di kolom Agent card JSON, perbarui detail kartu agen dalam format JSON. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A). Contoh berikut hanya menggunakan kolom wajib diisi.

   Contoh:

   {
     "protocolVersion": "0.3",
     "name": "Hello World Agent",
     "description": "Just a hello world agent",
     "url": "https://example.com/myagent",
     "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
     "version": "1.1.0",
     "capabilities": {
     },
     "skills": [
       {
         "id": "data-analysis",
         "name": "Data Analysis",
         "description": "Data analysis",
         "tags": []
       }
     ],
     "defaultInputModes": [
       "text/plain"
     ],
     "defaultOutputModes": [
       "text/plain"
     ]
   }
   

6. Klik Simpan.

REST

Untuk memperbarui detail agen A2A yang terdaftar di Gemini Enterprise, gunakan metode agents.patch. Perintah berikut hanya menggunakan kolom yang wajib diisi. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A).

Jalankan perintah ini untuk mengupdate agen A2A Anda dengan Gemini Enterprise:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Ganti kode berikut:

• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• LOCATION: multi-region penyimpanan data Anda: global, us, atau eu.
• PROJECT_ID: ID project Anda.
• APP_ID: ID aplikasi yang ingin Anda daftarkan ke agen.
• AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.
• AGENT_NAME: ID unik untuk agen.
• AGENT_DISPLAY_NAME: nama agen yang ditampilkan di aplikasi web.
• AGENT_DESCRIPTION: deskripsi tentang hal yang dapat dilakukan agen.
• PROTOCOLVERSION: versi protokol A2A yang didukung agen. Untuk mengetahui informasi selengkapnya tentang versi yang didukung, lihat catatan rilis A2A.
• AGENT_URL: URL endpoint agen.
• AGENT_VERSION: versi agen.
• INPUT_MODE: jenis media input default. Misalnya, application/json atau text/plain.
• OUTPUT_MODE: jenis media output default. Misalnya, text/plain atau image/png.
• CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya \"streaming\": true atau \"pushNotifications\": false.
• SKILLS: daftar objek AgentSkill yang ditawarkan agen.
• authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolom authorization_config ke resource JSON Anda.
  • AUTH_ID: nilai yang Anda gunakan untuk AUTH_ID di bagian Menambahkan resource otorisasi ke Gemini Enterprise.

Contoh perintah dan hasil

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890 \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.1.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{  },\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }P
}

Menghapus agen A2A

Contoh kode berikut menunjukkan cara menghapus agen yang terhubung ke aplikasi Anda:

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Ganti variabel dengan nilai:

• ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
  • us untuk multi-region AS
  • eu untuk multi-region Uni Eropa
  • global untuk lokasi Global
  Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: multi-region aplikasi Anda: global, us, atau eu
• APP_ID: ID aplikasi Gemini Enterprise Anda.
• AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Contoh perintah dan hasil

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

Langkah berikutnya

• Gunakan agen yang Anda daftarkan ke Gemini Enterprise di aplikasi web.