Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Autenticación en herramientas y recursos

Cuando un agente de orquestador invoca un agente remoto o un conjunto de herramientas del Protocolo de contexto del modelo (MCP) descubierto a través de Agent Registry, debe autenticarse con el servicio Google Cloud subyacente que proporciona esas capacidades.

En este documento, se describe cómo controlar la autenticación de los recursos de Agent Registry.

Antes de comenzar

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

Configura Agent Registry en tu proyecto.
Instala o actualiza a la versión más reciente del ADK con las dependencias de A2A necesarias:
pip
pip install --upgrade "google-adk[a2a]"
uv
uv add "google-adk[a2a]"
Debes actualizar a google-adk>=1.29.0 como mínimo.
Para usar las credenciales predeterminadas de la aplicación (ADC) para la autenticación, configúralas:
```
gcloud auth application-default login
```
Las credenciales de ADC deben tener los permisos de IAM necesarios para los servicios subyacentes Google Cloud con los que interactúan los agentes o las herramientas.
Para seguir los ejemplos de esta guía, debes configurar variables de entorno, por ejemplo:
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY
```
Reemplaza lo siguiente:
- PROJECT_ID: ID del proyecto
- LOCATION: 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 información sobre los modelos de autenticación

Para administrar las credenciales, Agent Registry se basa en Agent Identity para la autenticación integrada y en el administrador de autenticación de Agent Identity para los proveedores de autenticación y las vinculaciones. Google Cloud

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

Como alternativa, para enviar contexto avanzado a un agente de destino o si los conjuntos de herramientas externas no admiten el administrador de autenticación de Agent Identity, puedes proporcionar encabezados HTTP personalizados directamente en tus solicitudes de ADK.

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

Usa Agent Identity para Google Cloud herramientas

Para los Google Cloud servicios, como Vertex AI 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 necesarios de Identity and Access Management para los servicios subyacentes Google Cloud . 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 orquestador 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().

Te recomendamos que definas un tiempo de espera personalizado para evitar exceder los límites de tiempo de espera predeterminados del cliente HTTP.

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

Autentica herramientas de MCP

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

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

Cuando tu agente necesita conectarse a APIs externas, herramientas personalizadas o servidores MCP externos, puedes usar el administrador de autenticación de Agent Identity para administrar las credenciales sin codificarlas de forma rígida 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 el agente con claves de API o OAuth de 2 segmentos (2LO) cuando el agente necesite acceder a una herramienta con su propia identidad y permisos.
Accede a herramientas en nombre de un usuario: Autentica el agente que actúa como un usuario individual con OAuth de 3 segmentos (3LO). Se recomienda este modelo cuando el agente debe acceder a las 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, crea una vinculación en Agent Registry para vincular el proveedor de autenticación a tus recursos de registro.

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

Accede a herramientas personalizadas

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

Crea el proveedor de autenticación: Crea un proveedor de autenticación en el administrador de autenticación de Agent Identity 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 orquestador detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en Agent Registry entre tu agente y el proveedor de autenticación. Con las vinculaciones, no tienes que definir manualmente los proveedores de autenticación en tu código.

Crea una vinculación para vincular de forma explícita tu agente al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider, debes usar el ID de tu proyecto:
```
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" \
```
Para obtener más información sobre la administración de estas conexiones, consulta Administra vinculaciones.

Accede a herramientas en nombre de un usuario

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

El administrador de autenticación proporciona un servicio completamente administrado por Google para controlar los tokens de OAuth, el consentimiento del usuario y las redirecciones. Cuando interactúas con el agente y activas una herramienta que requiere permisos delegados, la plataforma solicita automáticamente el consentimiento del 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 de Agent Identity y configura tus URIs de redireccionamiento de OAuth. Para obtener 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 controlar la llamada a función adk_request_credential y administrar 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 orquestador detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en Agent Registry entre tu agente y el proveedor de autenticación. Con las vinculaciones, no tienes que definir manualmente los proveedores de autenticación en tu código.

Crea una vinculación para vincular de forma explícita tu agente al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider, debes usar el ID de tu proyecto:
```
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" \
```
Para obtener más información sobre la administración de estas conexiones, consulta Administra vinculaciones.

Resuelve vinculaciones en tu código de ADK

Después de crear la vinculación del proveedor de autenticación en Agent Registry, 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 de forma manual en tu código.

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

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

[...]

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

Usa encabezados personalizados para herramientas externas

Para enviar contexto avanzado a un agente de destino o si los conjuntos de herramientas externas no admiten el administrador de autenticación de Agent Identity, puedes proporcionar encabezados HTTP personalizados directamente en tus solicitudes de ADK.

Configura encabezados personalizados proporcionando 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 muestra un diccionario de encabezados HTTP. El componente RemoteA2aAgent o McpToolset adjunta automáticamente estos encabezados a las solicitudes descendentes.

Los encabezados personalizados que proporciona la devolución de llamada header_provider solo se envían a los servicios de destino Google Cloud , que son los agentes o las herramientas. Los encabezados personalizados no se usan para autenticar con la API de Agent Registry. La API siempre se basa en ADC.

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

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)

¿Qué sigue?

Obtén información para usar Agent Gateway para aplicar controles de acceso y perímetros de red en tus solicitudes de herramientas autenticadas.