Mengautentikasi ke alat dan resource

Saat memanggil agen jarak jauh atau set alat Model Context Protocol (MCP) yang ditemukan melalui Agent Registry, agen orkestrator harus melakukan autentikasi dengan layanan pokok yang menyediakan kemampuan tersebut.

Dokumen ini menjelaskan cara menangani autentikasi untuk resource Agent Registry.

Sebelum memulai

Sebelum Anda melakukan autentikasi ke alat dan resource, selesaikan langkah-langkah berikut:

Siapkan Agent Registry di project Anda.
Instal atau upgrade ke versi terbaru Agent Development Kit (ADK):
```
pip install --upgrade google-adk
```
Anda harus mengupgrade ke minimal google-adk>=1.29.0.
Untuk menggunakan Kredensial Default Aplikasi (ADC) untuk autentikasi, konfigurasikan ADC:
```
gcloud auth application-default login
```
Kredensial ADC harus memiliki izin IAM yang diperlukan untuk layanan pokok yang berinteraksi dengan agen atau alat.
Untuk mengikuti contoh dalam panduan ini, Anda harus menyiapkan variabel lingkungan, misalnya:
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY
```
Ganti kode berikut:
- PROJECT_ID: project ID Anda.
- LOCATION: region atau lokasi registri, seperti us-central1.
- EXTERNAL_API_KEY: jika menggunakan header kustom, kunci API eksternal Anda.

Mempelajari model autentikasi

Untuk mengelola kredensial, Agent Registry mengandalkan Agent Identity untuk autentikasi Google Cloud bawaan dan pengelola autentikasi Agent Identity untuk penyedia autentikasi dan binding.

Agen Anda dapat menggunakan identitasnya sendiri atau menggunakan pengelola autentikasi untuk mengakses alat menggunakan kunci API atau OAuth. Identitas agen sendiri diberikan melalui Kredensial Default Aplikasi (ADC) baik Anda menggunakan Identitas Agen atau akun layanan.

Atau, untuk mengirim konteks lanjutan ke agen target, atau jika set alat eksternal tidak mendukung pengelola autentikasi Identitas Agen, Anda dapat memberikan header HTTP kustom langsung dalam permintaan ADK.

Untuk menentukan pendekatan terbaik untuk kasus penggunaan Anda, lihat Model autentikasi.

Menggunakan Identitas Agen untuk alat Google Cloud

Untuk layanan Google Cloud , seperti Vertex AI atau Cloud Storage, agen Anda menggunakan identitasnya sendiri untuk mengakses alat. Akses ini dikelola melalui Kredensial Default Aplikasi (ADC) baik Anda menggunakan Identitas Agen maupun akun layanan.

Identitas yang terkait dengan agen Anda harus memiliki izin Identity and Access Management yang diperlukan untuk layanan pokok. Misalnya, jika alat MCP mengelola instance VM Compute Engine, identitas agen harus memiliki peran seperti Compute Instance Admin (v1) atau yang lebih tinggi, selain peran Pelihat Agent Registry API.

Mengautentikasi agen A2A jarak jauh

Jika agen orkestrator Anda terhubung ke agen Google Agent2Agent (A2A) jarak jauh menggunakan identitasnya sendiri, Anda harus menyertakan httpx.AsyncClient secara eksplisit yang dikonfigurasi dengan header autentikasi Google Anda ke metode get_remote_a2a_agent().

Sebaiknya tentukan waktu tunggu kustom untuk mencegah terlampauinya batas waktu tunggu klien HTTP default.

Contoh berikut menunjukkan cara mengonfigurasi httpx.AsyncClient dengan ADC dan waktu tunggu kustom:

import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

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

# Initialize the registry client
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,
)

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

# 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"
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client,
)

Mengautentikasi alat MCP

Jika agen orkestrator Anda menggunakan identitasnya sendiri untuk mengakses toolset MCP, Anda dapat menginisialisasi klien registri menggunakan ADC dan metode get_mcp_toolset():

import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

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

# Initialize the registry client
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,
)

# 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)

Menggunakan pengelola autentikasi untuk alat kustom dan akses yang didelegasikan

Saat agen Anda perlu terhubung ke API eksternal, alat kustom, atau server MCP eksternal, Anda dapat menggunakan pengelola autentikasi Identitas Agen untuk mengelola kredensial tanpa meng-hardcode-nya di aplikasi Anda.

Bergantung pada kasus penggunaan, Anda dapat mengonfigurasi pengelola autentikasi untuk skenario berikut:

Mengakses alat kustom: Lakukan autentikasi agen dengan kunci API atau OAuth 2-legged (2LO) saat agen perlu mengakses alat menggunakan identitas dan izinnya sendiri.
Mengakses alat atas nama pengguna: Lakukan autentikasi pada agen yang bertindak sebagai pengguna perorangan dengan 3-legged OAuth (3LO). Model ini direkomendasikan saat agen harus mengakses alat atas nama orang yang berinteraksi dengannya, sehingga memerlukan izin pengguna dan izin yang didelegasikan.

Model ini mengharuskan Anda membuat penyedia autentikasi. Kemudian, Anda membuat binding di Agent Registry untuk menautkan penyedia otorisasi ke resource registry Anda.

Setelah mengonfigurasi penyedia autentikasi, ADK akan mengelola alur autentikasi untuk orkestrator Anda. Untuk melihat contoh, lihat Menyelesaikan binding dalam kode ADK Anda.

Mengakses alat kustom

Jika Anda ingin agen terhubung ke alat eksternal atau kustom menggunakan kredensialnya sendiri, Anda dapat mengonfigurasi pengelola autentikasi Identitas Agen untuk menangani kunci API atau OAuth 2-legged (2LO):

Buat penyedia autentikasi: Buat penyedia autentikasi di pengelola autentikasi Identitas Agen untuk menyimpan kunci API atau kredensial OAuth. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi menggunakan OAuth 2-legged dengan pengelola autentikasi atau Mengautentikasi menggunakan kunci API dengan pengelola autentikasi.
Ikat penyedia autentikasi: Agar agen orkestrator Anda dapat mendeteksi penyedia autentikasi yang benar untuk target, Anda harus membuat pengikatan di Pendaftaran Agen antara agen dan penyedia autentikasi. Dengan binding, Anda tidak perlu menentukan penyedia autentikasi secara manual dalam kode Anda.

Buat binding untuk menautkan agen Anda secara eksplisit ke penyedia autentikasi. Saat menentukan nama resource --auth-provider, Anda harus menggunakan project ID Anda:
```
gcloud alpha agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=LOCATION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--auth-provider="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_ID" \
```
Untuk mengetahui informasi selengkapnya tentang cara mengelola koneksi ini, lihat Mengelola binding.

Mengakses alat atas nama pengguna

Jika Anda ingin agen melakukan autentikasi ke server atau alat MCP jarak jauh atas nama pengguna individual, gunakan 3-legged OAuth (3LO) melalui pengelola autentikasi Identitas Agen.

Pengelola autentikasi menyediakan layanan yang dikelola sepenuhnya oleh Google untuk menangani token OAuth, izin pengguna, dan pengalihan. Saat Anda berinteraksi dengan agen dan memicu alat yang memerlukan izin yang didelegasikan, platform akan otomatis meminta izin pengguna, menyimpan kredensial, dan melanjutkan alur kerja:

Buat penyedia auth: Buat penyedia auth di pengelola autentikasi Identitas Agen dan konfigurasi URI pengalihan OAuth Anda. Untuk mengetahui informasi, lihat Mengautentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi.
Perbarui aplikasi klien: Perbarui klien aplikasi Anda untuk menangani panggilan fungsi adk_request_credential dan mengelola izin pengguna. Untuk petunjuk mendetail, lihat Mengupdate aplikasi sisi klien.
Ikat penyedia autentikasi: Agar agen orkestrator Anda dapat mendeteksi penyedia autentikasi yang benar untuk target, Anda harus membuat pengikatan di Pendaftaran Agen antara agen dan penyedia autentikasi. Dengan binding, Anda tidak perlu menentukan penyedia autentikasi secara manual dalam kode Anda.

Buat binding untuk menautkan agen Anda secara eksplisit ke penyedia autentikasi. Saat menentukan nama resource --auth-provider, Anda harus menggunakan project ID Anda:
```
gcloud alpha agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=LOCATION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--auth-provider="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_ID" \
```
Untuk mengetahui informasi selengkapnya tentang cara mengelola koneksi ini, lihat Mengelola binding.

Menyelesaikan binding dalam kode ADK Anda

Setelah Anda membuat binding penyedia autentikasi di Agent Registry, ADK akan menangani alur autentikasi.

Saat Anda menggunakan klien AgentRegistry untuk mengambil set alat MCP, ADK akan otomatis menyelesaikan semua binding yang terkait dengan server tersebut dan menerapkan skema yang benar. Anda tidak perlu mengonfigurasi kredensial secara manual dalam kode Anda.

Contoh berikut menunjukkan cara mengambil set alat MCP yang diautentikasi dan melampirkannya ke agen:

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
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.")

# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

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

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide"
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get"
        "the best information (e.g., search for a place first, then get details"
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses,"
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including"
        "full addresses and key details. Use formatting to make recommendations"
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with"
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

Jika Anda menyiapkan 3LO untuk mengakses alat atas nama pengguna, Anda juga harus memberikan continue_uri ke metode get_mcp_toolset. URI ini menunjukkan ke mana pengguna dialihkan setelah memberikan izin:

[...]

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
# For 3-legged OAuth (3LO), provide continue_uri.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(
    mcp_server_name=mcp_server_name,
    # Replace with your app's redirect URI:
    continue_uri="https://REDIRECT_URI"
)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide"
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get"
        "the best information (e.g., search for a place first, then get details"
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses,"
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including"
        "full addresses and key details. Use formatting to make recommendations"
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with"
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

Menggunakan header kustom untuk alat eksternal

Untuk mengirim konteks lanjutan ke agen target, atau jika set alat eksternal tidak mendukung pengelola autentikasi Identitas Agen, Anda dapat memberikan header HTTP kustom langsung dalam permintaan ADK.

Konfigurasi header kustom dengan memberikan callback header_provider saat menginisialisasi klien AgentRegistry.

Callback header_provider menerima konteks eksekusi saat ini dan menampilkan kamus header HTTP. Komponen RemoteA2aAgent atau McpToolset secara otomatis melampirkan header ini ke permintaan hilir.

Header kustom yang disediakan oleh callback header_provider hanya dikirim ke layanan target, yaitu agen atau alat. Header kustom tidak digunakan untuk mengautentikasi terhadap Agent Registry API itu sendiri. API selalu mengandalkan ADC.

Contoh ini menunjukkan cara memberikan kunci API atau token pembawa kustom untuk kumpulan alat eksternal:

import os
from typing import Any
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
external_api_key = os.environ.get("API_KEY")

# Define the custom header provider.
def my_auth_headers(context: Any) -> dict[str, str]:
    """Returns custom headers injected into the tool or agent requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the MCP server or agent during invocation.
# The header_provider is not used to authenticate against the Agent Registry API.
# The Agent Registry API always uses your Google ADC.
registry = AgentRegistry(
    project_id=project_id,
    location=location,
    header_provider=my_auth_headers
)

# Fetching the toolset automatically attaches the header_provider to the MCP server.
# Replace with the full resource name of your registered MCP server.
mcp_server_name = f"projects/PROJECT_ID/locations/LOCATION/mcpServers/EXTERNAL_SERVER_ID"
external_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

Langkah berikutnya

Pelajari cara menggunakan Agent Gateway untuk menerapkan kontrol akses dan perimeter jaringan pada permintaan alat yang diautentikasi.