Criar um agente de IA que atue em nome do usuário com o gerenciador de autenticação e identidade do agente

1. Introdução

Um agente com credenciais próprias e permissão ampla tem acesso aos dados de todos. Neste codelab, você vai criar um agente que chama uma API de terceiros com as próprias credenciais do usuário conectado. Assim, ele vê exatamente o que a pessoa pode ver e nada mais.

Você vai criar com o Kit de Desenvolvimento de Agente (ADK) do Google e o Gemini Enterprise.

Especificamente, você vai aprender a projetar uma arquitetura de dupla identidade em que:

1. O agente age em nome próprio (identidade do agente): usando uma identidade do agente com suporte do SPIFFE, o agente invoca o Auth Manager, armazena telemetria e chama as APIs do Google Cloud.
2. O agente age em nome do usuário (identidade delegada pelo usuário): para acessar recursos externos, como o GitHub, o agente aciona um fluxo de consentimento OAuth de três vias (3LO) para consultar ferramentas com segurança usando as credenciais do usuário.

Para isso, você vai aprender a:

1. Crie um agente do ADK que se conecte ao servidor do Protocolo de Contexto de Modelo (MCP) do GitHub.
2. Atualize a ferramenta do agente de um PAT (token de acesso pessoal) estático do GitHub para um fluxo OAuth de três etapas (3LO) usando o Gerenciador de autenticação do Google Cloud.
3. Implante o agente com segurança no Agent Runtime e provisione a identidade do agente.
4. Configure papéis do IAM para fornecer o acesso de identidade do agente ao cofre de tokens em nome do usuário.
5. Entender o fluxo completo de 3LO para o Auth Manager no Google Cloud.

Pré-requisitos

Antes de começar, verifique se você atende a estes requisitos:

• Um projeto do Google Cloud com o faturamento ativado.
• O SDK Google Cloud (CLI gcloud) instalado e autenticado no seu projeto na máquina local. É necessário ter a versão 586.0.0 ou mais recente: execute gcloud components update.
• Python 3.10 a 3.13 instalado localmente.
• O gerenciador de pacotes uv instalado (pip install uv).
• Uma conta do GitHub para registrar um aplicativo OAuth e criar tokens. Se você não tiver uma conta do GitHub, poderá substituir qualquer servidor MCP de terceiros que ofereça suporte ao OAuth 2.0 de três vias.

2. Configuração do projeto

1. Autenticar no Google Cloud

Autentique-se no Google Cloud na linha de comando local para garantir que seu ambiente tenha as permissões necessárias para fazer a implantação no Agent Runtime, provisionar a identidade do agente e configurar o Auth Manager durante este laboratório:

Execute os comandos a seguir para fazer login na sua conta do Google Cloud e configurar as Application Default Credentials (ADC):

gcloud auth login
gcloud auth application-default login

2. Ativar os serviços obrigatórios do Google Cloud

Ative as APIs necessárias no seu projeto do Google Cloud para executar este laboratório. Execute o comando a seguir no terminal.

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

Esse comando pode levar um minuto para ser executado. Depois de concluído, ele vai retornar ao prompt de comando confirmando que as APIs estão ativas.

3. Instalar a CLI de agentes e configurar o projeto

O agents-cli é a ferramenta de linha de comando usada para criar estruturas, gerenciar, testar e implantar agentes do ADK no Gemini Enterprise. Instale localmente:

uvx google-agents-cli setup

Verifique a instalação:

agents-cli --help

O menu de ajuda da CLI vai mostrar os comandos disponíveis, como deploy, run e status.

Gere o scaffolding inicial do projeto. Você vai começar com um protótipo local e aprimorá-lo depois para a implantação do Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

Isso cria o diretório "secure-agent-demo" com o código, as dependências e os arquivos de teste do agente básico.

4. Adicionar os extras do ADK necessários

O pyproject.toml gerado envia google-adk[gcp,otel-gcp], que não tem dois extras necessários para esse agente: mcp para o conjunto de ferramentas do GitHub e agent-identity para o Auth Manager mais tarde no laboratório. Abra secure-agent-demo/pyproject.toml e mude a linha google-adk para:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

Em seguida, instale:

cd secure-agent-demo
agents-cli install

3. Criar e testar o agente

1. Criar um agente

No projeto, substitua o código no arquivo agent.py pelo seguinte:

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

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

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

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

Esse arquivo define três componentes principais do agente:

• Instrução do sistema (INSTRUCTION): define a personalidade, limita o assistente à triagem do GitHub e aplica regras de segurança estritas (como acesso somente leitura e orientação aos usuários para autenticação em caso de erros).
• Configuração do agente (root_agent): instancia um ADK Agent usando o modelo gemini-3.8-flash, configura a lógica de novas tentativas HTTP e equipa o agente com o conjunto de ferramentas do GitHub.
• App Wrapper (app): encapsula o agente raiz em um contêiner App do ADK, tornando-o implantável no Agent Runtime.

2. Adicionar a ferramenta MCP do GitHub

O agente se conecta ao GitHub usando o Protocolo de Contexto de Modelo (MCP). Crie um arquivo chamado tools.py na pasta app/ para registrar os parâmetros de conexão do gateway do MCP. Copie e cole o seguinte código:

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

Essa função cria uma ferramenta que chama o servidor MCP do GitHub:

• Conjunto de ferramentas do MCP (McpToolset): descobre e registra dinamicamente recursos do GitHub como ferramentas de agente chamáveis.
• Parâmetros de conexão (StreamableHTTPConnectionParams): direciona o conjunto de ferramentas para o gateway público do MCP do GitHub.
• Cabeçalhos de autorização: injeta o GITHUB_TOKEN como um token de portador e aplica o modo somente leitura (X-MCP-Readonly: true) diretamente na camada de transporte.

3. Testar localmente com um PAT (token de acesso pessoal) do GitHub

Para executar o agente localmente com credenciais estáticas:

1. Crie um token de acesso pessoal do GitHub. Conceda acesso de leitura aos seus repositórios. Caso contrário, o agente só poderá ver dados públicos, e o comando abaixo não vai retornar nada.
2. Defina no seu ambiente:

   export GITHUB_TOKEN="your_github_pat_here"
   

3. Navegue até a pasta secure-agent-demo. Execute:

   cd secure-agent-demo
   agents-cli playground
   

4. Abra a interface do playground e selecione a pasta "app" no menu suspenso. Na caixa de chat, digite "Fetch my contributions across my private repositories over the last 6 months" e verifique se o agente chama a ferramenta do GitHub e retorna dados dos seus repositórios particulares.

4. Configurar o Auth Manager

Embora a codificação de credenciais estáticas (como um PAT) seja conveniente para prototipagem, ela expõe aplicativos de produção a vazamento de credenciais, tempo de inatividade de atualização manual de tokens e falta de controles de acesso nativos da nuvem.

Para resolver isso, o Google Cloud oferece o Gerenciador de autenticação de identidade do agente. O gerenciador de autenticação de identidade do agente é um cofre de credenciais projetado para ajudar a proteger as credenciais. Ele permite que os agentes façam a autenticação usando uma chave de API ou um ID e uma chave secreta do cliente OAuth, ou em nome de um usuário por delegação do OAuth usando tokens de acesso do usuário final.

No Auth Manager, você configura provedores de autenticação que definem o tipo de autenticação e as credenciais de aplicativos específicos de terceiros. Os provedores de autenticação são regionais, e a região precisa corresponder à região em que você implanta o agente. O fluxo de trabalho completo do Auth Manager funciona da seguinte maneira:

1. Interceptação dinâmica de consentimento: quando o agente tenta executar uma ferramenta em nome de um usuário, o ADK verifica se o Auth Manager tem uma credencial válida. Se não houver, o Auth Manager vai retornar um URL de autorização para iniciar um fluxo de consentimento do OAuth de três pernas (3LO).
2. Armazenamento seguro do Vault: depois que o usuário final autoriza o aplicativo, o Auth Manager intercepta automaticamente o callback do OAuth e armazena os tokens de acesso e de atualização do usuário resultantes em um cofre de credenciais seguro gerenciado pelo Google.
3. Ciclo de vida automatizado do token: o Auth Manager gerencia totalmente a expiração e a rotação do token em segundo plano, eliminando a necessidade de lógica de atualização manual do token ou tempo de inatividade.
4. Execução de ferramentas sem chaves secretas: para ações subsequentes, o agente (autenticando pela identidade do agente SPIFFE) solicita dinamicamente o token de acesso delegado do usuário ao Auth Manager durante a execução, mantendo o código do cliente e do agente totalmente sem chaves secretas.

Importante: ao longo deste codelab, você vai encontrar variáveis de marcador de posição em maiúsculas, como YOUR_PROJECT_ID, YOUR_PROJECT_NUMBER, YOUR_ORG_ID e YOUR_ENGINE_ID. Substitua essas variáveis pelos valores do seu projeto na nuvem e recursos do Google Cloud ao executar os comandos.

Etapa A: configurar o GitHub como um provedor de autenticação

Execute o comando gcloud a seguir para criar um provedor de autenticação do GitHub no seu projeto do Google Cloud. Você vai fornecer o ID e a chave secreta do cliente mais tarde. O GitHub não vai emitir esses dados até saber o URL de callback do provedor.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

Descreva o provedor para recuperar o URL de redirecionamento do OAuth gerado:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

O campo é redirectUrl, aninhado em authProviderTypeParams.threeLeggedOauth. Para ler diretamente:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

O caminho é parecido com https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Etapa B: registrar o app OAuth no GitHub

1. Acesse a página de configurações de desenvolvedor do GitHub e clique em Registrar um novo app OAuth.
2. No URL da página inicial, insira o URL do aplicativo de front-end (por exemplo, http://localhost:8501 para prototipagem local). Depois, você pode mudar para o URL implantado na produção.
3. Defina o URI de redirecionamento como o redirectUrl recuperado na etapa anterior.
4. Clique em Registrar aplicativo e em Gerar uma nova chave secreta do cliente. Salve o ID e a chave secreta do cliente.

Etapa C: adicionar as credenciais do GitHub ao provedor de autenticação

Substitua o ID do projeto, o ID do cliente e a chave secreta do cliente e execute este comando:

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

O comando repete o provedor com clientId visível, mas não o secret.

👉 Com essa etapa concluída, seu Google Cloud Auth Manager agora está totalmente configurado com as credenciais do aplicativo OAuth do GitHub, configurando o Google Cloud para agir como o cofre seguro que processa o consentimento e os ciclos de vida dos tokens.

5. Mudar o token PAT para o Auth Manager

Agora que o Auth Manager está totalmente configurado, a próxima etapa é atualizar o código da ferramenta do agente. Substitua app/tools.py pelo código a seguir.

👉 Substitua o ID do projeto e o local na variável OAUTH_PROVIDER_NAME abaixo.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

Entender o código da ferramenta

A principal mudança é auth_scheme. Ao anexar o token ao conjunto de ferramentas, sempre que o agente chamar o GitHub, o ADK vai pedir primeiro ao Auth Manager o token desse usuário. Se ainda não houver um, o ADK vai pedir que o usuário faça login em vez de falhar. O GITHUB_TOKEN fixado no código desapareceu completamente.

6. Implantar o agente no Agent Runtime

Agora que atualizamos a ferramenta MCP do GitHub para usar o Auth Manager, a próxima etapa é implantar o agente no Agent Runtime. A implantação com a identidade do agente ativada provisiona um ID SPIFFE exclusivo para o agente.

Vamos começar inicializando a configuração de implantação do projeto. Execute no terminal:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

Esse comando inspeciona a estrutura do projeto para verificar a compatibilidade com o ADK, prepara as configurações de pacote de contêineres subjacentes e gera um arquivo agents-cli-manifest.yaml na raiz do projeto pré-preenchido com as configurações de implantação padrão.

👉 Abra o arquivo agents-cli-manifest.yaml recém-criado e verifique ou atualize o campo region para us-central1. Assim, você garante que o agente seja implantado na mesma região do seu provedor de autenticação:

region: "us-central1"

Implantar o Agente com uma Identidade do Agente

Implante com adk deploy agent_engine. Isso provisiona o agente com a própria identidade do agente, uma identidade criptográfica exclusiva com suporte do SPIFFE pertencente a essa implantação, que o agente usa para autenticar no Auth Manager e em outros serviços do Google Cloud.

👉 Substitua YOUR_PROJECT_ID antes de executar estes comandos:

# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

A implantação leva alguns minutos para criar e fazer upload do contêiner. Quando terminar, a CLI vai imprimir o nome do recurso implantado. Anote o valor reasoningEngines/ENGINE_ID, porque você vai precisar dele para autorizar seu agente e apontar o cliente da interface para ele.

Use adk deploy agent_engine, não agents-cli deploy --agent-identity. Ambos são implantados com sucesso, mas produzem formatos de recursos diferentes. O agents-cli deploy cria um servidor de contêiner sem classMethods. O cliente da interface que você executa depois chama create_session() no agente implantado e falha com 'AgentEngine' object has no attribute 'create_session'. adk deploy agent_engine produz o formato AdkApp em pickle, que expõe os 13 métodos de que o cliente precisa.

Para onde o usuário é direcionado após o consentimento: depois que um usuário aprova o acesso, o navegador dele é enviado para o endereço em OAUTH_CONTINUE_URI, que é veiculado pelo seu próprio aplicativo cliente. Neste laboratório, o cliente é executado na sua máquina. Portanto, o agente usa o padrão já definido em app/tools.py (http://localhost:8501/validateUserId), e não é necessário mudar nada. Se você hospedar o cliente em outro lugar mais tarde, atualize o padrão antes de fazer a implantação.

Autorizar a identidade do agente

Agora que o agente está sendo executado na nuvem, ele precisa de permissão para acessar as credenciais armazenadas no Auth Manager. Por padrão, a identidade SPIFFE do agente não tem acesso a recursos externos da nuvem.

Execute o comando gcloud a seguir para conceder o papel roles/agentidentity.user à identidade do agente no recurso do provedor de autenticação. Isso concede ao seu agente as permissões exatas necessárias para solicitar tokens de usuário do cofre, e nada mais.

👉 Substitua YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER e YOUR_ENGINE_ID. O ID do mecanismo está na saída de implantação acima.

Para receber YOUR_ORG_ID, execute o comando abaixo:

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

Agora conceda à sua própria conta a mesma função no provedor. O cliente da interface que você executa na próxima etapa chama a API de finalização de credenciais com suas Application Default Credentials. Sem isso, o fluxo de consentimento falha com um erro 403 em agentidentity.authProviders.retrieveCredentials:

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

Essa segunda vinculação só é necessária para executar o laboratório localmente. Ele permite que o cliente na sua máquina finalize o consentimento usando suas próprias credenciais. Na produção, o cliente é executado com a própria identidade, e apenas a vinculação do agente acima é necessária.

7. Entender o fluxo de consentimento do 3LO

Agora que o agente está implantado no Agent Runtime com uma Identidade do Agente segura, a próxima etapa é fornecer uma interface de front-end personalizada para que os usuários conversem com ele. Mais importante ainda, o Google Cloud Auth Manager exige um gerenciador de callback de aplicativo cliente para concluir o loop de autenticação.

Embora o Google Cloud Auth Manager gerencie com segurança as credenciais do usuário em um cofre, ele não pode concluir a troca de tokens do OAuth por conta própria. O handshake 3LO depende do aplicativo cliente para preencher a lacuna:

1. Quando um usuário autoriza o app GitHub, o GitHub o redireciona de volta para o redirectUrl do provedor de autenticação de identidade do agente .
2. Em seguida, o Auth Manager redireciona o pop-up do navegador do usuário de volta para um URL de callback do lado do cliente (continue_uri).
3. É responsabilidade do aplicativo cliente interceptar esse redirecionamento, ler o nonce dos cookies do navegador e chamar o endpoint credentials:finalize do Google Cloud para concluir o handshake.
4. Depois que o cliente concluir a troca, o Google Cloud vai salvar o token com segurança no cofre do provedor de autenticação, permitindo que o agente chame a ferramenta do GitHub.

Sem esse cliente personalizado hospedando o endpoint de callback, o handshake permanece incompleto, e o cofre não pode armazenar as credenciais.

O fluxo interativo do OAuth 3LO abrange várias camadas. Confira o ciclo de vida de execução completo de uma solicitação de ferramenta. Vamos detalhar isso na explicação abaixo e na próxima etapa.

👉 Clique na imagem para ampliar.

Principais responsabilidades do cliente no Handshake

• Transmitir o desafio de consentimento (etapas 5 e 6): o agente emite um adk_request_credential que carrega o URL de consentimento e um número aleatório de uso único. O cliente abre o pop-up e armazena o número aleatório como um cookie.
• Hospede o callback de redirecionamento (etapas 10 a 11) : /validateUserId, em que o Auth Manager envia o pop-up após o consentimento.
• Finalize o token (etapas 12 a 14): combine o estado de validação do redirecionamento com o nonce armazenado em cache e chame credentials:finalize, que armazena o token no cofre.

Criar seu próprio cliente

Não é necessário escrever esse cliente para o laboratório. A próxima etapa executa um cliente pré-criado. Ao implementar isso no seu próprio aplicativo, estas são as duas referências para trabalhar:

• Atualize o aplicativo do lado do cliente na documentação do Auth Manager, que aborda o processamento do desafio de consentimento e a chamada de credentials:finalize.
• O cliente de amostra executável no repositório adk-python. Leia main.py para uma implementação completa e funcional das três responsabilidades acima.

8. Executar o cliente da interface localmente

Como mostramos no diagrama de sequência do fluxo de consentimento do 3LO, o Auth Manager precisa redirecionar o pop-up do navegador de volta para um endpoint de callback do lado do cliente. O cliente de exemplo hospeda esse endpoint em /validateUserId. Vamos executar localmente.

Copiar arquivos do cliente para "Local"

Navegue até a pasta gcp_auth/client no repositório do GitHub adk-python. Essa pasta contém os recursos necessários para criar nosso contêiner de cliente de chat.

👉 Copie todos os arquivos em gcp_auth/client para seu ambiente local:

• main.py: o script do aplicativo FastAPI que contém o callback de finalização do token (/validateUserId) discutido na seção anterior.
• static/: contém as páginas HTML.

Como alternativa, você também pode fazer um checkout esparso da pasta:

git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout

Executar o cliente

1. Navegue até a pasta client que você acabou de copiar:

   cd adk-python/contributing/samples/integrations/gcp_auth/client
   

2. Crie um ambiente virtual e instale as dependências do cliente. A pasta envia um requirements.txt e nenhum pyproject.toml. Portanto, uv run uvicorn ... por si só falha com Failed to spawn: uvicorn:

   uv venv --python 3.13 .venv
   source .venv/bin/activate
   uv pip install --python .venv/bin/python -r requirements.txt
   

3. Aponte o cliente para o agente implantado e inicie na porta 8501:

   export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=us-central1
   export AGENT_ID=YOUR_ENGINE_ID
   
   .venv/bin/uvicorn main:app --port 8501
   

4. Verifique se o servidor foi iniciado e está escutando em http://localhost:8501.

Use localhost, não 127.0.0.1. O redirecionamento do OAuth exige o nome do host localhost. Os dois não são intercambiáveis aqui, mesmo que sejam resolvidos para o mesmo endereço.

9. Testar o fluxo do OAuth

Agora que todos os serviços estão implantados, as vinculações do IAM estão configuradas e as variáveis de ambiente estão definidas, você pode testar o fluxo de autorização delegada pelo usuário de ponta a ponta seguro.

Etapa A: iniciar a execução da ferramenta

1. Abra uma guia do navegador e acesse o URL do cliente: http://localhost:8501.
2. No painel à esquerda, defina o tipo de agente como Remote Agent Engine.
3. Digite o projeto e o local do Google Cloud. Clique em Load Remote Agents. Isso vai carregar todos os agentes implantados no seu projeto.
4. Selecione o agente certo no menu suspenso e salve as configurações.
5. Na caixa de chat, digite:

   Fetch my contributions across my private repositories over the last 6 months
   

   e pressione Enter.
6. Observe a interface do chat: como o agente ainda não tem credenciais para sua sessão de usuário, ele recebe um desafio de autenticação e mostra o card "Autenticação necessária" na conversa.

Etapa B: concluir a permissão do OAuth de três etapas

1. Uma janela pop-up separada do navegador será aberta, redirecionando você pelo Auth Manager do Google Cloud até a página de autorização do OAuth do GitHub.
2. Revise as permissões solicitadas e clique em Autorizar.
3. O GitHub vai redirecionar de volta para o Google Cloud, que redireciona o pop-up para o URL de callback /validateUserId do localhost.
4. O serviço de callback processa e finaliza o handshake de credenciais.

Etapa C: retome

1. Quando a janela pop-up é fechada, a guia de chat principal detecta o fechamento automaticamente.
2. O front-end envia um payload de retomada de volta ao agente.
3. O agente recupera o token recém-trocado com segurança do Google Cloud Auth Manager, chama as ferramentas MCP do GitHub em seu nome e transmite dados dos seus repositórios particulares diretamente para a janela de chat. Esses dados não poderiam ser acessados pelo agente por conta própria.

Etapa D: inspecionar os registros do Cloud

Para verificar se a troca e a finalização do token foram processadas com segurança:

1. Acesse a Análise de registros no console do Google Cloud.
2. Localize os registros do servidor confirmando a extração do nonce e a validação bem-sucedida:

   INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
   INFO:secure-agent-client:Successfully finalized auth provider credentials.
   

3. Inspecionar logs do Agent Runtime: outra opção é conferir os logs de execução diretamente no console do Agent Platform:
   • Acesse o console do Agent Runtime.
   • Clique no agente implantado na lista.
   • Mude para a guia Playground. Isso vai mostrar os registros do agente ativo no painel de baixo, mostrando o loop de raciocínio do agente, os detalhes de execução da ferramenta e o ciclo de vida de recuperação de token em tempo real.

10. Limpeza

Para evitar cobranças contínuas no Google Cloud, limpe os recursos implantados:

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

Limpar arquivos locais

Se quiser limpar totalmente o ambiente local:

1. Pressione Ctrl+C no terminal em que ele está sendo executado para interromper o servidor uvicorn local.
2. Remova os diretórios do projeto criados durante este laboratório:

# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Parabéns!

Você criou e protegeu um agente que age em nome do usuário conectado.

O que você aprendeu:

• Identidade do sistema do agente: como o agente opera com a própria identidade da conta para interagir com segurança com a infraestrutura do GCP, gerenciar registros de telemetria e chamar APIs de finalização de credenciais.
• Identidade delegada pelo usuário: como o agente solicita autorização para agir em nome do usuário em plataformas externas (como o GitHub) ao acionar um fluxo de consentimento OAuth de três pernas (3LO).
• Integração segura de ferramentas: como conectar agentes do ADK a servidores do Protocolo de Contexto de Modelo (MCP) usando o Gerenciador de autenticação do Google Cloud para buscar dinamicamente tokens de usuário em vez de usar segredos codificados.
• Configuração da política do IAM: como configurar vinculações de permissões refinadas para autorizar a identidade do Agent Runtime e sua própria conta no provedor de autenticação.

Leitura adicional

• Gerenciador de autenticação de identidade do agente para entender a configuração e os escopos do fluxo de autenticação.
• Visão geral do Agent Runtime
• Documentação do ADK
• Protocolo de Contexto de Modelo