Autenticar usando a chave de API com o gerenciador de autenticação

Para permitir que seus agentes se autentiquem em ferramentas externas, como as APIs do Google Maps ou Weather, configure a autenticação de saída usando provedores de autenticação de chave de API no gerenciador de autenticação de Identidade do Agente.

Os provedores de autenticação de chave de API gerenciam suas chaves criptográficas para você. Esse recurso elimina a necessidade de codificar chaves no código do agente ou gerenciá-las manualmente.

Fluxo de trabalho da chave de API

Os provedores de autenticação de chave de API usam a identidade do agente e não exigem o consentimento do usuário. O Google toma medidas para ajudar a proteger a chave de API durante o armazenamento. Quando você usa o Kit de Desenvolvimento de Agente (ADK), ele recupera e injeta automaticamente a chave de API nos cabeçalhos de invocação da ferramenta.

Antes de começar

  1. Verifique se você escolheu o método de autenticação correto.

  2. Ative a API Agent Identity, se ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  3. Criar e implantar um agente.

  4. Consiga uma chave de API do serviço de terceiros ao qual você quer se conectar.

  5. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

Para receber as permissões necessárias para criar e usar um provedor de autenticação de chave de API, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar e usar um provedor de autenticação de chave de API. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar e usar um provedor de autenticação de chave de API:

  • Para criar provedores de autenticação: agentidentity.authProviders.create
  • Para usar provedores de autenticação:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Receber uma chave de API do serviço de terceiros

Antes de criar um provedor de autenticação, receba uma chave de API do serviço de terceiros ao qual você quer que o agente se conecte.

Se você estiver se conectando a um serviço de terceiros fora do Google Cloud, consiga a chave de API no portal do desenvolvedor desse serviço e pule as etapas desta seção.

Se você estiver se conectando aos serviços do Google Cloud (como o Cloud Translation ou o Google Maps), gere e configure uma chave de API seguindo estas etapas:

  1. No console do Google Cloud , ative os serviços de API necessários para seu projeto:

    1. No console do Google Cloud , acesse a página APIs e serviços > Biblioteca.

      Acesse APIs e serviços > Biblioteca

    2. Pesquise e ative as APIs que seu agente usa, como a API Cloud Translation ou a API Weather do Google Maps.
    3. Copie a string da chave de API gerada.

  2. Configure sua chave de API:

    1. No console do Google Cloud , acesse a página APIs e serviços > Credenciais.

      Acesse APIs e serviços > Credenciais

    2. Clique em Criar credenciais > Chave de API.
    3. Na caixa de diálogo Criar chave de API, faça o seguinte:
      1. Insira um nome exclusivo para a chave de API.
      2. Para restringir a chave às APIs específicas que você ativou, selecione essas APIs na lista Selecionar restrições da API.
      3. Opcional: na seção Restrinja sua chave para reduzir os riscos de segurança, selecione um tipo de aplicativo para restringir o acesso.
      4. Clique em Criar.

  3. Valide sua chave de API enviando uma solicitação de teste para o endpoint do serviço.

    • Para verificar uma chave de API Cloud Translation, execute o seguinte comando:

      curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -d '{"q": "Hello world", "target": "es"}' \
  "https://translation.googleapis.com/language/translate/v2"

      Substitua YOUR_API_KEY pela chave de API que você gerou.

    • Para verificar uma chave de API Google Maps Weather, execute o seguinte comando:

      curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"

      Substitua YOUR_API_KEY pela chave de API que você gerou.

    Se a chave de API for válida e estiver configurada corretamente, o serviço vai retornar os dados solicitados.

Criar um provedor de autenticação de chave de API

Crie um provedor de autenticação para definir a configuração e as credenciais de aplicativos de terceiros.

Para criar um provedor de autenticação de chave de API, use o console do Google Cloud , a Google Cloud CLI ou a API REST.

Console

  1. No console do Google Cloud , acesse a página Agent Registry.

    Acessar o Agent Registry

  2. Clique no nome do agente para o qual você quer criar um provedor de autenticação.
  3. Clique em Identidade.
  4. Na seção Provedores de autenticação, clique em Adicionar provedor de autenticação.

  5. No painel Adicionar provedor de autenticação, insira um nome e uma descrição.

    O nome só pode conter letras minúsculas, números ou hifens, não pode terminar com um hífen e precisa começar com uma letra minúscula.

  6. Na lista Tipo de OAuth, selecione Chave de API .
  7. Clique em Criar e continuar.
  8. Para conceder à identidade do agente permissão para usar o provedor de autenticação, clique em Conceder acesso.

    Esse processo atribui automaticamente o papel de Usuário de identidade do agente (roles/agentidentity.user) à identidade do agente no recurso do provedor de autenticação.

  9. Na seção Credenciais do provedor de autenticação, insira a chave de API.
  10. Clique em Adicionar configuração do provedor.

O provedor de autenticação recém-criado aparece na lista Provedores de autenticação.

CLI da gcloud

  1. Crie o provedor de autenticação:

    gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --api-key="API_KEY"
  2. Verifique se o provedor de autenticação aparece na lista e se o estado dele é ENABLED: 
    gcloud agent-identity auth-providers list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  3. Conceda permissões de acesso para permitir que seu agente e ambiente de desenvolvimento local recuperem credenciais do provedor de autenticação. Para permitir que o agente implantado e sua conta de usuário pessoal acessem o provedor de autenticação, conceda o papel de Usuário de identidade do agente (roles/agentidentity.user) no recurso do provedor de autenticação:

    1. Conceda acesso ao ID do SPIFFE do agente implantado (identidade do agente):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

    2. Conceda acesso à sua conta de usuário pessoal para desenvolvimento e testes locais (adk web):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="user:USER_EMAIL"

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o local em que o provedor de autenticação e o agente estão implantados (por exemplo, us-west1).
  • AUTH_PROVIDER_NAME: o nome do provedor de autenticação (por exemplo, maps-api-key-authprovider).
  • API_KEY: a chave de API que você gerou no serviço de terceiros.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • ENGINE_ID: o ID do agente do mecanismo de raciocínio implantado.
  • USER_EMAIL: o endereço de e-mail da sua conta de usuário pessoal.

REST

  1. Crie o provedor de autenticação:

    O método authProviders.create da API Agent Identity cria um provedor de autenticação de chave de API em um projeto e local.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto do Google Cloud . Os IDs do projeto são strings alfanuméricas, como my-project.
    • LOCATION: o local em que o provedor de autenticação e o agente estão implantados (por exemplo, us-west1).
    • AUTH_PROVIDER_NAME: o nome do provedor de autenticação (por exemplo, maps-api-key-authprovider). O nome pode conter apenas letras minúsculas, números ou hifens, não pode terminar com um hífen e precisa começar com uma letra minúscula.
    • API_KEY: a chave de API que você gerou no serviço de terceiros.

    Método HTTP e URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

    Corpo JSON da solicitação:

    {
  "authProviderTypeParams": {
    "apiKey": {
      "apiKey": "API_KEY"
    }
  }
}

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "name": "projects/my-project/locations/us-west1/authProviders/maps-api-key-authprovider",
  "createTime": "2026-04-03T21:15:41.367155Z",
  "updateTime": "2026-04-03T21:15:41.367155Z",
  "authProviderTypeParams": {
    "apiKey": {}
  },
  "state": "ENABLED"
}

  2. Para permitir que o agente implantado e sua conta de usuário pessoal recuperem credenciais do provedor de autenticação, conceda o papel de Usuário de identidade do agente (roles/agentidentity.user) no recurso do provedor de autenticação:

    O método authProviders.setIamPolicy da API Agent Identity define a política de permissão no recurso do provedor de autenticação.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto do Google Cloud . Os IDs do projeto são strings alfanuméricas, como my-project.
    • LOCATION: o local em que o provedor de autenticação e o agente estão implantados (por exemplo, us-west1).
    • AUTH_PROVIDER_NAME: o nome do provedor de autenticação.
    • ORGANIZATION_ID: o ID da organização do Google Cloud.
    • PROJECT_NUMBER: o número numérico do projeto do Google Cloud em que o agente está implantado (por exemplo, 987654321098).
    • ENGINE_ID: o ID do agente do mecanismo de raciocínio implantado.
    • USER_EMAIL: o endereço de e-mail da sua conta de usuário pessoal.

    Método HTTP e URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

    Corpo JSON da solicitação:

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/agentidentity.user",
        "members": [
          "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
          "user:USER_EMAIL"
        ]
      }
    ]
  }
}

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "version": 1,
  "etag": "BwYKmjvelug=",
  "bindings": [
    {
      "role": "roles/agentidentity.user",
      "members": [
        "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
        "user:alex@example.com"
      ]
    }
  ]
}

Autenticar no código do agente

Para autenticar seu agente, use o ADK.

ADK

Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas do MCP no ADK.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Google Cloud auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Exemplo: conexão com o MCP do Google Maps

O exemplo a seguir demonstra uma configuração agent.py que conecta um agente a um servidor MCP do Google Maps:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

maps_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://mapstools.googleapis.com/mcp"),
    auth_scheme=maps_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful "
        "information. You can also use your Google Maps tools to look up "
        "locations and directions."
    ),
    tools=[maps_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Faça referência ao provedor de autenticação no código do agente usando uma ferramenta de função autenticada no ADK.

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

Exemplo: como se conectar à API Weather do Google Maps

O exemplo a seguir demonstra uma configuração de agent.py que conecta um agente à API Weather do Google Maps usando uma ferramenta de função autenticada:

import os
import httpx
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

weather_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets current weather conditions for a location."""
    api_key = None
    if http := credential.http:
        if http.additional_headers and "X-GOOG-API-KEY" in http.additional_headers:
            api_key = http.additional_headers["X-GOOG-API-KEY"]
        elif http.credentials and http.credentials.token:
            api_key = http.credentials.token

    if not api_key:
        return "Error: No API key available from the auth provider."

    params = {"location.latitude": latitude, "location.longitude": longitude, "key": api_key}
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://weather.googleapis.com/v1/currentConditions:lookup",
            params=params,
        )
        if response.status_code != 200:
            return f"Error from Weather API: {response.status_code} - {response.text}"
        return response.json()

get_weather_tool = AuthenticatedFunctionTool(
    func=get_weather, auth_config=weather_auth_config
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant. You will use your weather tool to "
        "look up current conditions."
    ),
    tools=[get_weather_tool],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas MCP do Agent Registry no ADK.

Não é necessário criar um esquema de autenticação para esse fluxo. A vinculação de saída do servidor MCP já registra qual provedor de autenticação usar.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se a identidade do agente está ativada.

CLI do agente

Se você estiver usando o Kit de Desenvolvimento de Agente (ADK) e a Agents CLI, faça o seguinte para implantar o agente com a Identidade do Agente ativada:

  1. Na pasta do aplicativo do agente, crie um arquivo de configuração chamado .agent_engine_config.json para ativar a identidade do agente:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. Implante seu agente no Agent Runtime na Gemini Enterprise Agent Platform: 

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Substitua:

    • AGENT_NAME: o nome da pasta do aplicativo do agente (por exemplo, maps_agent).
    • PROJECT_ID: o ID do projeto do Google Cloud.
    • LOCATION: a região com disponibilidade em que você quer implantar o agente (por exemplo, us-west1).

SDK do Python

Se você estiver implantando de forma programática usando o SDK da Vertex AI para Python, use a flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região com disponibilidade em que você quer implantar o agente (por exemplo, us-west1).

A seguir