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

Autenticar usando o OAuth de duas etapas com o gerenciador de autenticação

Para permitir que os agentes façam a autenticação em ferramentas externas, como ServiceNow ou Salesforce, usando a própria autoridade, configure a autenticação de saída usando provedores de autenticação OAuth de duas etapas (credenciais do cliente) no gerenciador de autenticação do Agent Identity.

Ao gerenciar credenciais e tokens, os provedores de autenticação OAuth de duas etapas eliminam a necessidade de código personalizado para processar fluxos de autenticação.

Fluxo de trabalho do OAuth de duas etapas

Os provedores de autenticação OAuth de duas etapas usam a identidade do agente e não exigem o consentimento do usuário. O Google gerencia o armazenamento das credenciais do cliente. Quando você usa o Kit de desenvolvimento de agentes (ADK, na sigla em inglês), ele recupera e injeta automaticamente os tokens de acesso resultantes 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.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
Ativar a API
Crie e implante um agente.
Receba o ID do cliente e a chave secreta do cliente do aplicativo de terceiros que você quer conectar.
Verifique se você tem os papéis necessários para concluir essa tarefa.

Funções exigidas

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

Para criar provedores de autenticação:
- Administrador do Agent Identity (roles/agentidentity.admin)
- Editor do Agent Identity (roles/agentidentity.editor)
Para usar provedores de autenticação:
- Usuário do Agent Identity (roles/agentidentity.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 do Agent Identity de duas etapas. Para acessar as permissões exatas que são 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 do Agent Identity de duas etapas:

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 papéis personalizados ou outros papéis predefinidos.

Criar um provedor de autenticação de duas etapas

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 duas etapas, use a CLI gcloud:

Crie o provedor de autenticação:

gcloud alpha agent-identity authProviders create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

Verifique se o provedor de autenticação aparece na lista e se o estado dele é ENABLED:

gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

Conceda permissões de acesso para permitir que o agente e o ambiente de desenvolvimento local ambiente 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 do Agent Identity (roles/agentidentity.user) no recurso do provedor de autenticação:

Conceda acesso ao ID SPIFFE do agente implantado (Agent Identity):

gcloud alpha agent-identity authProviders 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"

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

gcloud alpha agent-identity authProviders 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 Google Cloud projeto do.
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, bigquery-mcp-3lo-authprovider).
AUTHORIZATION_URL: o URL do servidor de autorização (por exemplo, https://accounts.google.com/o/oauth2/v2/auth).
TOKEN_URL: o URL do servidor de tokens (por exemplo, https://oauth2.googleapis.com/token).
CLIENT_ID: o ID do cliente OAuth gerado pelo serviço de terceiros.
CLIENT_SECRET: a chave secreta do cliente OAuth gerada pelo 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.

Autenticar no código do agente

Para autenticar o agente, você pode usar 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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="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
# 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"
    )
)

# 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="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Instalar dependências para testes locais

Para testar o agente localmente em um ambiente virtual, instale as seguintes dependências necessárias:

Crie e ative um ambiente virtual:

python3 -m venv env
source env/bin/activate

Instale os pacotes necessários.

pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se o Agent Identity está ativado.

Se você estiver implantando no Agent Runtime na Gemini Enterprise Agent Platform , use a identity_type=AGENT_IDENTITY flag:

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