Dalam sistem multi-agen, agen orchestrator mendelegasikan tugas ke agen dan alat target khusus. Agen target tersebut menjadi sub-agen dari sistem atau aplikasi multi-agen.
Dengan Agent Registry, agen orchestrator Anda dapat mencari endpoint Agent2Agent (A2A) dan Model Context Protocol (MCP) secara dinamis saat runtime tanpa melakukan hardcoding URL layanan dalam kode aplikasi Anda. Anda dapat mengambil
agen terdaftar dan
server MCP untuk membangun agen orchestrator
menggunakan klien AgentRegistry di
Agent Development Kit (ADK) atau library
HTTP dan google-auth standar.
Saat agen orchestrator memanggil endpoint agen target, agen tersebut akan mengirimkan permintaan langsung ke Agent Runtime agen target atau server MCP. Untuk menerapkan kebijakan keamanan, melakukan mediasi protokol, dan menerapkan pemfilteran konten pada endpoint agen target, Anda dapat merutekan panggilan agen melalui Agent Gateway.
Sebelum memulai
Sebelum Anda mencari URL endpoint agen target atau memanggil agen A2A melalui Agent Registry, selesaikan langkah-langkah berikut:
- Menyiapkan Agent Registry.
Untuk penyiapan project tunggal, dapatkan project ID dari project tata kelola tempat Agent Registry diaktifkan. Jika Anda mengonfigurasi batas pengelolaan untuk beberapa project, gunakan ID project pengelolaan Anda untuk penemuan dan pendaftaran di seluruh batas, atau tentukan ID project anggota untuk operasi project tunggal.
Instal dependensi klien untuk framework Anda:
ADK (pip)
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"Anda harus menginstal setidaknya
google-adk>=1.29.0.ADK (uv)
uv add "google-adk[a2a,agent-identity,mcp]"Anda harus menginstal setidaknya
google-adk>=1.29.0.Python non-ADK
pip install --upgrade google-auth requests httpxKonfigurasi Kredensial Default Aplikasi (ADC) untuk pengembangan lokal. Jika tidak, lampirkan akun layanan atau konfigurasi kredensial Workload Identity Federation di lingkungan eksternal:
gcloud auth application-default loginSiapkan variabel lingkungan berikut:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATIONGanti kode berikut:
PROJECT_ID: project ID dari project tata kelola Anda.LOCATION: lokasi Agent Registry tempat agen dan server MCP Anda terdaftar, sepertiglobalatauus-central1.
Peran yang diperlukan
Anda dapat menggunakan akun pengguna untuk pengembangan lokal, atau menggunakan akun layanan atau akun utama agen untuk agen orchestrator Anda guna menemukan komponen terdaftar dan memanggil agen A2A target. Akun pengguna, akun layanan, atau entitas agen harus memiliki peran yang sesuai untuk menemukan komponen dan memanggil agen A2A target.
Untuk memastikan akun pengguna, akun layanan, atau akun utama agen Anda memiliki izin yang diperlukan untuk menemukan komponen terdaftar dan memanggil agen A2A target, minta administrator untuk memberikan peran IAM berikut ke akun pengguna, akun layanan, atau akun utama agen Anda di project tata kelola tempat Registry Agen diaktifkan:
-
Untuk menemukan agen dan server MCP yang terdaftar:
Agent Registry API Viewer (
roles/agentregistry.viewer) -
Untuk memanggil agen A2A target saat runtime:
Peran runtime atau gateway untuk layanan yang menghosting agen target, yang diperlukan untuk memanggil agen tersebut. Misalnya, jika agen target berjalan di Cloud Run, akun atau akun utama harus memiliki peran Cloud Run Invoker (
roles/run.invoker).
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Administrator Anda mungkin juga dapat memberikan izin yang diperlukan kepada akun pengguna, akun layanan, atau akun utama agen Anda melalui peran khusus atau peran bawaan lainnya.
Memilih kredensial untuk endpoint agen A2A target
Mencari komponen di Agent Registry dan memanggil endpoint agen A2A targetnya memerlukan token autentikasi terpisah. Saat agen orchestrator Anda memanggil endpoint agen A2A target, agen tersebut harus melampirkan jenis token pemilik yang diharapkan oleh endpoint tersebut:
| Endpoint agen A2A target | Token pemilik yang diperlukan | Sumber dan panduan kredensial |
|---|---|---|
Endpoint agen APIGoogle Cloud
(https://*.googleapis.com) |
Token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/cloud-platform atau cakupan layanan yang lebih sempit. Saat menggunakan Kredensial Default Aplikasi (ADC) yang tidak memiliki project kuota default yang dikonfigurasi, sertakan header X-Goog-User-Project untuk menentukan project yang ditagih untuk kuota API. Untuk mengetahui detailnya, lihat
Menetapkan project kuota dengan permintaan REST. |
google.auth.default() menggunakan
Kredensial Default Aplikasi (ADC), akun layanan terlampir, atau konfigurasi kredensial Workload Identity Federation. Untuk membatasi izin per panggilan, lihat
Menggunakan
peniruan akun layanan. |
Endpoint agen HTTPS Cloud Run atau Identity-Aware Proxy (IAP) (https://*.run.app atau domain kustom) |
Token ID
yang klaim aud-nya cocok dengan URL layanan target
atau client ID OAuth 2.0 IAP. |
google.oauth2.id_token.fetch_id_token() menggunakan akun layanan atau server metadata komputasi. Untuk petunjuk penyiapan, lihat
Mendapatkan token ID,
Autentikasi layanan ke layanan
di Cloud Run, dan
Autentikasi terprogram untuk
IAP. |
| Agen eksternal atau SaaS yang terikat OAuth | Token OAuth 2.0 2-legged, token OAuth 2.0 3-legged, atau Kunci API. | Dikelola secara otomatis di ADK saat binding pengelola autentikasi Agent Identity dilampirkan ke agen. Untuk mengetahui petunjuk penyiapan, lihat Melakukan autentikasi ke alat dan resource. |
Melakukan inisialisasi klien AgentRegistry di ADK
Untuk berinteraksi dengan Agent Registry melalui ADK, lakukan inisialisasi
klien AgentRegistry dalam kode Python Anda dengan project ID tata kelola
dan lokasi Agent Registry Anda:
import os
from google.adk.integrations.agent_registry import AgentRegistry
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
registry = AgentRegistry(
project_id=project_id,
location=location,
)
Setelah menginisialisasi klien AgentRegistry ADK, Anda dapat
mengambil agen A2A jarak jauh dan alat MCP jarak jauh dari Agent Registry. Di
ADK, agen A2A yang terdaftar digabungkan sebagai instance
RemoteA2aAgent. Instance ini disebut sebagai agen jarak jauh karena
ADK mendelegasikan tugas kepada instance tersebut melalui jaringan, bukan menjalankannya
dalam proses lokal. Demikian pula, server MCP jarak jauh yang terdaftar digabungkan
sebagai instance McpToolset.
Menyusun sistem multi-agen dengan ADK
Untuk mengambil sub-agen A2A jarak jauh dan rangkaian alat MCP jarak jauh dari
Agent Registry dan menyertakannya dalam definisi agen orchestrator LlmAgent,
gunakan klien AgentRegistry yang diinisialisasi:
- Untuk mengambil agen A2A jarak jauh: panggil
registry.get_remote_a2a_agent()dengan nama resource relatif sub-agen. Nama resource ini dapat berupa nama resource relatif dalam formatagents/AGENT_ID, yang menggunakan project ID dan lokasi yang dikonfigurasi pada klienAgentRegistry, atau nama resource lengkap dalam formatprojects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Jika pengelola autentikasiBindingada untuk agen,get_remote_a2a_agent()akan mengonfigurasi kredensial permintaan secara otomatis. Jika tidak adaBinding, teruskanhttpx_clientkustom yang dikonfigurasi dengan pengendalihttpx.Auth. - Untuk mengambil toolset MCP jarak jauh: panggil
registry.get_mcp_toolset()dengan nama resource relatif server MCP (mcpServers/SERVER_ID) atau nama resource lengkap (projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID).
Contoh berikut menunjukkan cara menentukan agen orchestrator dalam
file agent.py ADK. Dalam contoh ini, pertimbangkan hal berikut:
Class
GoogleApiAuthmengimplementasikan pengendalihttpx.Authuntuk memanggil subagen A2AGoogle Cloud API (https://*.googleapis.com). Library ini menggunakangoogle.auth.default()untuk memuat Kredensial Default Aplikasi, Akun Layanan Terlampir, atau kredensial Workload Identity Federation, serta menetapkan headerAuthorizationdanX-Goog-User-Projectpada setiap permintaan.Klien
registrymengambil sub-agen A2A jarak jauh dan toolset MCP jarak jauh dari Agent Registry dan meneruskannya keLlmAgentmelalui parametersub_agentsdantools.
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
class GoogleApiAuth(httpx.Auth):
def __init__(self, user_project_id: str):
self.user_project_id = user_project_id
self.creds, _ = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
def auth_flow(self, request):
if not self.creds.valid:
self.creds.refresh(Request())
request.headers["Authorization"] = f"Bearer {self.creds.token}"
request.headers["X-Goog-User-Project"] = self.user_project_id
yield request
quota_project_id = "QUOTA_PROJECT_ID"
agent_name = "agents/AGENT_ID"
httpx_client = httpx.AsyncClient(
auth=GoogleApiAuth(quota_project_id),
timeout=httpx.Timeout(60.0),
)
my_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_name,
httpx_client=httpx_client,
)
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
root_agent = LlmAgent(
model="MODEL_ID",
name="travel_orchestrator",
instruction=(
"You are a travel coordinator. Use your subagents to book travel "
"and your tools to query historical travel data."
),
tools=[my_mcp_toolset],
sub_agents=[my_remote_agent],
)
Ganti kode berikut:
QUOTA_PROJECT_ID: project ID yang digunakan untuk atribusi kuota dan penagihan pada permintaan ke endpoint agenGoogle Cloud API.AGENT_ID: ID sub-agen A2A terdaftar yang ingin dipanggil oleh agen orchestrator Anda, misalnya,agentregistry-01234456-7890-abcd-1234-567890abcdef.SERVER_ID: ID server MCP terdaftar yang ingin Anda gunakan untuk agen orchestrator.MODEL_ID: ID model untuk agen orchestrator Anda, misalnya,gemini-2.5-flash.
Setelah menyimpan root_agent di file agent.py project ADK,
Anda dapat menguji dan menjalankan agen orchestrator secara lokal menggunakan perintah CLI adk run atau
adk web, atau men-deploy-nya ke
Agent Runtime di Gemini Enterprise Agent Platform. Untuk mengetahui struktur project dan petunjuk eksekusi yang lengkap, lihat panduan memulai Python ADK dan contoh Registry Agen ADK di GitHub.
Memanggil agen A2A dari klien non-ADK
Jika Anda membangun agen atau klien orchestrator kustom tanpa ADK, aplikasi Anda akan melakukan dua langkah yang diautentikasi:
- Discovery: melakukan autentikasi ke Agent Registry API dengan token akses OAuth 2.0
untuk mengambil resource
Agentsub-agen target dan memeriksa Kartu Agennya. - Panggilan runtime: lampirkan token pemilik yang diperlukan oleh endpoint agen target, yang merupakan token akses OAuth 2.0 untuk endpoint agen
*.googleapis.comatau token ID OIDC untuk endpoint agen Cloud Run dan IAP. Kemudian, kirim permintaanSendMessageA2A. Output menampilkan objek JSONSendMessageResponse, yang berisi kolomtaskataumessagedalam format{"task": ...}atau{"message": ...}. Kolom ini berisi respons sub-agen, yang dapat diurai dan digunakan oleh agen orchestrator dalam alur kerjanya.
Untuk mencari dan memanggil subagen A2A terdaftar menggunakan google-auth dan httpx,
selesaikan langkah-langkah berikut:
Lakukan autentikasi ke Agent Registry dengan token akses OAuth 2.0 dan ambil resource
Agentsub-agen dari Agent Registry API:import os import uuid from urllib.parse import urlparse import google.auth from google.auth.transport.requests import Request from google.oauth2 import id_token import httpx project_id = os.environ["GOOGLE_CLOUD_PROJECT"] location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global") agent_id = "AGENT_ID" creds, _ = google.auth.default( scopes=["https://www.googleapis.com/auth/cloud-platform"] ) creds.refresh(Request()) registry_url = ( f"https://agentregistry.googleapis.com/v1/projects/{project_id}" f"/locations/{location}/agents/{agent_id}" ) client = httpx.Client(timeout=60.0) reg_response = client.get( registry_url, headers={ "Authorization": f"Bearer {creds.token}", "X-Goog-User-Project": project_id, }, ) reg_response.raise_for_status() agent_resource = reg_response.json()Ganti
AGENT_IDdengan ID sub-agen A2A terdaftar yang ingin Anda panggil, misalnya,agentregistry-01234456-7890-abcd-1234-567890abcdef.Ekstrak antarmuka A2A berbasis HTTP dari Kartu Agen di resource
Agent:card = agent_resource.get("card", {}).get("content", {}) interfaces = card.get("supportedInterfaces") or ( (agent_resource.get("protocols") or [{}])[0].get("interfaces", []) ) iface = next( i for i in interfaces if i.get("protocolBinding", "HTTP+JSON") in ("HTTP+JSON", "HTTP_JSON", "JSONRPC") ) endpoint_url = iface["url"] binding = iface.get("protocolBinding", "HTTP+JSON") tenant = iface.get("tenant", "")Siapkan header permintaan dengan token akses OAuth 2.0 untuk endpoint agen
*.googleapis.comatau token ID OIDC untuk endpoint agen Cloud Run atau IAP:host = urlparse(endpoint_url).hostname or "" headers = {"Content-Type": "application/json", "A2A-Version": "1.0"} if host == "googleapis.com" or host.endswith(".googleapis.com"): headers["Authorization"] = f"Bearer {creds.token}" headers["X-Goog-User-Project"] = project_id else: oidc_audience = f"https://{host}" oidc_jwt = id_token.fetch_id_token(Request(), oidc_audience) headers["Authorization"] = f"Bearer {oidc_jwt}"Format dan kirim permintaan
SendMessageA2A menggunakan binding protokol dari Kartu Agen, dan uraikan respons dari sub-agen:message = { "messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"text": "Summarize recent deployment status."}], } if binding == "JSONRPC": params = {"message": message} if tenant: params["tenant"] = tenant payload = { "jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": "SendMessage", "params": params, } target_url = endpoint_url else: payload = {"message": message} prefix = f"/{tenant.strip('/')}" if tenant else "" target_url = f"{endpoint_url.rstrip('/')}{prefix}/message:send" response = client.post(target_url, headers=headers, json=payload) response.raise_for_status() body = response.json() if binding == "JSONRPC": if "error" in body: raise RuntimeError(f"JSON-RPC error: {body['error']}") send_message_response = body["result"] else: send_message_response = body print(send_message_response) client.close()Langkah ini memformat permintaan
SendMessageuntuk A2A versi1.0. Jika Anda perlu melakukan negosiasi antara protokol A2A versi1.0dan0.3secara otomatis, gunakan ADK atau klien Pythona2a-sdk.
Menggunakan kembali agen jarak jauh di seluruh agen orchestrator di ADK
Untuk meminimalkan latensi jaringan, ambil remote agent dan toolset Anda dari
Agent Registry sekali saat aplikasi dimulai, bukan memanggil
get_remote_a2a_agent() pada setiap permintaan.
Di ADK, instance RemoteA2aAgent hanya dapat memiliki satu agen orchestrator induk dalam satu waktu. Melanjutkan dari
penyiapan inisialisasi, panggil .clone() untuk membuat
salinan independen bagi setiap agen orchestrator induk:
agent_path = (
f"projects/{project_id}/locations/{location}"
"/agents/AGENT_ID"
)
base_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_path,
httpx_client=httpx_client,
)
flight_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="flight_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
hotel_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="hotel_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
Ganti AGENT_ID dengan ID sub-agen A2A terdaftar yang ingin dipanggil oleh agen orchestrator Anda.
Langkah berikutnya
- Tinjau A2A protocol untuk binding transpor dan status siklus proses tugas.
- Pelajari cara menyiapkan Agent Gateway untuk merutekan dan mengatur traffic untuk endpoint agen target Anda.
- Pelajari cara melakukan autentikasi ke alat dan resource serta mencakup kredensial di seluruh panggilan agen.
- Pelajari cara mendaftarkan keahlian dan mengelola keahlian di Agent Registry.