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

Para conceder ao 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 etapas no gerenciador de autenticação de identidade do agente.

Os provedores de autenticação OAuth de três etapas gerenciam o redirecionamento e os tokens do usuário. Isso elimina a necessidade de escrever um código personalizado para processar fluxos complexos do OAuth 2.0.

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

  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 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 três etapas, peça que o administrador conceda 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 três 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 de três etapas:

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

Console

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

    Acessar o Registro de agentes

  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 pode conter apenas 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.

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

    Isso atribui automaticamente o Usuário do conector (roles/iamconnectors.user) papel à 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 do provedor.

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

CLI gcloud

  1. Configure o aplicativo cliente OAuth para registrar o cliente e receber um ID do cliente 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 alpha agent-identity connectors 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 alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  4. 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 conector (roles/iamconnectors.user) no recurso do provedor de autenticação:

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

      gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.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 alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/iamconnectors.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, 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 Google Cloud ID da organização.
  • PROJECT_NUMBER: o Google Cloud número do projeto.
  • 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, receba 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, receba 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, é necessário registrar o URI de redirecionamento de callback dedicado do provedor de autenticação.

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

    https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .
    • LOCATION: The region where your auth provider will be deployed (for example,`us-west1`).
    • CONNECTOR_NAME: o nome do provedor de autenticação.

    Por exemplo: https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback

  2. Se você estiver se conectando aos Google Cloud serviços (como o BigQuery), poderá configurar a tela de permissão e criar credenciais de cliente OAuth no Google Cloud console:

    1. Configurar a tela de permissão OAuth:

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

        Acessar 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 suas 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 as credenciais do cliente OAuth:

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

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

      2. Clique em Criar credenciais >ID do cliente OAuth ID.
      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 construído.
      6. Clique em Criar. Na caixa de diálogo Cliente OAuth criado, copie os valores gerados de ID do cliente e Client Secret.

Autenticar no código do agente

Para autenticar o agente, você pode usar o ADK ou chamar 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 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())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

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

Exemplo: como se conectar ao MCP do BigQuery

O exemplo a seguir mostra uma configuração agent.py que conecta um agente ao servidor MCP do BigQuery usando o OAuth de três etapas:

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 for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the callback is received.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/connectors/{bigquery_mcp_auth_provider_id}",
    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.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())

# 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/connectors/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 = LlmAgent(
    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.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())

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

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    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 iamconnectorcredentials.retrieveCredentials para receber o token.

Como esse é um fluxo OAuth de várias etapas, a API retorna uma operação de longa duração (LRO). O agente precisa processar o ciclo de vida da operação:

  1. Solicitação inicial: o agente chama retrieveCredentials.
  2. Consentimento necessário: se o usuário não tiver concedido o consentimento, a API retornará uma LRO em que os metadados contêm o auth_uri e um consent_nonce.
  3. Redirecionamento de front-end: seu aplicativo precisa redirecionar o usuário para o auth_uri.
  4. Conclusão: depois que o usuário concede o consentimento, chame FinalizeCredential usando o consent_nonce para concluir o fluxo e receber o token.

Atualizar o aplicativo do lado do cliente

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

Servidor de interface de amostra

Você pode fazer o download e executar um servidor UI de amostra completo 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 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 Python:

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

  3. Navegue até o diretório do cliente 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 em a 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: é necessário usar localhost e não 127.0.0.1, já que o URL de redirecionamento OAuth exige isso. Especifique as configurações, clique 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 acionador de autorização

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

Gerencie o contexto da sessão gravando o consent_nonce fornecido pelo provedor de autenticação. Esse nonce é 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 concede o 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 do usuário

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

  1. Receber user_id_validation_state e auth_provider_name como parâmetros de consulta.
  2. Recuperar os valores user_id e consent_nonce do contexto da sessão.
  3. Chamar a API FinalizeCredentials do provedor de autenticação com esses parâmetros.
  4. Fechar a janela de autorização ao receber uma resposta bem-sucedida.
Exemplo: endpoint de validação do FastAPI (main.py)

O exemplo a seguir mostra um endpoint de validação do FastAPI completo que processa o callback 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://iamconnectorcredentials.googleapis.com/v1alpha"
    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 do agente

Depois que o usuário concede o consentimento e a janela de autorização é 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 uma 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.

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

A seguir