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

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

Para permitir que seus agentes façam a autenticação em ferramentas externas, como o Google Maps ou as APIs 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. Essa capacidade 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 agentes (ADK, na sigla em inglês), ele recupera e injeta automaticamente a chave de API nos cabeçalhos de invocação da ferramenta.

Antes de começar

Verifique se você escolheu o método de autenticação correto.
Ative a API Agent Identity Connector.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
Ativar a API
Crie e implante um agente.
Receba a chave de API do serviço de terceiros a que você quer se conectar.
Verifique se você tem as funções necessárias para concluir essa 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 criar provedores de autenticação:
- Administrador do conector do IAM (roles/iamconnectors.admin)
- Editor do conector do IAM (roles/iamconnectors.editor)
Para usar provedores de autenticação:
- Usuário do conector do IAM (roles/iamconnectors.user)
- Acesso padrão do agente (roles/aiplatform.agentDefaultAccess)
- Editor de contexto do agente (roles/aiplatform.agentContextEditor)
- Usuário da Vertex AI (roles/aiplatform.user)
- Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

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: iamconnectors.connectors.create
Para usar provedores de autenticação:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

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 Google Cloud console ou a Google Cloud CLI.

Console

No Google Cloud console, acesse a página Registro de agentes.
Acessar o Registro de agentes
Clique no nome do agente para o qual você quer criar um provedor de autenticação.
Clique em Identidade.
Na seção Provedores de autenticação, clique em Adicionar provedor de autenticação.
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 hífens, não pode terminar com um hífen e precisa começar com uma letra minúscula.
Na lista Tipo de OAuth, selecione Chave de API .
Clique em Criar e continuar.
Para conceder permissão de identidade do agente para usar o provedor de autenticação, clique em Conceder acesso.
Isso atribui automaticamente o papel Usuário do conector (roles/iamconnectors.user) à identidade do agente no recurso do provedor de autenticação.
Na seção Credenciais do provedor de autenticação, insira a chave de API.
Clique em Adicionar configuração do provedor.

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

Google Cloud CLI

Crie o provedor de autenticação:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --api-key="API_KEY"

Para conceder permissão de identidade do agente para usar provedores de autenticação, atualize a política de permissão do IAM para o projeto ou o provedor de autenticação específico e conceda o papel Usuário do conector (roles/iamconnectors.user) ao principal do agente.

A identidade do agente é baseada no formato de ID SPIFFE padrão do setor. Nas políticas de permissão do IAM, as identidades do agente são referenciadas usando identificadores principais.
Nível do projeto (gcloud)

A concessão do papel no nível do projeto permite que o agente use qualquer provedor de autenticação nesse projeto.
- Para conceder acesso de um único agente a provedores de autenticação em um projeto, execute o seguinte comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- Para conceder acesso de todos os agentes em um projeto a provedores de autenticação, execute o seguinte comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
Nível do conector (curl)

Para conceder acesso de um único agente a um provedor de autenticação específico, use a setIamPolicy API. Esse comando substitui qualquer política de permissão atual no recurso.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
Substitua:
- PROJECT_ID: o ID do projeto do Google Cloud .
- AUTH_PROVIDER_NAME: o nome do provedor de autenticação.
- ORGANIZATION_ID: o ID da sua Google Cloud organização.
- PROJECT_NUMBER: o número do seu projeto. Google Cloud
- LOCATION: o local do seu agente (por exemplo, us-central1).
- ENGINE_ID: o ID do seu mecanismo de raciocínio.

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.llm_agent import LlmAgent
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 the Google Cloud auth provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud auth provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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.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_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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

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

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

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

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_identity import 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
from google.adk.integrations.agent_registry import AgentRegistry

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

# Create Google Cloud auth provider scheme by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/PROJECT_ID/locations/global/mcpServers/agentregistry-00000000-0000-0000-0000-000000000000", auth_scheme=auth_scheme)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Implantar o agente

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

Se você estiver implantando no ambiente de execução do agente, use a flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# 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")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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]"],
    },
)