Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengautentikasi ke alat dan resource

Agent Registry memungkinkan agen orchestrator Anda melakukan autentikasi dengan aman ke agen jarak jauh, set alat Model Context Protocol (MCP), dan layananGoogle Cloud yang ditemukan. Dengan menggunakan Agent Identity dan pengelola autentikasi Agent Identity, Anda dapat mengonfigurasi kredensial, binding, dan header HTTP kustom saat memanggil kemampuan yang ditemukan melalui Agent Registry.

Sebelum memulai

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

Menyiapkan Agent Registry.
Dapatkan project ID untuk project tata kelola tempat Agent Registry diaktifkan.
Instal atau upgrade ke Agent Development Kit (ADK) versi terbaru dengan dependensi A2A, Agent Identity, dan MCP:
pip
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
uv
uv add "google-adk[a2a,agent-identity,mcp]"
Anda harus mengupgrade ke setidaknya google-adk>=1.29.0.
Untuk menggunakan Kredensial Default Aplikasi (ADC) untuk autentikasi, konfigurasikan kredensial tersebut:
```
gcloud auth application-default login
```
Kredensial ADC harus memiliki izin Identity and Access Management (IAM) yang diperlukan untuk layanan Google Cloud yang mendasarinya, yang berinteraksi dengan agen atau alat.
Siapkan variabel lingkungan berikut:
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY
```
Ganti kode berikut:
- PROJECT_ID: project ID dari project tata kelola Anda.
- LOCATION: region atau lokasi registry, 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 untuk penyedia autentikasi dan binding.

Agen Anda dapat menggunakan identitas mereka sendiri atau menggunakan pengelola autentikasi untuk mengakses alat menggunakan kunci API atau OAuth 2.0. Identitas agen itu sendiri disediakan melalui Kredensial Default Aplikasi (ADC), baik Anda menggunakan Identitas Agen maupun akun layanan.

Jika Anda perlu melakukan autentikasi tanpa menggunakan pengelola autentikasi, berikan header HTTP kustom langsung dalam permintaan ADK Anda.

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

Menggunakan Identitas Agen untuk alat Google Cloud

Untuk layanan Google Cloud , seperti Agent Runtime di Gemini Enterprise Agent Platform atau Cloud Storage, agen Anda menggunakan identitasnya sendiri untuk mengakses alat. Akses ini dikelola melalui Kredensial Default Aplikasi (ADC), baik Anda menggunakan Identitas Agen atau akun layanan.

Identitas yang terkait dengan agen Anda harus memiliki izin IAM yang diperlukan untuk layanan Google Cloud yang mendasarinya. 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 Agent Registry API Viewer.

Mengautentikasi agen A2A jarak jauh

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

Untuk mencegah terlampauinya batas waktu tunggu klien HTTP default, tentukan waktu tunggu kustom.

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

Ganti AGENT_ID dengan ID agen terdaftar Anda.

Mengautentikasi alat MCP

Jika agen orchestrator menggunakan identitasnya sendiri untuk mengakses toolset MCP, Anda dapat melakukan inisialisasi klien registry menggunakan ADC dan metode get_mcp_toolset():

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

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

Ganti SERVER_ID dengan ID server MCP terdaftar Anda.

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 untuk mengelola kredensial tanpa melakukan hardcoding di aplikasi Anda.

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

Mengakses alat kustom: 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: mengautentikasi agen yang bertindak sebagai pengguna individu dengan OAuth 3-legged (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 autentikasi ke resource registry Anda.

Setelah mengonfigurasi penyedia autentikasi, ADK akan mengelola alur autentikasi untuk orchestrator Anda. Misalnya, 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 untuk menangani kunci API atau OAuth 2-legged (2LO):

Membuat penyedia autentikasi: buat penyedia autentikasi di pengelola autentikasi untuk menyimpan kunci API atau kredensial OAuth. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi menggunakan OAuth 2-legged dengan pengelola autentikasi atau Melakukan autentikasi menggunakan kunci API dengan pengelola autentikasi.
Mengikat penyedia autentikasi: agar agen orchestrator dapat mendeteksi penyedia autentikasi yang benar untuk target, Anda harus membuat binding di Registry Agen antara agen, resource target, dan penyedia autentikasi. Dengan binding, Anda tidak perlu menentukan penyedia autentikasi secara manual dalam kode:
gcloud
Buat binding untuk menautkan agen Anda secara eksplisit ke resource target dan penyedia autentikasi dengan menjalankan perintah gcloud agent-registry bindings create. Saat menentukan nama resource --auth-provider-binding, Anda harus menggunakan project ID dari project tata kelola Anda:
gcloud agent-registry bindings create BINDING_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --source-identifier="SOURCE_ID" \ --target-identifier="TARGET_ID" \ --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
Terraform
Konfigurasi resource google_agent_registry_binding untuk menautkan agen dan resource target Anda ke penyedia autentikasi:
resource "google_agent_registry_binding" "custom_tool_binding" { project = "PROJECT_ID" location = "LOCATION" binding_id = "BINDING_NAME" display_name = "DISPLAY_NAME" source { identifier = "SOURCE_ID" } target { identifier = "TARGET_ID" } auth_provider_binding { auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" } }
Ganti kode berikut:
- BINDING_NAME: ID unik untuk binding.
- PROJECT_ID: project ID dari project tata kelola Anda.
- LOCATION: region atau lokasi registry, seperti us-central1 atau global.
- DISPLAY_NAME: nama tampilan yang dapat dibaca manusia untuk binding.
- SOURCE_ID: ID agen agen sumber dalam format URN.
- TARGET_ID: ID registry server atau endpoint MCP target dalam format URN.
- AUTH_PROVIDER_ID: ID penyedia autentikasi Anda.
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 perorangan, gunakan 3-legged OAuth (3LO) melalui pengelola autentikasi.

Pengelola autentikasi menyediakan layanan terkelola sepenuhnya oleh Google untuk menangani token OAuth, izin pengguna, dan pengalihan. Saat pengguna akhir 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 auth dan konfigurasikan URI pengalihan OAuth Anda. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi.
Mengupdate aplikasi klien: update klien aplikasi Anda untuk menangani panggilan fungsi adk_request_credential dan mengelola izin pengguna. Untuk petunjuk mendetail, lihat Mengupdate aplikasi sisi klien.
Mengikat penyedia autentikasi: agar agen orchestrator dapat mendeteksi penyedia autentikasi yang benar untuk target, Anda harus membuat binding di Registry Agen antara agen, resource target, dan penyedia autentikasi. Dengan binding, Anda tidak perlu menentukan penyedia autentikasi secara manual dalam kode:
gcloud
Buat binding untuk menautkan agen Anda secara eksplisit ke resource target dan penyedia autentikasi dengan menjalankan perintah gcloud agent-registry bindings create. Saat menentukan nama resource --auth-provider-binding, Anda harus menggunakan project ID dari project tata kelola Anda:
gcloud agent-registry bindings create BINDING_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --display-name="DISPLAY_NAME" \ --source-identifier="SOURCE_ID" \ --target-identifier="TARGET_ID" \ --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" \ --auth-provider-binding-scopes=SCOPES \ --auth-provider-binding-continue-uri="https://REDIRECT_URI"
Terraform
Konfigurasi resource google_agent_registry_binding dengan cakupan OAuth 2.0 dan URI lanjutkan:
resource "google_agent_registry_binding" "user_delegated_binding" { project = "PROJECT_ID" location = "LOCATION" binding_id = "BINDING_NAME" display_name = "DISPLAY_NAME" source { identifier = "SOURCE_ID" } target { identifier = "TARGET_ID" } auth_provider_binding { auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" scopes = [SCOPES] continue_uri = "https://REDIRECT_URI" } }
Ganti kode berikut:
- BINDING_NAME: ID unik untuk binding.
- PROJECT_ID: project ID dari project tata kelola Anda.
- LOCATION: region atau lokasi registry, seperti us-central1 atau global.
- DISPLAY_NAME: nama tampilan yang dapat dibaca manusia untuk binding.
- SOURCE_ID: ID agen agen sumber dalam format URN.
- TARGET_ID: ID registry resource alat atau server MCP target dalam format URN.
- AUTH_PROVIDER_ID: ID penyedia autentikasi Anda.
- SCOPES: comma separated list berisi cakupan OAuth 2.0, seperti https://www.googleapis.com/auth/cloud-platform. Di Terraform, sertakan setiap cakupan dalam tanda kutip ganda.
- REDIRECT_URI: URI pengalihan yang dikonfigurasi untuk penyedia autentikasi Anda setelah izin pengguna.
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 MCP toolset, ADK akan otomatis me-resolve binding apa pun 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 toolset 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],
)

Ganti SERVER_ID dengan ID server MCP terdaftar Anda.

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

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.
# 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],
)

Ganti kode berikut:

SERVER_ID: ID server MCP terdaftar Anda.
REDIRECT_URI: URI pengalihan aplikasi Anda, yang menjadi tujuan pengalihan pengguna setelah memberikan izin.

Menggunakan header kustom untuk alat eksternal

Jika Anda perlu mengautentikasi atau meneruskan header permintaan tanpa menggunakan pengelola autentikasi, berikan header HTTP kustom langsung dalam permintaan ADK Anda.

Konfigurasikan header kustom dengan memberikan callback header_provider saat melakukan inisialisasi klien AgentRegistry Anda.

Callback header_provider menerima konteks eksekusi saat ini dan menampilkan kamus header HTTP. Komponen McpToolset akan otomatis melampirkan header ini ke permintaan downstream yang dikirim ke server MCP.

Header kustom yang disediakan oleh callback header_provider hanya dikirim ke server MCP target. Header kustom tidak digunakan untuk melakukan autentikasi terhadap Agent Registry API itu sendiri. API selalu mengandalkan ADC.

Contoh ini menunjukkan cara memberikan kunci API atau token pemilik kustom untuk set 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 MCP toolset requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the target MCP server 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)