Membangun sistem multi-agen dan memanggil agen A2A

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:

  1. Menyiapkan Agent Registry.
  2. 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.

  3. 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 httpx
    
  4. Konfigurasi 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 login
    
  5. Siapkan variabel lingkungan berikut:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=LOCATION
    

    Ganti kode berikut:

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 format agents/AGENT_ID, yang menggunakan project ID dan lokasi yang dikonfigurasi pada klien AgentRegistry, atau nama resource lengkap dalam format projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Jika pengelola autentikasi Binding ada untuk agen, get_remote_a2a_agent() akan mengonfigurasi kredensial permintaan secara otomatis. Jika tidak ada Binding, teruskan httpx_client kustom yang dikonfigurasi dengan pengendali httpx.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 GoogleApiAuth mengimplementasikan pengendali httpx.Auth untuk memanggil subagen A2AGoogle Cloud API (https://*.googleapis.com). Library ini menggunakan google.auth.default() untuk memuat Kredensial Default Aplikasi, Akun Layanan Terlampir, atau kredensial Workload Identity Federation, serta menetapkan header Authorization dan X-Goog-User-Project pada setiap permintaan.

  • Klien registry mengambil sub-agen A2A jarak jauh dan toolset MCP jarak jauh dari Agent Registry dan meneruskannya ke LlmAgent melalui parameter sub_agents dan tools.

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:

  1. Discovery: melakukan autentikasi ke Agent Registry API dengan token akses OAuth 2.0 untuk mengambil resource Agent sub-agen target dan memeriksa Kartu Agennya.
  2. Panggilan runtime: lampirkan token pemilik yang diperlukan oleh endpoint agen target, yang merupakan token akses OAuth 2.0 untuk endpoint agen *.googleapis.com atau token ID OIDC untuk endpoint agen Cloud Run dan IAP. Kemudian, kirim permintaan SendMessage A2A. Output menampilkan objek JSON SendMessageResponse, yang berisi kolom task atau message dalam 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:

  1. Lakukan autentikasi ke Agent Registry dengan token akses OAuth 2.0 dan ambil resource Agent sub-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_ID dengan ID sub-agen A2A terdaftar yang ingin Anda panggil, misalnya, agentregistry-01234456-7890-abcd-1234-567890abcdef.

  2. 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", "")
    
  3. Siapkan header permintaan dengan token akses OAuth 2.0 untuk endpoint agen *.googleapis.com atau 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}"
    
  4. Format dan kirim permintaan SendMessage A2A 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 SendMessage untuk A2A versi 1.0. Jika Anda perlu melakukan negosiasi antara protokol A2A versi 1.0 dan 0.3 secara otomatis, gunakan ADK atau klien Python a2a-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