Menyelesaikan endpoint dan membangun pengatur

Agent Development Kit (ADK) menyediakan klien AgentRegistry khusus yang memungkinkan Anda menemukan, mencari, dan terhubung ke agen AI dan server Model Context Protocol (MCP) yang dikatalogkan dalam Agent Registry secara terprogram.

Daripada meng-hardcode URL endpoint ke dalam aplikasi, Anda dapat menggunakan ADK untuk menyelesaikan endpoint ini saat runtime.

Agent Registry menyediakan endpoint pokok, tetapi deployment produksi biasanya merutekan pemanggilan ini melalui Agent Gateway. Agent Gateway membantu Anda menerapkan kebijakan keamanan, melakukan mediasi protokol, dan menerapkan pemfilteran konten ke alat yang Anda temukan.

Dokumen ini menjelaskan cara mengambil agen jarak jauh dan toolset MCP dari Agent Registry serta menyertakannya dalam agen pengelola induk.

Sebelum memulai

Sebelum mengintegrasikan ADK dengan Agent Registry, selesaikan langkah-langkah berikut:

  1. Siapkan Agent Registry di project Anda.

  2. Instal atau upgrade ke ADK versi terbaru dengan dependensi A2A yang diperlukan:

    pip 

    pip install --upgrade "google-adk[a2a]"

    uv 

    uv add "google-adk[a2a]"

    Anda harus mengupgrade ke minimal google-adk>=1.29.0.

  3. Konfigurasi Kredensial Default Aplikasi (ADC):

    gcloud auth application-default login

Kredensial ADC harus memiliki izin IAM yang diperlukan untuk layanan pokok yang berinteraksi dengan agen atau alat. Secara opsional, Anda juga dapat menggunakan header kustom untuk set alat eksternal. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi ke alat dan resource.

Menetapkan variabel lingkungan

Untuk mengikuti panduan ini, tetapkan variabel lingkungan berikut:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION

Ganti kode berikut:

  • PROJECT_ID: project ID Anda.
  • LOCATION: region atau lokasi registri, seperti us-central1.

Menginisialisasi klien registri

Untuk berinteraksi dengan registry Anda secara terprogram, lakukan inisialisasi klien AgentRegistry dengan project dan lokasi 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.")

# Initialize the client
registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

Menyusun sistem multi-agen

ADK mengabstraksi mekanisme koneksi yang mendasarinya, sehingga Anda dapat mendesain aplikasi yang skalabel dengan menyusun beberapa agen khusus ke dalam hierarki yang fleksibel.

Anda dapat menggunakan klien registri untuk mengambil resource tertentu dan meneruskannya langsung ke definisi agen LlmAgent baru. Orchestrator Anda dapat memanggil agen jarak jauh sebagai subagen dan menjalankan alat MCP seolah-olah alat tersebut adalah fungsi Python lokal.

Gunakan metode berikut:

  • Untuk mengambil agen jarak jauh: Gunakan get_remote_a2a_agent()
  • Untuk mengambil toolset MCP: Gunakan get_mcp_toolset()

Contoh berikut menunjukkan cara menyusun sistem multi-agen dengan membangun agen orkestrator yang memanfaatkan agen perjalanan terdaftar dan server MCP Compute Engine yang terdaftar. Dalam contoh ini, autentikasi ditangani oleh identitas agen itu sendiri, tetapi Anda dapat menggunakan metode lain, seperti kunci API dan OAuth. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi ke alat dan resource.

Untuk mendesain dan mengatur agen menggunakan antarmuka visual low-code, konfigurasi subagen terdaftar langsung di kanvas Agent Studio. Untuk mengetahui informasi selengkapnya, lihat Mendesain agen di Agent Studio.

import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent

# Define the GoogleAuth class for the HTTP client
class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

# Connect to a remote A2A agent using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "agents/AGENT_ID"
# Full format: f"projects/{project_id}/locations/{location}/agents/AGENT_ID"
agent_name = "agents/AGENT_ID"

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client
)

# Retrieve an MCP toolset using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "mcpServers/SERVER_ID"
# Full format: f"projects/{project_id}/locations/{location}/mcpServers/SERVER_ID"
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

# Compose the orchestrator agent
main_agent = LlmAgent(
    model="MODEL_ID", # Replace with a model such as gemini-1.5-flash
    name="travel_orchestrator",
    instruction="""You are a travel coordinator. You can use your
                   subagents to book travel and your tools to query
                   historical travel data.""",
    tools=[my_mcp_toolset],
    sub_agents=[my_remote_agent],
)

# You can now run your orchestrator agent
# response = await main_agent.run('Book a flight to Paris and check my past trips.')

Praktik terbaik untuk menggunakan kembali agen

Untuk meminimalkan latensi jaringan, ambil agen dan toolset Anda dari registry sekali saat aplikasi dimulai, bukan memanggil get_remote_a2a_agent() pada setiap pemanggilan.

Agen hanya dapat memiliki satu agen induk dalam satu waktu. Jika Anda mencoba menetapkan instance agen yang sama yang diambil ke beberapa pengelola, ADK mungkin akan menampilkan error yang menunjukkan bahwa agen sudah memiliki induk.

Untuk menggunakan kembali agen yang ditemukan di beberapa agen induk, gunakan metode .clone() untuk membuat instance baru objek agen.

Contoh berikut menunjukkan cara mengambil agen sekali dan meng-clone-nya untuk digunakan di pengelola yang berbeda:

import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent

# Define the GoogleAuth class for the HTTP client
class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))

# Fetch the remote agent once during startup
# Use the resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "agents/AGENT_ID"
# Full format: f"projects/{project_id}/locations/{location}/agents/AGENT_ID"
agent_name = f"projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID"
base_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client
)

# Use .clone() to assign the agent to different parent orchestrators
flight_orchestrator = LlmAgent(
    model="gemini-1.5-flash",
    name="flight_orchestrator",
    sub_agents=[base_remote_agent.clone()]
)

hotel_orchestrator = LlmAgent(
    model="gemini-1.5-flash",
    name="hotel_orchestrator",
    sub_agents=[base_remote_agent.clone()]
)

Langkah berikutnya