Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Autenticación en herramientas y recursos

Agent Registry permite que tus agentes de organización se autentiquen de forma segura en los agentes remotos descubiertos, los conjuntos de herramientas del Protocolo de contexto del modelo (MCP) y los servicios deGoogle Cloud . Con Agent Identity y el administrador de autenticación de Agent Identity, puedes configurar credenciales, vinculaciones y encabezados HTTP personalizados cuando invoques capacidades descubiertas a través de Agent Registry.

Antes de comenzar

Antes de autenticarte en las herramientas y los recursos, completa lo siguiente:

Configura el Registro de agentes.
Obtén el ID del proyecto para el proyecto de administración en el que está habilitado el Registro de agentes.
Instala o actualiza a la versión más reciente del Kit de desarrollo de agentes (ADK) con las dependencias de A2A, Agent Identity y MCP:
pip
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
uv
uv add "google-adk[a2a,agent-identity,mcp]"
Debes actualizar a la versión google-adk>=1.29.0 como mínimo.
Para usar las credenciales predeterminadas de la aplicación (ADC) en la autenticación, configúralas de la siguiente manera:
```
gcloud auth application-default login
```
Las credenciales de ADC deben tener los permisos de Identity and Access Management (IAM) necesarios para los servicios de Google Cloud subyacentes con los que interactúan los agentes o las herramientas.
Configura las siguientes variables de entorno:
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY
```
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de administración.
- LOCATION: Es la región o ubicación del registro, como us-central1.
- EXTERNAL_API_KEY: Si usas encabezados personalizados, tu clave de API externa.

Obtén más información sobre los modelos de autenticación

Para administrar las credenciales, el registro de agentes se basa en la identidad del agente para la autenticación integrada deGoogle Cloud y el administrador de autenticación para los proveedores de autenticación y las vinculaciones.

Tus agentes pueden usar su propia identidad o el administrador de autenticación para acceder a las herramientas con claves de API o con OAuth 2.0. La identidad del agente se proporciona a través de las credenciales predeterminadas de la aplicación (ADC), ya sea que uses la identidad del agente o las cuentas de servicio.

Si necesitas autenticarte sin usar el administrador de autenticación, proporciona encabezados HTTP personalizados directamente en tus solicitudes del ADK.

Para determinar el mejor enfoque para tu caso de uso, consulta Modelos de autenticación.

Usa la identidad del agente para las herramientas de Google Cloud

Para los servicios de Google Cloud , como Agent Runtime en Gemini Enterprise Agent Platform o Cloud Storage, tu agente usa su propia identidad para acceder a las herramientas. Este acceso se administra a través de las credenciales predeterminadas de la aplicación (ADC), ya sea que uses Agent Identity o cuentas de servicio.

La identidad asociada con tu agente debe tener los permisos de IAM necesarios para los servicios de Google Cloud subyacentes. Por ejemplo, si una herramienta de MCP administra instancias de VM de Compute Engine, la identidad del agente debe tener roles como Administrador de instancias de Compute (v1) o superior, además del rol de visualizador de la API de Agent Registry.

Autentica agentes A2A remotos

Si tu agente de organización se conecta a un agente remoto de Google Agent2Agent (A2A) con su propia identidad, debes incluir de forma explícita httpx.AsyncClient configurado con tus encabezados de autenticación de Google en el método get_remote_a2a_agent().

Para evitar que se superen los límites de tiempo de espera predeterminados del cliente HTTP, define un tiempo de espera personalizado.

En el siguiente ejemplo, se muestra cómo configurar httpx.AsyncClient con ADC y un tiempo de espera personalizado:

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

Reemplaza AGENT_ID por el ID de tu agente registrado.

Autentica las herramientas de MCP

Si tu agente de organización usa su propia identidad para acceder a un conjunto de herramientas de MCP, puedes inicializar el cliente de registro con tus ADC y el método 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)

Reemplaza SERVER_ID por el ID de tu servidor de MCP registrado.

Usa el administrador de autenticación para herramientas personalizadas y acceso delegado

Cuando tu agente necesite conectarse a APIs externas, herramientas personalizadas o servidores de MCP externos, puedes usar el administrador de autenticación para administrar las credenciales sin codificarlas de forma fija en tu aplicación.

Según tu caso de uso, puedes configurar el administrador de autenticación para las siguientes situaciones:

Accede a herramientas personalizadas: Autentica al agente con claves de API o OAuth de 2 etapas (2LO) cuando el agente necesite acceder a una herramienta con su propia identidad y permisos.
Accede a las herramientas en nombre de un usuario: Autentica al agente que actúa como un usuario individual con OAuth de 3 segmentos (3LO). Este modelo se recomienda cuando el agente debe acceder a herramientas en nombre de la persona que interactúa con él, lo que requiere el consentimiento del usuario y el permiso delegado.

Estos modelos requieren que crees un proveedor de autenticación. Luego, creas una vinculación en el Registro de agentes para vincular el proveedor de autenticación a tus recursos del registro.

Después de configurar el proveedor de autenticación, el ADK administra el flujo de autenticación para tu orquestador. Para ver un ejemplo, consulta Cómo resolver vinculaciones en tu código del ADK.

Accede a herramientas personalizadas

Si quieres que tu agente se conecte a herramientas externas o personalizadas con sus propias credenciales, puedes configurar el administrador de autenticación para que controle las claves de API o el OAuth de 2 niveles (2LO):

Crea el proveedor de autenticación: Crea un proveedor de autenticación en el administrador de autenticación para almacenar la clave de API o las credenciales de OAuth. Para obtener información, consulta Autentica con OAuth de 2 segmentos con el administrador de autenticación o Autentica con una clave de API con el administrador de autenticación.
Vincula el proveedor de autenticación: Para permitir que tu agente de organización detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en Agent Registry entre tu agente, el recurso de destino y el proveedor de autenticación. Con las vinculaciones, no tienes que definir de forma manual los proveedores de autenticación en tu código:
gcloud
Ejecuta el comando gcloud agent-registry bindings create para crear una vinculación que asocie de forma explícita tu agente al recurso de destino y al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider-binding, debes usar el ID del proyecto de administración:
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
Configura el recurso google_agent_registry_binding para vincular tu agente y el recurso de destino al proveedor de autenticación:
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" } }
Reemplaza lo siguiente:
- BINDING_NAME: Es el ID único de la vinculación.
- PROJECT_ID: Es el ID del proyecto de administración.
- LOCATION: Es la región o ubicación del registro, como us-central1 o global.
- DISPLAY_NAME: Es un nombre visible legible para humanos para la vinculación.
- SOURCE_ID: Es el identificador del agente de origen en formato URN.
- TARGET_ID: Es el identificador de registro del servidor de MCP o extremo de destino en formato URN.
- AUTH_PROVIDER_ID: Es el ID de tu proveedor de autenticación.
Para obtener más información sobre cómo administrar estas conexiones, consulta Administra vinculaciones.

Accede a herramientas en nombre de un usuario

Si quieres que tu agente se autentique en servidores o herramientas de MCP remotos en nombre de un usuario individual, usa OAuth de 3 etapas (3LO) a través del administrador de autenticación.

El administrador de autenticación proporciona un servicio completamente administrado por Google para controlar los tokens de OAuth, el consentimiento del usuario y los redireccionamientos. Cuando un usuario final interactúa con el agente y activa una herramienta que requiere permisos delegados, la plataforma le solicita automáticamente el consentimiento al usuario, almacena las credenciales y reanuda el flujo de trabajo:

Crea el proveedor de autenticación: Crea un proveedor de autenticación en el administrador de autenticación y configura tus URIs de redireccionamiento de OAuth. Para obtener más información, consulta Autentica con OAuth de 3 segmentos con el administrador de autenticación.
Actualiza la aplicación cliente: Actualiza el cliente de tu aplicación para que controle la llamada a función adk_request_credential y administre el consentimiento del usuario. Para obtener instrucciones detalladas, consulta Actualiza tu aplicación del cliente.
Vincula el proveedor de autenticación: Para permitir que tu agente de organización detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en Agent Registry entre tu agente, el recurso de destino y el proveedor de autenticación. Con las vinculaciones, no tienes que definir de forma manual los proveedores de autenticación en tu código:
gcloud
Ejecuta el comando gcloud agent-registry bindings create para crear una vinculación que asocie de forma explícita tu agente al recurso de destino y al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider-binding, debes usar el ID del proyecto de administración:
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
Configura el recurso google_agent_registry_binding con tus permisos de OAuth 2.0 y el URI de continuación:
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" } }
Reemplaza lo siguiente:
- BINDING_NAME: Es el ID único de la vinculación.
- PROJECT_ID: Es el ID del proyecto de administración.
- LOCATION: Es la región o ubicación del registro, como us-central1 o global.
- DISPLAY_NAME: Es un nombre visible legible para humanos para la vinculación.
- SOURCE_ID: Es el identificador del agente de origen en formato URN.
- TARGET_ID: Es el identificador de registro del servidor de MCP o recurso de herramienta de destino en formato URN.
- AUTH_PROVIDER_ID: Es el ID de tu proveedor de autenticación.
- SCOPES: Es una lista separada por comas de permisos de OAuth 2.0, como https://www.googleapis.com/auth/cloud-platform. En Terraform, encierra cada permiso entre comillas dobles.
- REDIRECT_URI: Es el URI de redireccionamiento configurado para tu proveedor de autenticación después del consentimiento del usuario.
Para obtener más información sobre cómo administrar estas conexiones, consulta Administra vinculaciones.

Cómo resolver vinculaciones en tu código de ADK

Después de crear la vinculación del proveedor de autenticación en el registro de agentes, el ADK controla el flujo de autenticación.

Cuando usas el cliente AgentRegistry para recuperar un conjunto de herramientas de MCP, el ADK resuelve automáticamente cualquier vinculación asociada con ese servidor y aplica el esquema correcto. No es necesario que configures las credenciales en tu código de forma manual.

En el siguiente ejemplo, se muestra cómo recuperar un conjunto de herramientas de MCP autenticado y adjuntarlo a un agente:

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

Reemplaza SERVER_ID por el ID de tu servidor de MCP registrado.

Si configuras 3LO para acceder a herramientas en nombre de un usuario, también debes proporcionar continue_uri al método get_mcp_toolset. Este URI indica dónde se redirecciona al usuario final después de otorgar el consentimiento:

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

Reemplaza lo siguiente:

SERVER_ID: Es el ID de tu servidor de MCP registrado.
REDIRECT_URI: Es el URI de redireccionamiento de tu aplicación al que se envía al usuario después de otorgar el consentimiento.

Usa encabezados personalizados para herramientas externas

Si necesitas autenticar o pasar encabezados de la solicitud sin usar el administrador de autenticación, proporciona encabezados HTTP personalizados directamente en tus solicitudes de ADK.

Para configurar encabezados personalizados, proporciona una devolución de llamada header_provider cuando inicialices tu cliente AgentRegistry.

La devolución de llamada header_provider recibe el contexto de ejecución actual y devuelve un diccionario de encabezados HTTP. El componente McpToolset adjunta automáticamente estos encabezados a las solicitudes descendentes que se envían al servidor de MCP.

Los encabezados personalizados que proporciona la devolución de llamada header_provider solo se envían a los servidores de MCP de destino. Los encabezados personalizados no se usan para autenticar en la API de Agent Registry. La API siempre se basa en las ADC.

En este ejemplo, se muestra cómo proporcionar una clave de API o un token del portador personalizado para un conjunto de herramientas externo:

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)