Autenticar ferramentas e recursos

Quando um agente orquestrador invoca um agente remoto ou um conjunto de ferramentas do Protocolo de Contexto de Modelo (MCP) descoberto pelo Registro de agentes, ele precisa se autenticar com o serviço subjacente que fornece essas funcionalidades.

Neste documento, descrevemos como processar a autenticação para recursos do Agent Registry.

Antes de começar

Antes de fazer a autenticação em ferramentas e recursos, faça o seguinte:

  1. Configure o Agent Registry no projeto.

  2. Instale ou faça upgrade para a versão mais recente do Kit de Desenvolvimento de Agente (ADK):

    pip install --upgrade google-adk

    É necessário fazer upgrade para pelo menos google-adk>=1.29.0.

  3. Para usar o Application Default Credentials (ADC) para autenticação, configure-o:

    gcloud auth application-default login

    As credenciais do ADC precisam ter as permissões do IAM necessárias para os serviços subjacentes com que os agentes ou ferramentas interagem.

  4. Para seguir os exemplos neste guia, configure variáveis de ambiente, como:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • LOCATION: a região ou o local do registro, como us-central1.
    • EXTERNAL_API_KEY: se você estiver usando cabeçalhos personalizados, sua chave de API externa.

Saiba mais sobre os modelos de autenticação

Para gerenciar credenciais, o Agent Registry usa a identidade do agente para autenticação Google Cloud integrada e o gerenciador de autenticação de identidade do agente para provedores de autenticação e vinculações.

Seus agentes podem usar a própria identidade ou o gerenciador de autenticação para acessar ferramentas usando chaves de API ou OAuth. A identidade do agente é fornecida por Application Default Credentials (ADC), seja usando a identidade do agente ou contas de serviço.

Como alternativa, para enviar contexto avançado a um agente de destino ou se conjuntos de ferramentas externos não forem compatíveis com o gerenciador de autenticação de identidade do agente, forneça cabeçalhos HTTP personalizados diretamente nas solicitações do ADK.

Para determinar a melhor abordagem para seu caso de uso, consulte Modelos de autenticação.

Usar a identidade do agente para ferramentas Google Cloud

Para serviços do Google Cloud , como a Vertex AI ou o Cloud Storage, o agente usa a própria identidade para acessar as ferramentas. Esse acesso é gerenciado pelas Application Default Credentials (ADC), seja usando a identidade do agente ou contas de serviço.

A identidade associada ao seu agente precisa ter as permissões necessárias do Identity and Access Management para os serviços subjacentes. Por exemplo, se uma ferramenta do MCP gerencia instâncias de VM do Compute Engine, a identidade do agente precisa ter papéis como Administrador da instância do Compute (v1) ou superior, além do papel Leitor da API Agent Registry.

Autenticar agentes A2A remotos

Se o agente orquestrador estiver se conectando a um agente remoto do Google Agent2Agent (A2A) usando a própria identidade, inclua explicitamente httpx.AsyncClient configurado com seus cabeçalhos de autenticação do Google no método get_remote_a2a_agent().

Recomendamos definir um tempo limite personalizado para evitar exceder os limites padrão de tempo limite do cliente HTTP.

O exemplo a seguir mostra como configurar o httpx.AsyncClient com ADC e um tempo limite 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,
)

Autenticar ferramentas do MCP

Se o agente orquestrador usar a própria identidade para acessar um conjunto de ferramentas do MCP, você poderá inicializar o cliente de registro usando o ADC e o 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)

Usar o gerenciador de autenticação para ferramentas personalizadas e acesso delegado

Quando o agente precisa se conectar a APIs externas, ferramentas personalizadas ou servidores MCP externos, use o gerenciador de autenticação de identidade do agente para gerenciar credenciais sem codificá-las no aplicativo.

Dependendo do seu caso de uso, é possível configurar o gerenciador de autenticação para os seguintes cenários:

Para usar esses modelos, é necessário criar um provedor de autenticação. Em seguida, crie uma vinculação no Agent Registry para vincular o provedor de autenticação aos recursos do seu registro.

Depois de configurar o provedor de autenticação, o ADK gerencia o fluxo de autenticação do seu orquestrador. Para um exemplo, consulte Resolver vinculações no código do ADK.

Acessar ferramentas personalizadas

Se você quiser que o agente se conecte a ferramentas externas ou personalizadas usando as próprias credenciais, configure o gerenciador de autenticação de identidade do agente para processar chaves de API ou OAuth de duas etapas (2LO):

  1. Crie o provedor de autenticação:crie um provedor de autenticação no gerenciador de autenticação de identidade do agente para armazenar a chave de API ou as credenciais do OAuth. Para mais informações, consulte Autenticar usando o OAuth de duas etapas com o gerenciador de autenticação ou Autenticar usando uma chave de API com o gerenciador de autenticação.

  2. Vincule o provedor de autenticação:para permitir que o agente orquestrador detecte o provedor de autenticação correto para um destino, crie uma vinculação no Registro de agentes entre seu agente e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente provedores de autenticação no código.

    Crie uma vinculação para vincular explicitamente seu agente ao provedor de autenticação. Ao especificar o nome do recurso --auth-provider, use o ID do projeto:

    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 mais informações sobre como gerenciar essas conexões, consulte Gerenciar vinculações.

Acessar ferramentas em nome de um usuário

Se você quiser que seu agente se autentique em servidores ou ferramentas remotos do MCP em nome de um usuário individual, use o OAuth de três etapas (3LO) pelo gerenciador de autenticação de identidade do agente.

O gerenciador de autenticação oferece um serviço totalmente gerenciado pelo Google para processar tokens OAuth, consentimento do usuário e redirecionamentos. Quando você interage com o agente e aciona uma ferramenta que exige permissões delegadas, a plataforma automaticamente pede o consentimento do usuário, armazena as credenciais e retoma o fluxo de trabalho:

  1. Crie o provedor de autenticação:crie um provedor de autenticação no gerenciador de autenticação de identidade do agente e configure os URIs de redirecionamento do OAuth. Para mais informações, consulte Autenticar usando o OAuth de três etapas com o gerenciador de autenticação.
  2. Atualize o aplicativo cliente:atualize o cliente do aplicativo para processar a chamada de função adk_request_credential e gerenciar o consentimento do usuário. Para instruções detalhadas, consulte Atualizar o aplicativo do lado do cliente.

  3. Vincule o provedor de autenticação:para permitir que o agente orquestrador detecte o provedor de autenticação correto para um destino, crie uma vinculação no Registro de agentes entre seu agente e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente provedores de autenticação no código.

    Crie uma vinculação para vincular explicitamente seu agente ao provedor de autenticação. Ao especificar o nome do recurso --auth-provider, use o ID do projeto:

    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 mais informações sobre como gerenciar essas conexões, consulte Gerenciar vinculações.

Resolver vinculações no código do ADK

Depois de criar a vinculação do provedor de autenticação no Agent Registry, o ADK processa o fluxo de autenticação.

Quando você usa o cliente AgentRegistry para buscar um conjunto de ferramentas do MCP, o ADK resolve automaticamente todas as vinculações associadas a esse servidor e aplica o esquema correto. Não é necessário configurar manualmente credenciais no código.

O exemplo a seguir demonstra como buscar um conjunto de ferramentas MCP autenticado e anexá-lo a um 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],
)

Se você configurar o 3LO para acessar ferramentas em nome de um usuário, também precisará fornecer continue_uri ao método get_mcp_toolset. Esse URI indica para onde o usuário é redirecionado depois de dar consentimento:

[...]

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

Usar cabeçalhos personalizados para ferramentas externas

Para enviar contexto avançado a um agente de destino ou se conjuntos de ferramentas externos não forem compatíveis com o gerenciador de autenticação de identidade do agente, forneça cabeçalhos HTTP personalizados diretamente nas solicitações do ADK.

Configure cabeçalhos personalizados fornecendo um callback header_provider ao inicializar o cliente AgentRegistry.

O callback header_provider recebe o contexto de execução atual e retorna um dicionário de cabeçalhos HTTP. O componente RemoteA2aAgent ou McpToolset anexa automaticamente esses cabeçalhos às solicitações downstream.

Os cabeçalhos personalizados fornecidos pelo callback header_provider são enviados apenas para os serviços de destino, que são os agentes ou as ferramentas. Os cabeçalhos personalizados não são usados para autenticar na própria API Agent Registry. A API sempre depende do ADC.

Este exemplo mostra como fornecer uma chave de API ou um token de autenticação personalizado para um conjunto de ferramentas 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)

A seguir

  • Saiba como usar o Agent Gateway para aplicar controles de acesso e perímetros de rede às solicitações de ferramentas autenticadas.