Autenticar usando o OAuth de três etapas com o gerenciador de autenticação

Para conceder ao seu agente acesso a ferramentas e serviços externos (como tarefas do Jira ou repositórios do GitHub) em nome de um usuário final específico, configure um provedor de autenticação OAuth de três pernas no gerenciador de autenticação de identidade do agente.

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

Importante:este documento mostra como autenticar usando a API Agent Identity. Recomendamos usar a API Agent Identity porque a API IAM Connectors (Visualização) não estará disponível de forma geral. Se você estiver usando a API IAM Connectors, migre para a API Agent Identity.

Fluxo de trabalho do OAuth de três etapas

Os provedores de autenticação OAuth de três etapas exigem o consentimento do usuário porque o agente acessa recursos em nome dele.

1. Solicitação e redirecionamento: a interface de chat pede que o usuário faça login e o redireciona para a página de consentimento do aplicativo de terceiros.
2. Consentimento e armazenamento: depois que o usuário concede permissão, o gerenciador de autenticação de identidade do agente armazena os tokens OAuth resultantes em um cofre de credenciais gerenciado pelo Google.
3. Injeção: quando você usa o Kit de Desenvolvimento de Agente (ADK), o agente recupera automaticamente o token do provedor de autenticação e o injeta 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.

   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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

3. Crie e implante um agente.
4. Verifique se você tem um aplicativo de front-end para processar solicitações de login do usuário e redirecionamento para páginas de consentimento de terceiros.
5. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

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

• Para criar provedores de autenticação:
  • Administrador de identidade do agente (roles/agentidentity.admin)
  • Editor de identidade do agente (roles/agentidentity.editor)
• Para usar provedores de autenticação:
  • Usuário de identidade do agente (roles/agentidentity.user)
  • 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 três etapas. 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 três 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 funções personalizadas ou outros papéis predefinidos.

Criar um provedor de autenticação de três vias

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 três etapas, use o console do Google Cloud ou a Google Cloud CLI.

Console

1. No console Google Cloud , acesse a página Registro de agentes.

   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 OAuth (3 etapas) .
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 a função Usuário da identidade do agente (roles/agentidentity.user) à identidade do agente no recurso do provedor de autenticação.

9. Copie o URL de callback.
10. Em outra guia, registre o URL de callback no aplicativo cliente OAuth de terceiros.
11. Na seção Credenciais do provedor de autenticação, insira as seguintes informações:
    • ID do cliente
    • Client Secret
    • URL do token
    • URL de autorização
12. Clique em Adicionar configuração de provedor.

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

CLI da gcloud

1. Configure seu aplicativo cliente OAuth para registrar o cliente e receber um ID e uma chave secreta do cliente. Especifique o URI de redirecionamento usando o modelo nessa seção.

2. Crie o provedor de autenticação usando as credenciais do cliente:

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --project="PROJECT_ID" \
       --location="LOCATION" \
       --three-legged-oauth-client-id="CLIENT_ID" \
       --three-legged-oauth-client-secret="CLIENT_SECRET" \
       --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
       --three-legged-oauth-token-url="TOKEN_URL"

3. 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"

4. Conceda permissões de acesso para permitir que seu agente e o 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 da 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 seu provedor de autenticação e 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 token (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 sua organização 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.

Configurar o aplicativo cliente OAuth

Antes de registrar as credenciais do cliente OAuth, obtenha um ID e uma chave secreta do cliente do servidor de autorização de terceiros (por exemplo, Google, GitHub ou Jira).

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

Registrar o URI de redirecionamento

Ao configurar as credenciais do cliente OAuth, é preciso registrar o URI de redirecionamento de callback dedicado do provedor de autenticação.

1. Crie o URI de redirecionamento usando o seguinte modelo:

   https://agentidentitycredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/oauthcallback

   Substitua:

   • PROJECT_ID: o ID do projeto do Google Cloud .
   • LOCATION: a região em que seu provedor de autenticação será implantado (por exemplo, us-west1).
   • AUTH_PROVIDER_NAME: o nome do provedor de autenticação.

   Exemplo:

   https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback

2. Se você estiver se conectando a serviços do Google Cloud (como o BigQuery), configure a tela de permissão e crie credenciais de cliente OAuth no console do Google Cloud :

   1. Configure a tela de permissão OAuth:

      1. No console do Google Cloud , acesse a página APIs e serviços >Tela de permissão OAuth.

         Acesse APIs e serviços >Tela de permissão OAuth

      2. Na seção Informações do app, insira um nome de aplicativo (como "Aplicativo do gerenciador do BigQuery") e um e-mail de suporte.
      3. Na seção Público-alvo, selecione Interno ou Externo.
      4. Insira seus dados de contato para receber notificações.
      5. Leia e aceite a Política de dados do usuário dos serviços de API do Google.
      6. Clique em Concluir.

   2. Crie suas credenciais de cliente OAuth:

      1. No console do Google Cloud , acesse a página APIs e serviços >Tela de permissão OAuth >Clientes.

         Acesse APIs e serviços >Tela de permissão OAuth >Clientes

      2. Clique em Criar credenciais >ID do cliente OAuth.
      3. Selecione a opção Aplicativo da Web na lista.
      4. Insira um nome reconhecível para o cliente OAuth.
      5. Na seção URIs de redirecionamento autorizados, clique em Adicionar URI e insira o URI de redirecionamento criado.
      6. Clique em Criar. Na caixa de diálogo Cliente OAuth criado, copie os valores gerados de ID do cliente e Chave secreta do cliente.

Fazer a autenticação no código do agente

Para autenticar seu agente, use o ADK ou chame a API Agent Identity diretamente.

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())

# The URI to redirect the user to after consent is granted.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create 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",
    continue_uri=CONTINUE_URI
)

# 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="MODEL_NAME (ex. gemini-2.5-flash)",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Exemplo: como se conectar à MCP do BigQuery

O exemplo a seguir mostra uma configuração agent.py que conecta um agente ao servidor MCP do BigQuery:

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
import google.auth
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

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

# URI to redirect user to after consent is granted.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_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())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

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

ADK

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

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.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())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider scheme
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

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

Chamar a API diretamente

Se você não estiver usando o ADK, o agente precisará chamar a API agentidentitycredentials.retrieveCredentials para receber o token.

Como esse é um fluxo do OAuth de várias etapas, o agente precisa processar o ciclo de vida da operação:

1. Solicitação inicial: o agente liga para retrieveCredentials.
2. Consentimento obrigatório: se o usuário não tiver dado consentimento, a API vai retornar uma resposta contendo o resultado como uri_consent_required. Ele vai conter authorization_uri e um consent_nonce.
3. Redirecionamento de front-end: seu aplicativo precisa redirecionar o usuário para o authorization_uri.
4. Conclusão: depois que o usuário der o consentimento, chame FinalizeCredentials usando consent_nonce para concluir o fluxo e receber o token.

Atualizar o aplicativo do lado do cliente

Observação: a UI do cliente funciona apenas com agentes remotos.

Para processar o login do usuário e o redirecionamento para o OAuth de três etapas, seu aplicativo do lado do cliente precisa implementar as seguintes etapas para gerenciar o consentimento do usuário e retomar a conversa:

Exemplo de servidor de interface

Você pode baixar e executar um servidor UI completa de amostra que usa uvicorn. Antes de começar, verifique se você tem uma conta do GitHub e o pip instalado.

Para configurar e executar o servidor de UI de amostra, faça o seguinte:

1. Clone o repositório do GitHub adk-python:

   git clone https://github.com/google/adk-python.git

2. Navegue até o repositório e ative um ambiente virtual do Python:

   cd adk-python
   python3 -m venv .venv
   source .venv/bin/activate

3. Navegue até o diretório do cliente da UI de amostra:

   cd contributing/samples/integrations/gcp_auth/client

4. Instale as dependências do cliente:

   pip install -r requirements.txt

5. Antes de iniciar o servidor, defina a variável de ambiente AGENT_PROJECT_DIR para especificar o diretório em que o código do agente está localizado. Caso contrário, o aplicativo vai procurar agentes na pasta mãe do diretório do cliente.

   Inicie o servidor UI de amostra usando uvicorn. Verifique se a porta corresponde ao URI de redirecionamento configurado no cliente OAuth:

   export AGENT_PROJECT_DIR="/path/to/your/agent_project"
   uvicorn main:app --port 8501 --reload

6. Abra http://localhost:8501 no navegador. Observação: use localhost e não 127.0.0.1, porque o URL de redirecionamento do OAuth exige especificamente o nome de host localhost. Especifique suas configurações, clique em Salvar e aplicar configurações e interaja com o agente.

Aplicativo de interface personalizada

Para implementar esses recursos diretamente em um aplicativo UI personalizada, siga estas etapas:

• Processar o gatilho de autorização
• Implementar um endpoint de validação de usuário
• Retomar a conversa com o agente

Processar o gatilho de autorização

Quando um agente precisa do consentimento do usuário, ele retorna uma chamada de função adk_request_credential. Seu aplicativo precisa interceptar essa chamada para iniciar uma caixa de diálogo ou um redirecionamento de autorização do usuário.

Gerencie o contexto da sessão gravando o consent_nonce fornecido pelo provedor de autenticação. Este valor de uso único é necessário para verificar o usuário durante a etapa de validação. Salve os valores auth_config e auth_request_function_call_id na sessão para facilitar a retomada do fluxo depois que o usuário der consentimento.

if (fc := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(fc)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, AUTH_PROVIDER_NAME, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = (
                fc.get('id') if isinstance(fc, dict)
                else getattr(fc, 'id', None)
            )
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    ec = auth_config.exchanged_auth_credential
    if ec and ec.oauth2:
        oauth2 = ec.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implementar um endpoint de validação de usuário

Implemente um endpoint de validação no seu servidor da Web (o mesmo URI fornecido como continue_uri durante a configuração). Esse endpoint precisa fazer o seguinte:

1. Receba user_id_validation_state, auth_provider_name e uuid como parâmetros de consulta.
2. Recupere os valores user_id e consent_nonce do armazenamento de sessão. Se vários fluxos de autorização forem executados simultaneamente, use o uuid para corresponder à sessão correta.
3. Chame a API FinalizeCredentials do provedor de autenticação com estes parâmetros.
4. Feche a janela de autorização ao receber uma resposta de sucesso.

Exemplo: endpoint de validação do FastAPI (main.py)

O exemplo a seguir mostra um endpoint de validação completo do FastAPI que processa o callback do OAuth e finaliza as credenciais do usuário:

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
    auth_provider_name = request.query_params.get("auth_provider_name")
    session_id = request.cookies.get("session_id")
    session = consent_sessions.get(session_id, {})

    payload = {
        "userId": session.get("user_id"),
        "userIdValidationState": request.query_params.get(
            "user_id_validation_state"
        ),
        "consentNonce": session.get("consent_nonce"),
    }

    base_url = "https://agentidentitycredentials.googleapis.com/v1"
    finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize"

    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(finalize_url, json=payload)
            resp.raise_for_status()
    except httpx.HTTPError as e:
        err_text = e.response.text if hasattr(e, "response") else str(e)
        status = e.response.status_code if hasattr(e, "response") else 500
        return HTMLResponse(err_text, status_code=status)

    return HTMLResponse("""
        <script>
            window.close();
        </script>
        <p>Success. You can close this window.</p>
    """)

Retomar a conversa com o agente

Depois que o usuário der consentimento e a janela de autorização for fechada, recupere os valores auth_config e auth_request_function_call_id dos dados da sessão. Para continuar a conversa, inclua esses detalhes em uma nova solicitação ao agente como um function_response.

if (request.is_auth_resume and session.auth_request_function_call_id
    and session.auth_config):
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

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 CLI do agente, faça o seguinte para implantar seu 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 seu agente (por exemplo, maps_agent).
   • PROJECT_ID: o ID do projeto do Google Cloud.
   • LOCATION: a região compatível em que você quer implantar o agente (por exemplo, us-west1).

SDK do Python

Se você estiver fazendo a implantação 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

# 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,mcp]>=2.7.1",
        ],
    },
)

Substitua:

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

A seguir

• Resolver problemas de autenticação de identidade do agente
• Visão geral da identidade do agente
• Autenticar usando o OAuth de duas etapas com o gerenciador de autenticação
• Autenticar usando a chave de API com o gerenciador de autenticação
• Gerenciar provedores de autenticação de identidade do agente