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

Autenticar ferramentas e recursos

Quando um agente orquestrador invoca um agente remoto ou um conjunto de ferramentas do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) descoberto pelo Agent Registry, ele precisa se autenticar com o serviço Google Cloud subjacente que fornece esses recursos.

Este documento descreve como processar a autenticação de recursos do Agent Registry.

Antes de começar

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

Configure o Agent Registry no seu projeto.
Instale ou faça upgrade para a versão mais recente do ADK com as dependências A2A necessárias:
pip
pip install --upgrade "google-adk[a2a]"
uv
uv add "google-adk[a2a]"
É necessário fazer upgrade para pelo menos google-adk>=1.29.0.
Para usar as Application Default Credentials (ADC) na autenticação, configure-as:
```
gcloud auth application-default login
```
As credenciais do ADC precisam ter as permissões do IAM necessárias para os serviços subjacentes Google Cloud com que os agentes ou ferramentas interagem.
Para seguir os exemplos neste guia, configure variáveis de ambiente, por exemplo:
```
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 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 depende de Identidade do Agente para autenticação Google Cloud integrada e do 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 própria identidade do agente é fornecida pelas Application Default Credentials (ADC) , seja usando a identidade do agente ou contas de serviço.

Como alternativa, para enviar um contexto avançado a um agente de destino ou se os conjuntos de ferramentas externas não forem compatíveis com o gerenciador de autenticação de identidade do agente, você poderá fornecer 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 Google Cloud ferramentas

Para Google Cloud serviços, 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 agente precisa ter as permissões do Identity and Access Management necessárias para os serviços subjacentes Google Cloud . Por exemplo, se uma ferramenta do MCP gerenciar instâncias de VM do Compute Engine, a identidade do agente precisará ter papéis como Administrador da instância do Compute (v1) ou superior, além do papel de Leitor da API do Agent Registry.

Autenticar agentes A2A remotos

Se o agente orquestrador estiver se conectando a um agente Google Agent2Agent (A2A) remoto usando a própria identidade, você precisará incluir explicitamente httpx.AsyncClient configurado com os 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 de tempo limite do cliente HTTP padrão.

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 do 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, você pode usar 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:

Acessar ferramentas personalizadas: autentique o agente com chaves de API ou OAuth de duas etapas (2LO) quando ele 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 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 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):

Criar 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.
Vincular 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 Agent Registry entre o agente e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente os provedores de autenticação no código.

Crie uma vinculação para vincular explicitamente o 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 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 de identidade do agente.

O gerenciador de autenticação fornece 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 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 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.
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 permitir que o agente orquestrador detecte o provedor de autenticação correto para um destino, crie uma vinculação no Agent Registry entre o agente e o provedor de autenticação. Com as vinculações, não é necessário definir manualmente os provedores de autenticação no código.

Crie uma vinculação para vincular explicitamente o 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 as credenciais no código.

O exemplo a seguir demonstra como buscar um conjunto de ferramentas do 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 após conceder o 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 um contexto avançado a um agente de destino ou se os conjuntos de ferramentas externas não forem compatíveis com o gerenciador de autenticação de identidade do agente, você poderá fornecer 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 header_provider callback são enviados apenas aos serviços de destino Google Cloud , que são os agentes ou ferramentas. Os cabeçalhos personalizados não são usados para autenticar a própria API do 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 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)

A seguir

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