O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Autenticar ferramentas e recursos

O Agent Registry permite que seus agentes orquestradores se autentiquem com segurança em agentes remotos descobertos, conjuntos de ferramentas do Protocolo de Contexto de Modelo (MCP) e serviços doGoogle Cloud . Usando a Identidade do Agente e o gerenciador de autenticação de Identidade do Agente, é possível configurar credenciais, vinculações e cabeçalhos HTTP personalizados ao invocar recursos descobertos pelo Agent Registry.

Antes de começar

Antes de se autenticar em ferramentas e recursos, faça o seguinte:

Configure o Agent Registry.
Consiga o ID do projeto para o projeto de governança em que o Agent Registry está ativado.
Instale ou faça upgrade para a versão mais recente do Kit de Desenvolvimento de Agente (ADK) com as dependências de A2A, identidade do agente e MCP:
pip
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
uv
uv add "google-adk[a2a,agent-identity,mcp]"
É necessário fazer upgrade para pelo menos google-adk>=1.29.0.
Para usar o Application Default Credentials (ADC) na autenticação, configure-o:
```
gcloud auth application-default login
```
As credenciais do ADC precisam ter as permissões necessárias do Identity and Access Management (IAM) para os serviços do Google Cloud com que os agentes ou as ferramentas interagem.
Configure as seguintes variáveis de ambiente:
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
export API_KEY=EXTERNAL_API_KEY
```
Substitua:
- PROJECT_ID: o ID do projeto de governança.
- 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 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 o OAuth 2.0. A identidade do agente é fornecida pelo Application Default Credentials (ADC), seja usando a identidade do agente ou contas de serviço.

Se você precisar se autenticar sem usar o gerenciador de autenticação, forneça cabeçalhos HTTP personalizados diretamente nas suas 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 do Google Cloud

Para serviços do Google Cloud , como o Agent Runtime na Gemini Enterprise Agent Platform ou o Cloud Storage, o agente usa a própria identidade para acessar as ferramentas. Esse acesso é gerenciado pelo Application Default Credentials (ADC), seja usando a identidade do agente ou contas de serviço.

A identidade associada ao agente precisa ter as permissões do IAM necessárias para os serviços do Google Cloud subjacentes. Por exemplo, se uma ferramenta 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 de 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 os cabeçalhos de autenticação do Google no método get_remote_a2a_agent().

Para evitar exceder os limites de tempo limite padrão do cliente HTTP, defina um tempo limite personalizado.

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

Substitua AGENT_ID pelo ID do agente registrado.

Autenticar ferramentas do MCP

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

Substitua SERVER_ID pelo ID do servidor MCP registrado.

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 para gerenciar as 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:

Acessar ferramentas personalizadas: autentique o agente com chaves de API ou OAuth de duas etapas (2LO) quando o agente precisar acessar uma ferramenta usando a própria identidade e permissões.
Acessar ferramentas em nome de um usuário: autentique o agente que atua como um usuário individual com o OAuth de três etapas (3LO). Esse modelo é recomendado quando o agente precisa acessar ferramentas em nome da pessoa que interage com ele, exigindo o consentimento do usuário e permissão delegada.

Esses modelos exigem que você crie um provedor de autenticação. Em seguida, crie uma vinculação no Agent Registry para vincular o provedor de autenticação aos recursos do registro.

Depois de configurar o provedor de autenticação, o ADK gerencia o fluxo de autenticação do seu orquestrador. Para ver 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 para processar chaves de API ou OAuth de duas etapas (2LO):

Criar o provedor de autenticação: crie um provedor de autenticação no gerenciador de autenticação 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 a chave de API com o gerenciador de autenticação.
Vincular o provedor de autenticação: para que o agente orquestrador detecte o provedor de autenticação correto para um destino, crie uma vinculação no Agent Registry entre o agente, o recurso de destino e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente os provedores de autenticação no seu código:
gcloud
Crie uma vinculação para associar explicitamente o agente ao recurso de destino e ao provedor de autenticação executando o comando gcloud agent-registry bindings create. Ao especificar o nome do recurso --auth-provider-binding, use o ID do projeto de governança:
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
Configure o recurso google_agent_registry_binding para vincular o agente e o recurso de destino ao provedor de autenticação:
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" } }
Substitua:
- BINDING_NAME: o ID exclusivo da vinculação.
- PROJECT_ID: o ID do projeto de governança.
- LOCATION: a região ou o local do registro, como us-central1 ou global.
- DISPLAY_NAME: um nome de exibição legível por humanos para a vinculação.
- SOURCE_ID: o identificador do agente de origem no formato URN.
- TARGET_ID: o identificador de registro do servidor MCP ou endpoint de destino no formato URN.
- AUTH_PROVIDER_ID: o ID do seu provedor de autenticação.
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 o agente se autentique em servidores ou ferramentas MCP remotos em nome de um usuário individual, use o OAuth de três etapas (3LO) pelo gerenciador de autenticação.

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

Criar o provedor de autenticação: crie um provedor de autenticação no gerenciador de autenticação 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.
Atualizar 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.
Vincular o provedor de autenticação: para que o agente orquestrador detecte o provedor de autenticação correto para um destino, crie uma vinculação no Agent Registry entre o agente, o recurso de destino e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente os provedores de autenticação no seu código:
gcloud
Crie uma vinculação para associar explicitamente o agente ao recurso de destino e ao provedor de autenticação executando o comando gcloud agent-registry bindings create. Ao especificar o nome do recurso --auth-provider-binding, use o ID do projeto de governança:
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
Configure o recurso google_agent_registry_binding com os escopos do OAuth 2.0 e o URI de continuação:
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" } }
Substitua:
- BINDING_NAME: o ID exclusivo da vinculação.
- PROJECT_ID: o ID do projeto de governança.
- LOCATION: a região ou o local do registro, como us-central1 ou global.
- DISPLAY_NAME: um nome de exibição legível por humanos para a vinculação.
- SOURCE_ID: o identificador do agente de origem no formato URN.
- TARGET_ID: o identificador de registro do servidor MCP de destino ou do recurso de ferramenta no formato URN.
- AUTH_PROVIDER_ID: o ID do seu provedor de autenticação.
- SCOPES: uma lista separada por vírgulas de escopos do OAuth 2.0, como https://www.googleapis.com/auth/cloud-platform. No Terraform, coloque cada escopo entre aspas duplas.
- REDIRECT_URI: o URI de redirecionamento configurado para seu provedor de autenticação após o consentimento do usuário.
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 as 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],
)

Substitua SERVER_ID pelo ID do servidor MCP registrado.

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

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

Substitua:

SERVER_ID: o ID do servidor MCP registrado.
REDIRECT_URI: o URI de redirecionamento do aplicativo para onde o usuário é enviado depois de conceder o consentimento.

Usar cabeçalhos personalizados para ferramentas externas

Se você precisar autenticar ou transmitir cabeçalhos da solicitação sem usar o gerenciador de autenticação, 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 McpToolset anexa automaticamente esses cabeçalhos às solicitações downstream enviadas ao servidor MCP.

Os cabeçalhos personalizados fornecidos pelo callback header_provider são enviados apenas para os servidores MCP de destino. Os cabeçalhos personalizados não são usados para autenticação na API Agent Registry. A API sempre depende do ADC.

Este exemplo demonstra como fornecer uma chave de API ou um token do portador 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 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)