Protokol Agent2Agent (A2A) adalah protokol komunikasi terbuka dan bahasa universal untuk agen. Protokol ini memungkinkan agen dari berbagai builder 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.
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.
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/a2av0untuk Go atau paketa2a.compat.v0_3untuk Python).Jika agen A2A Anda dihosting di Cloud Run, menggunakan URL
.run.appdefault 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: jumlah project Google Cloud Anda.
Mengonfigurasi autentikasi dan otorisasi
Bergantung pada lingkungan hosting agen dan persyaratan keamanan Anda, Anda dapat mengonfigurasi cara Gemini Enterprise melakukan autentikasi dengan agen Anda, cara agen Anda mengakses resource dan alat downstream atas nama pengguna akhir, dan cara mengamankan endpoint agen Anda:
- Cara Gemini Enterprise melakukan autentikasi dengan agen Anda: Pelajari cara Gemini Enterprise mengirim header IAM layanan ke layanan dan OAuth 2.0 pengguna akhir saat memanggil endpoint agen A2A Anda.
- Konfigurasikan OAuth 2.0 untuk otorisasi pengguna akhir:
Konfigurasikan resource otorisasi OAuth 2.0 di Gemini Enterprise agar
Gemini Enterprise memperoleh token pengguna akhir dan mengirimkannya di
header
Authorizationsaat memanggil agen Anda (misalnya, untuk memanggil agen A2A yang dihosting di Agent Runtime di Gemini Enterprise Agent Platform atau meneruskan token pengguna langsung ke container agen Anda). - Mengonfigurasi 3-legged OAuth dengan pengelola autentikasi Agent Identity: Konfigurasikan penyedia autentikasi 3-legged OAuth (3LO) di pengelola autentikasi Agent Identity agar agen A2A Anda dapat meminta token yang didelegasikan pengguna sesuai permintaan untuk alat tertentu, seperti server Model Context Protocol (MCP) atau API pihak ketiga.
Cara Gemini Enterprise melakukan autentikasi dengan agen Anda
Saat Gemini Enterprise 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 Saat Gemini Enterprise memanggil URL |
Authorization |
Otorisasi OAuth 2.0 pengguna akhir (untuk pemanggilan endpoint, 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 Untuk agen yang dihosting di Cloud Run, Cloud Run meneruskan header |
Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional)
Untuk agen A2A, konfigurasikan kredensial OAuth 2.0 di Gemini Enterprise jika endpoint agen Anda memerlukan token OAuth 2.0 pengguna akhir di header Authorization (misalnya, untuk memanggil agen A2A yang dihosting di Agent Runtime atau untuk meneruskan token pengguna langsung ke container agen Anda). Untuk mengetahui informasi selengkapnya tentang cara kerja header autentikasi dan
otorisasi, lihat
Cara Gemini Enterprise melakukan autentikasi dengan agen Anda.
Jika agen A2A Anda menggunakan pengelola autentikasi Agent Identity untuk OAuth 3-legged tingkat alat (misalnya, untuk mengakses server MCP atau API pihak ketiga atas nama pengguna), lihat Mengonfigurasi OAuth 3-legged dengan pengelola autentikasi Agent Identity.
Ikuti langkah-langkah berikut untuk membuat client ID OAuth:
Di konsol Google Cloud , di halaman APIs & Services, buka halaman Credentials.
-
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.
Klik Create credentials, lalu pilih OAuth client ID.
Di Application type, pilih aplikasi web.
Di bagian Authorized redirect URIs, tambahkan URI berikut:
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
Klik Create.
Di panel OAuth client created, klik Download JSON. JSON yang didownload mencakup
Client ID,Authorization URI,Token URI, danClient secretuntuk project Google Cloud yang dipilih. Anda memerlukan detail ini untuk membuat resource otorisasi.
Mengonfigurasi 3-legged OAuth dengan pengelola autentikasi Agent Identity (opsional)
Jika agen A2A Anda dibuat dengan Agent Development Kit (ADK) dan menggunakan pengelola autentikasi Agent Identity untuk OAuth 3-legged (3LO), agen Anda dapat melakukan autentikasi ke server MCP, Google Cloud layanan, atau API pihak ketiga downstream atas nama pengguna yang login.
Jika alat di agen A2A Anda memerlukan izin pengguna, Gemini Enterprise akan otomatis mengelola alur kerja 3LO sisi klien:
- Dialog izin: Saat agen Anda menampilkan interupsi alat
adk_request_credential(TASK_STATE_AUTH_REQUIRED), aplikasi web Gemini Enterprise akan meminta pengguna untuk login dan membuka URI otorisasi dari penyedia autentikasi. - Validasi pengguna dan penyimpanan token: Setelah pengguna memberikan izin, penyedia autentikasi akan mengalihkan ke endpoint validasi Gemini Enterprise
(
https://vertexaisearch.cloud.google.com/validateUserId). Gemini Enterprise memvalidasi status sesi dan menyelesaikan kredensial dengan pengelola autentikasi Agent Identity. - Melanjutkan percakapan: Gemini Enterprise mengirimkan respons
adk_request_credentialyang telah selesai kembali ke agen A2A Anda, yang mengambil token akses pengguna dari penyedia autentikasi dan memanggil alat.
Karena Gemini Enterprise menangani perintah izin, endpoint validasi, dan melanjutkan percakapan, Anda tidak perlu mengimplementasikan aplikasi UI sisi klien kustom.
Langkah 1: Siapkan penyedia autentikasi OAuth 3-legged
Ikuti langkah-langkah di
Melakukan autentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi
untuk mengaktifkan Agent Identity API (agentidentity.googleapis.com),
mengonfigurasi aplikasi klien OAuth, dan membuat penyedia autentikasi
3-legged OAuth.
Saat mengonfigurasi klien OAuth dan penyedia autentikasi untuk digunakan dengan Gemini Enterprise, sertakan setelan berikut:
Authorized redirect URIs: Dalam konfigurasi klien OAuth, tambahkan URI pengalihan callback penyedia autentikasi:
https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallbackJika Anda menggunakan kembali klien OAuth yang sama untuk resource otorisasi agen Gemini Enterprise (misalnya, untuk mengizinkan Gemini Enterprise memanggil agen A2A yang dihosting di Agent Runtime), sertakan juga URI pengalihan Gemini Enterprise (
https://vertexaisearch.cloud.google.com/oauth-redirect).Continue URI: Tetapkan URI lanjutkan (sebagai Default continue URI di penyedia autentikasi atau sebagai
continue_uridalam kode agen Anda) ke endpoint validasi Gemini Enterprise:https://vertexaisearch.cloud.google.com/validateUserId
Langkah 2: Konfigurasikan kode agen A2A Anda
Saat membangun agen ADK dan menggabungkannya dengan A2aAgent untuk
deployment di Agent Runtime, pastikan
kode agen Anda memenuhi persyaratan berikut:
- Instal versi paket yang diperlukan: Sertakan
a2a-sdk[http-server]>=1.0.0,google-cloud-aiplatform[agent_engines,adk]>=1.156.0, dangoogle-adk[a2a,agent-identity,mcp]>2.7.1dalam persyaratan deployment Anda. - Tetapkan
continue_urike Gemini Enterprise: Tetapkancontinue_urike"https://vertexaisearch.cloud.google.com/validateUserId"diGcpAuthProviderSchemeatauAgentRegistry.get_mcp_toolset(kecuali jika Anda mengonfigurasinya sebagai URI lanjutkan default di penyedia autentikasi). - Daftarkan
GcpAuthProviderdi dalam fungsi runner builder: PanggilCredentialManager.register_auth_provider(GcpAuthProvider())di dalam fungsi yang membangunRunnerdalam proses worker container yang di-deploy, bukan hanya di tingkat teratas modul. - Gunakan
A2aAgentExecutorbawaan: TeruskanA2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) keA2aAgent. Jangan gunakanAgentExecutorkustom yang hanya memeriksaevent.is_final_response(), karenaA2aAgentExecutordiperlukan untuk mengonversi interupsiadk_request_credentialmenjadi status tugas A2ATASK_STATE_AUTH_REQUIRED. - Sertakan protokol A2A versi
0.3diAgentCard: TambahkanAgentInterfacedenganprotocol_version=PROTOCOL_VERSION_0_3danprotocol_binding=TransportProtocol.HTTP_JSONkeagent_card.supported_interfacesbersama antarmuka1.0default agar Gemini Enterprise dapat berkomunikasi dengan agen Anda melalui rute A2A v0.3.
ADK + A2A
Contoh berikut mengonfigurasi agen A2A ADK yang
menggunakan GcpAuthProviderScheme dengan McpToolset (atau
AgentRegistry.get_mcp_toolset) untuk melakukan autentikasi ke server MCP
atas nama pengguna:
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) mcp_tools = McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://YOUR_MCP_SERVER_URL" ), auth_scheme=auth_scheme, ) # Alternatively, if your MCP server is registered in Agent Registry # with an outbound auth provider binding, use AgentRegistry.get_mcp_toolset: # from google.adk.integrations.agent_registry import AgentRegistry # registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION") # mcp_tools = registry.get_mcp_toolset( # mcp_server_name="projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_ID", # continue_uri=CONTINUE_URI, # ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[mcp_tools], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
ADK + A2A
Contoh berikut mengonfigurasi agen A2A ADK yang
menggunakan AuthenticatedFunctionTool dengan
GcpAuthProviderScheme untuk memanggil REST API pihak ketiga atau Google Cloud
atas nama pengguna:
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_tool import AuthConfig from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool import httpx from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) ) async def call_external_api(credential: AuthCredential, query: str) -> str: """Calls an external API using the end user's OAuth token.""" token = None if credential and credential.http and credential.http.credentials: token = credential.http.credentials.token if not token: return "Error: No authentication token available." async with httpx.AsyncClient() as client: response = await client.get( "https://YOUR_API_ENDPOINT", headers={"Authorization": f"Bearer {token}"}, params={"q": query}, ) response.raise_for_status() return response.text authenticated_tool = AuthenticatedFunctionTool( func=call_external_api, auth_config=auth_config, ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[authenticated_tool], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
Langkah 3: Deploy agen A2A dengan Identitas Agen dan berikan akses
Deploy
A2aAgentAnda ke Agent Runtime denganidentity_type=types.IdentityType.AGENT_IDENTITY:import vertexai from vertexai import types client = vertexai.Client( project="<var>PROJECT_ID</var>", location="<var>LOCATION</var>", http_options=dict(api_version="v1beta1"), ) remote_a2a_agent = client.agent_engines.create( agent=a2a_agent, config={ "display_name": "<var>AGENT_DISPLAY_NAME</var>", "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": [ "a2a-sdk[http-server]>=1.0.0", "google-cloud-aiplatform[agent_engines,adk]>=1.156.0", "google-adk[a2a,agent-identity,mcp]>2.7.1", "google-genai", "httpx", ], }, )Setelah deployment selesai, berikan peran Agent Identity User (
roles/agentidentity.user) di penyedia autentikasi ke akun utama SPIFFE agen yang di-deploy:gcloud agent-identity auth-providers add-iam-policy-binding <var>AUTH_PROVIDER_NAME</var> \ --project="<var>PROJECT_ID</var>" \ --location="<var>LOCATION</var>" \ --role="roles/agentidentity.user" \ --member="principal://agents.global.org-<var>ORGANIZATION_ID</var>.system.id.goog/resources/aiplatform/projects/<var>PROJECT_NUMBER</var>/locations/<var>LOCATION</var>/reasoningEngines/<var>ENGINE_ID</var>"Ganti kode berikut:
AUTH_PROVIDER_NAME: nama penyedia autentikasi Anda.PROJECT_ID: ID project Anda.LOCATION: region tempat penyedia autentikasi dan agen Anda di-deploy (misalnya,us-central1).ORGANIZATION_ID: ID organisasi Google Cloud Anda.PROJECT_NUMBER: jumlah project Google Cloud Anda.ENGINE_ID: ID resource agenreasoningEnginesyang di-deploy.
Daftarkan agen A2A yang di-deploy ke Gemini Enterprise menggunakan Daftarkan agen A2A ke Gemini Enterprise (Agen kustom melalui A2A) atau Impor agen A2A dari Agent Registry (Agen kustom melalui Agent Runtime). Karena agen dihosting di Agent Runtime, konfigurasikan resource otorisasi OAuth 2.0 di Gemini Enterprise dengan cakupan
https://www.googleapis.com/auth/cloud-platformagar Gemini Enterprise dapat memanggil endpoint Agent Runtime.
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
securitySchemesdansecuritykartu 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-Authorizationhanya 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:
- 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.
- Di kartu agen, tetapkan
urlke URL proxy API Apigee Anda. - Di proxy API, validasi token pengguna akhir di header
Authorizationsebelum 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 memanggilhttps://oauth2.googleapis.com/tokeninfodan memverifikasi kolom audiens (aud) danscope.
- 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 (
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.
Konsol
Untuk mendaftarkan agen A2A menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Gemini Enterprise.
Klik nama aplikasi yang ingin Anda daftarkan dengan agen.
Klik Agents > Add Agents.
Di bagian Choose an agent type, klik Add untuk Custom agent via A2A.
Di kolom Agent card JSON, 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" ] }Klik Pratinjau detail agen > Berikutnya.
Selesaikan penyiapan menggunakan salah satu metode berikut:
- Jika Anda tidak ingin agen mengakses resource Google Cloud atas nama Anda dan endpoint agen Anda tidak memerlukan header
Authorization, klik Skip & Finish untuk melewati langkah ini. - Jika Anda telah mengonfigurasi 3LO dengan pengelola autentikasi, klik Skip & Finish dan agen akan meminta akses secara dinamis.
Jika Anda belum mengonfigurasi 3LO dengan pengelola autentikasi atau endpoint agen Anda memerlukan header
Authorization(misalnya, saat mengamankan proxy API Apigee), ikuti langkah-langkah berikut:Masukkan Client ID, Client secret, Authorization URI, dan Token URI yang Anda buat di Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional).
Masukkan Cakupan.
Klik Selesai.
- Jika Anda tidak ingin agen mengakses resource Google Cloud atas nama Anda dan endpoint agen Anda tidak memerlukan header
REST
Untuk mendaftarkan agen A2A menggunakan REST API, ikuti langkah-langkah berikut:
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: jumlah project Google Cloud Anda.ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
LOCATION: multi-region penyimpanan data Anda:global,us, ataueuAUTH_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 Jika Anda menggunakan beberapa cakupan, pisahkan
dengan spasi, yang menjadi |
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 |
Tetapkan ke consent untuk membantu memastikan bahwa pengguna
selalu melihat 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:usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
LOCATION: multi-region penyimpanan data Anda:global,us, ataueuPROJECT_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/jsonatautext/plain.OUTPUT_MODE: jenis media output default. Misalnya,text/plain"atauimage/png.CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya\"streaming\": trueatau\"pushNotifications\": false.SKILLS: daftar objekAgentSkillyang ditawarkan agen.authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolomauthorization_configke resource JSON Anda.AUTH_ID: nilai yang Anda gunakan untuk AUTH_ID di bagian Menambahkan resource otorisasi ke Gemini Enterprise.
Menampilkan informasi penulis dan kontak untuk agen (opsional)
Secara default, agen A2A yang Anda daftarkan tidak menampilkan penulis di Gemini Enterprise. Untuk menampilkan siapa yang membuat agen dan siapa yang dapat dihubungi pengguna
tentang agen tersebut, tambahkan ekstensi metadata agen ke kolom capabilities.extensions
JSON kartu agen yang Anda gunakan untuk
mendaftarkan atau memperbarui agen:
{
"capabilities": {
"extensions": [
{
"uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
"params": {
"authorName": "Example Team",
"contactEmail": "agent-support@example.com"
}
}
]
}
}
Pertahankan kolom kartu agen lainnya dari
contoh pendaftaran bersama dengan capabilities. Di REST API, ekstensi adalah bagian dari string jsonAgentCard yang di-escape.
Kolom params mendukung nilai berikut. Keduanya bersifat opsional.
| Parameter | Deskripsi |
|---|---|
authorName |
Nama orang, tim, atau perusahaan yang membuat agen. Galeri agen menampilkannya sebagai Oleh AUTHOR_NAME di kartu agen, dan dialog Info Agen menampilkannya sebagai Penulis. Galeri hanya menampilkan nama ini jika agen tidak memiliki nama pemiliknya sendiri. Nama yang berisi kata "Google" tidak ditampilkan, agar tidak disalahartikan sebagai agen yang dibuat oleh Google. |
contactEmail |
Alamat email yang dapat digunakan pengguna untuk menghubungi penulis. Dialog Agent Info menampilkannya sebagai Contact. |
Setiap nilai harus berupa string maksimal 256 karakter, dan contactEmail harus berupa alamat email yang valid. Gemini Enterprise mengabaikan nilai yang tidak memenuhi
persyaratan ini. Gemini Enterprise tidak memverifikasi nama penulis atau
email kontak.
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:
usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
- PROJECT_ID: ID project Google Cloud Anda.
- LOCATION: multi-region aplikasi Anda:
global,us, ataueu. - APP_ID: ID aplikasi Gemini Enterprise Anda.
Jika agen Anda tidak dibuat otomatis oleh Google, responsnya 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",
...
}
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:
usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
- PROJECT_ID: ID project Google Cloud Anda.
- LOCATION: multi-region aplikasi Anda:
global,us, ataueu. - APP_ID: ID aplikasi Gemini Enterprise Anda.
- AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.
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:
Di konsol Google Cloud , buka halaman Gemini Enterprise.
Klik nama aplikasi yang menyertakan agen yang ingin Anda perbarui.
Klik Agents.
Klik nama agen A2A (Custom) yang akan diupdate, lalu klik Edit.
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" ] }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:usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
LOCATION: multi-region penyimpanan data Anda:global,us, ataueu.PROJECT_ID: ID project Anda.APP_ID: ID aplikasi tempat Anda ingin mendaftarkan 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/jsonatautext/plain.OUTPUT_MODE: jenis media output default. Misalnya,text/plainatauimage/png.CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya\"streaming\": trueatau\"pushNotifications\": false.SKILLS: daftar objekAgentSkillyang ditawarkan agen.authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolomauthorization_configke resource JSON Anda.AUTH_ID: nilai yang Anda gunakan untuk AUTH_ID di bagian Menambahkan resource otorisasi ke Gemini Enterprise.
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:
usuntuk multi-region ASeuuntuk multi-region Uni Eropaglobaluntuk lokasi Global
- PROJECT_ID: ID project Google Cloud Anda.
- LOCATION: multi-region aplikasi Anda:
global,us, ataueu - APP_ID: ID aplikasi Gemini Enterprise Anda.
- AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.
Langkah berikutnya
- Gunakan agen yang Anda daftarkan ke Gemini Enterprise di aplikasi web.