Autenticación en herramientas y recursos

Cuando un agente orquestador invoca un agente remoto o un conjunto de herramientas del Protocolo de contexto del modelo (MCP) descubierto a través del Registro de agentes, debe autenticarse con el servicio 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 los siguientes pasos:

  1. Configura Agent Registry en tu proyecto.

  2. Instala o actualiza a la versión más reciente del Kit de desarrollo de agentes (ADK):

    pip install --upgrade google-adk

    Debes actualizar a la versión google-adk>=1.29.0 como mínimo.

  3. Para usar las credenciales predeterminadas de la aplicación (ADC) para la autenticación, configúralas de la siguiente manera:

    gcloud auth application-default login

    Las credenciales del ADC deben tener los permisos de IAM necesarios para los servicios subyacentes con los que interactúan los agentes o las herramientas.

  4. 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: el ID de tu proyecto
    • LOCATION: Es la región o ubicación del registro, como us-central1.
    • EXTERNAL_API_KEY: Si usas encabezados personalizados, es tu clave de API externa.

Más información sobre los modelos de autenticación

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

Tus agentes pueden usar su propia identidad o el administrador de autorización para acceder a herramientas con claves de API o OAuth. 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 cuentas de servicio.

Como alternativa, para enviar contexto avanzado a un agente objetivo o si los conjuntos de herramientas externos no admiten el administrador de autenticación de identidad del agente, puedes proporcionar 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 Agent Identity para las herramientas de Google Cloud

En el caso de los servicios, como Vertex AI o Cloud Storage, tu agente usa su propia identidad para acceder a las herramientas. Google Cloud Este acceso se administra 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.

La identidad asociada con tu agente debe tener los permisos necesarios de Identity and Access Management para los servicios 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 del registro de agentes.

Autentica agentes A2A remotos

Si tu agente de orquestació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().

Recomendamos definir un tiempo de espera personalizado para evitar superar 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 orquestación 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 autorización para herramientas personalizadas y acceso delegado

Cuando tu agente necesita conectarse a APIs externas, herramientas personalizadas o servidores de MCP externos, puedes usar el administrador de autenticación de identidad del agente 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:

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 los recursos del 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 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 de identidad del agente para que controle las claves de API o el protocolo OAuth de 2 segmentos (2LO):

  1. 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 más 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.

  2. Vincula el proveedor de autenticación: Para permitir que tu agente orquestador detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en el Registro de agentes 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 explícitamente tu agente al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider, debes usar tu ID del 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 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 segmentos (3LO) a través del administrador de autenticación de identidad del agente.

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

  1. 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 más información, consulta Cómo autenticar con OAuth de 3 segmentos con el administrador de autorización.
  2. 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 Cómo actualizar tu aplicación del cliente.

  3. Vincula el proveedor de autenticación: Para permitir que tu agente orquestador detecte el proveedor de autenticación correcto para un destino, debes crear una vinculación en el Registro de agentes 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 explícitamente tu agente al proveedor de autenticación. Cuando especifiques el nombre del recurso --auth-provider, debes usar tu ID del 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 cómo administrar estas conexiones, consulta Administra vinculaciones.

Cómo resolver vinculaciones en tu código del 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 de 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 manualmente 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 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 objetivo o si los conjuntos de herramientas externos no admiten el administrador de autenticación de identidad del agente, puedes proporcionar encabezados HTTP personalizados directamente en tus solicitudes del 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 devuelve un diccionario de encabezados HTTP. El componente RemoteA2aAgent o McpToolset adjunta automáticamente estos encabezados a las solicitudes posteriores.

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

En este ejemplo, se muestra cómo proporcionar una clave de API o un token de 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 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?

  • Aprende a usar Agent Gateway para aplicar controles de acceso y perímetros de red en tus solicitudes de herramientas autenticadas.