1. Introdução
Um agente com a própria credencial e uma permissão ampla vê os dados de todos. Neste codelab, você vai criar um agente que chama uma API de terceiros com as credenciais do usuário conectado. Assim, ele vai ver exatamente o que essa pessoa pode ver e nada mais.
Você vai criá-lo com o Kit de Desenvolvimento de Agente (ADK) do Google e o Gemini Enterprise.
Especificamente, você vai aprender a projetar uma arquitetura de identidade dupla em que:
- O agente atua 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.
- 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 etapas (3LO) para consultar ferramentas com segurança usando as credenciais do usuário.

Para isso, você vai aprender a:
- Criar um agente do ADK que se conecta ao servidor do Protocolo de Contexto de Modelo (MCP) do GitHub.
- Atualize a ferramenta do agente de um PAT (token de acesso pessoal) estático do GitHub para o fluxo de OAuth de três etapas (3LO) usando o Gerenciador de autenticação do Google Cloud.
- Implantar o agente com segurança no Agent Runtime e provisionar a identidade do agente.
- Configurar papéis do IAM para fornecer à identidade do agente acesso ao cofre de tokens em nome do usuário.
- Entender o fluxo completo de 3LO para o Gerenciador de Autenticação 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 projeto na máquina local. É necessário ter a versão 586.0.0 ou mais recente. Executegcloud components update. - Python 3.10 a 3.13 instalado localmente.
- O
uvgerenciador de pacotes 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á usar qualquer servidor MCP de terceiros que ofereça suporte ao OAuth 2.0 de três etapas.
2. Configuração do projeto
1. Autenticar no Google Cloud
Autentique-se no Google Cloud pela linha de comando local para garantir que seu ambiente tenha as permissões necessárias para implantar 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, definir o projeto na nuvem ativo (substitua YOUR_PROJECT_ID pelo ID do projeto na nuvem do Google Cloud) e configurar o Application Default Credentials (ADC):
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. Ativar os serviços necessá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. Quando terminar, ele vai retornar ao prompt de comando confirmando que as APIs estão ativas.
3. Instalar a Agents CLI e configurar o projeto
agents-cli é a ferramenta de linha de comando usada para estruturar, gerenciar, testar e implantar agentes do ADK no Gemini Enterprise. Instale-o 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).
Gerar o scaffolding inicial do projeto. Você vai começar com um protótipo local e, depois, vai aprimorá-lo para implantação no Agent Runtime:
agents-cli create secure-agent-demo --prototype --yes
Isso cria o diretório secure-agent-demo, que contém o código do agente, as dependências e os arquivos de teste.
4. Adicionar os extras necessários do ADK
Adicione os dois extras que faltam no pyproject.toml gerado: mcp para o conjunto de ferramentas do GitHub e agent-identity para o Auth Manager, que será usado mais adiante no laboratório. Abra secure-agent-demo/pyproject.toml e substitua todo o
google-adk
linha de dependência por:
"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 em secure-agent-demo/app/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 persona, limita o escopo do assistente à triagem do GitHub e aplica regras de segurança rígidas (como acesso somente leitura e orientação para que os usuários se autentiquem em caso de erros). - Configuração do agente (
root_agent): instancia umAgentdo ADK usando o modelogemini-3.8-flash, configura a lógica de nova tentativa de HTTP e equipa o agente com o conjunto de ferramentas do GitHub. - Wrapper do app (
app): encapsula o agente raiz em um contêinerAppdo ADK, permitindo que ele seja implantado 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 novo arquivo em secure-agent-demo/app/tools.py 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 os recursos do GitHub como ferramentas de agente que podem ser chamadas. - 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_TOKENcomo um token do 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:
- Crie um token de acesso pessoal refinado na página Tokens de acesso pessoal do GitHub:
- Clique em Gerar novo token e dê um nome a ele.
- Em Acesso ao repositório, selecione Todos os repositórios (ou selecione repositórios específicos para testar).
- Em Permissions > Repositories, clique em +Add permissions e selecione Contents, Issues e solicitações de pull como Read-only (Metadata é definido automaticamente como Read-only).
- Clique em Gerar token e copie o valor do token gerado. (Como alternativa, se você usar um token de acesso pessoal (clássico), selecione o escopo
repo.)
- Defina-o no ambiente:
export GITHUB_TOKEN="your_github_pat_here" - Navegue até a pasta
secure-agent-demo(se ainda não estiver nela) e inicie o playground local:cd secure-agent-demo agents-cli playground - Abra a interface do playground e selecione a pasta
appno menu suspenso. Na caixa de chat, teste um comando direcionado, como"Get the last 2 GitHub issues reported against my name"ou"List my 3 most recently updated repositories", e verifique se o agente chama o conjunto de ferramentas do MCP do GitHub e retorna seus dados do GitHub. Para testar se o agente está realmente usando seu token PAT para realizar ações em seu nome, pergunte sobre seus repositórios ou contribuições particulares.
4. Configurar o Auth Manager
Embora a codificação de credenciais estáticas (como um PAT) seja conveniente para prototipagem, ela expõe os aplicativos de produção a vazamentos de credenciais, 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 credenciais. Ele permite que os agentes se autentiquem usando uma chave de API ou um ID e uma chave secreta do cliente OAuth, ou em nome de um usuário por meio da delegação do OAuth usando tokens de acesso do usuário final.
No Gerenciador de Autenticação, você configura provedores de autenticação que definem o tipo de autenticação e as credenciais para aplicativos de terceiros específicos. 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 Gerenciador de autenticação funciona da seguinte maneira:

- Intercepção de consentimento dinâmico: quando o agente tenta executar uma ferramenta em nome de um usuário, o ADK verifica se há uma credencial válida no Gerenciador de autenticação. Se não houver, o Gerenciador de Autenticação vai retornar um URL de autorização para iniciar um fluxo de consentimento do OAuth de três etapas (3LO).
- Armazenamento seguro no 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 atualização do usuário resultantes em um vault de credenciais seguro gerenciado pelo Google.
- Ciclo de vida automatizado de tokens: o Auth Manager gerencia totalmente a expiração e a rotação de tokens em segundo plano, eliminando a necessidade de lógica de atualização manual de tokens ou de inatividade.
- Execução de ferramentas sem secrets: para ações subsequentes, o agente (autenticando-se pela identidade do agente SPIFFE) solicita dinamicamente o token de acesso delegado do usuário ao gerenciador de autenticação no momento da execução, mantendo o código do cliente e do agente totalmente livre de secrets.
Etapa A: configurar o GitHub como um provedor de autenticação
Execute o seguinte comando gcloud para criar um provedor de autenticação do GitHub no seu projeto do Google Cloud. Você vai fornecer o ID do cliente e a chave secreta 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="YOUR_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="YOUR_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="YOUR_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
- Acesse a página de configurações do desenvolvedor do GitHub, selecione Apps OAuth na barra lateral esquerda e clique em Novo app OAuth (ou Registrar um novo aplicativo, se você ainda não tiver criado um).
- Preencha os campos do formulário do aplicativo OAuth:
- Nome do aplicativo: insira um nome para o aplicativo (por exemplo,
secure-agent-demo). - URL da página inicial: insira o URL do seu aplicativo de front-end (
http://localhost:8501para prototipagem local; é possível atualizar para o URL implantado na produção). - Descrição do aplicativo: opcional (pode ser deixada em branco).
- URL de callback de autorização (URI de redirecionamento): cole o
redirectUrlrecuperado na Etapa A. - Ativar fluxo do dispositivo: deixe desmarcado.
- Nome do aplicativo: insira um nome para o aplicativo (por exemplo,
- Clique em Registrar aplicativo.
- Na página do aplicativo, copie o ID do cliente, clique em Gerar uma nova chave secreta do cliente e copie a chave secreta do cliente gerada. Salve os dois valores, que serão usados como
YOUR_GITHUB_CLIENT_IDeYOUR_GITHUB_CLIENT_SECRETna próxima etapa.
Etapa C: adicionar as credenciais do GitHub ao provedor de autenticação
Substitua YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID e YOUR_GITHUB_CLIENT_SECRET pelos seus valores 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 retorna o provedor com clientId visível. O secret não é retornado.
👉 Com essa etapa concluída, o Gerenciador de autenticação do Google Cloud está totalmente configurado com as credenciais do aplicativo OAuth do GitHub, definindo o Google Cloud como o cofre seguro que lida com os ciclos de vida de consentimento e token.
5. Mudar o token PAT para o Gerenciador de Autenticação
Agora que o Gerenciador de Autenticação está totalmente configurado, a próxima etapa é atualizar o código da ferramenta do agente. Substitua o conteúdo de secure-agent-demo/app/tools.py pelo código abaixo.
👉 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,
)
Noções básicas sobre o código da ferramenta
A principal mudança é auth_scheme. Ao anexá-lo ao conjunto de ferramentas, sempre que o agente chamar o GitHub, o ADK primeiro vai pedir ao Gerenciador de Autenticação o token desse usuário. Se ainda não houver um, ele vai solicitar 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 Gerenciador de Autenticação, 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.
Inicialize a configuração de implantação do projeto. Verifique se o terminal está no diretório raiz do projeto secure-agent-demo e execute:
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 empacotamento do contêiner 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 para garantir que o agente seja implantado na mesma região do provedor de autenticação:
region: "us-central1"
Implantar o agente com uma identidade de agente
Implante com adk deploy agent_engine. Isso provisiona o agente com a própria identidade de agente, uma identidade criptográfica exclusiva, com suporte do SPIFFE, que pertence a essa implantação e que o agente usa para se autenticar no Gerenciador de Autenticação e em outros serviços do Google Cloud.
👉 No diretório secure-agent-demo, substitua YOUR_PROJECT_ID e execute estes comandos:
# Write a config file inside the `app/` folder instructing Agent Runtime to provision 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 mostrar o nome do recurso implantado. Anote o valor de reasoningEngines/ENGINE_ID, porque você vai precisar dele para autorizar o agente e apontar o cliente da interface para ele.
Autorizar a identidade do agente
Agora que o agente está em execução na nuvem, ele precisa de permissão para acessar o armazenamento de credenciais no Gerenciador de Autenticação. Por padrão, a identidade SPIFFE do agente não tem acesso a recursos de nuvem externos.
Execute o seguinte comando gcloud para conceder o papel roles/agentidentity.user à identidade do agente no recurso do provedor de autenticação. Isso concede ao agente as permissões exatas necessárias para solicitar tokens de usuário do vault, e nada mais.
# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
--format="value(projectNumber)"
Em seguida, vincule a política do IAM ao provedor de autenticação (substituindo YOUR_PROJECT_ID e o principal --member):
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"
👉 Você também pode conferir o valor completo de --member="principal://..." do agente implantado no console do Google Cloud: acesse o console do Agent Runtime, selecione o agente implantado, acesse a guia Identidade e copie a string principal://... completa diretamente.
Agora conceda à sua própria conta o mesmo papel no provedor. O cliente de interface que você vai executar 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"
7. Noções básicas sobre o fluxo de consentimento do 3LO
Agora que o agente está implantado no Agent Runtime com uma identidade segura, a próxima etapa é fornecer uma interface de front-end personalizada para que os usuários conversem com ele. Além disso, o Gerenciador de Autenticação do Google Cloud requer um gerenciador de callback do 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 finalizar a troca de tokens OAuth por conta própria. O handshake 3LO depende do aplicativo cliente para preencher a lacuna:
- Quando um usuário autoriza o app do GitHub, o GitHub o redireciona de volta para o
redirectUrldo provedor de autenticação da identidade do agente . - Em seguida, o Gerenciador de Autenticação redireciona o pop-up do navegador do usuário para um URL de callback do lado do cliente (
continue_uri). - É responsabilidade do aplicativo cliente interceptar esse redirecionamento, ler o valor de uso único dos cookies do navegador e chamar o endpoint
credentials:finalizedo Google Cloud para concluir o handshake. - Depois que o cliente finaliza a troca, o Google Cloud salva 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 Vault não pode armazenar as credenciais.
O fluxo interativo do OAuth 3LO abrange várias camadas. Confira o ciclo de vida completo de execução de uma solicitação de ferramenta. Vamos detalhar isso na explicação abaixo e na próxima etapa.
👉 Clique na imagem para ampliar.
As principais responsabilidades do cliente no handshake
- Transmitir o desafio de consentimento (etapas 5 e 6): o agente emite um
adk_request_credentialcom o URL de consentimento e um valor de uso único. O cliente abre o pop-up e armazena o valor como um cookie. - Hospedar o callback de redirecionamento (etapas 10 e 11) :
/validateUserId, para onde o Gerenciador de Autenticação envia o pop-up após o consentimento. - Finalizar o token (etapas 12 a 14): combine o estado de validação do redirecionamento com o valor de uso único armazenado em cache e chame
credentials:finalize, que armazena o token no cofre.
Como 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 aplicativo, use estas duas referências:
- Atualizar o aplicativo do lado do cliente na documentação do Gerenciador de autenticação, que aborda como lidar com o desafio de consentimento e chamar
credentials:finalize. - O cliente de exemplo executável no repositório adk-python. Leia
main.pypara ver uma implementação completa e funcional das três responsabilidades acima.
8. Executar o cliente da interface localmente
Conforme mostrado no diagrama de sequência do fluxo de consentimento de 3LO, o Gerenciador de Autenticação redireciona a janela do navegador de volta para um endpoint de callback do lado do cliente. O cliente de amostra no repositório adk-python hospeda esse endpoint em /validateUserId. Faça o download e execute-o localmente seguindo estas etapas.
Fazer o download dos arquivos do cliente
O diretório contributing/samples/integrations/gcp_auth/client em adk-python contém três recursos principais:
main.py: o back-end do FastAPI que se conecta ao Agent Engine implantado e hospeda o endpoint de callback/validateUserIdpara finalizar os tokens OAuth.static/: os arquivos HTML e JavaScript da interface de chat do navegador.requirements.txt: os pacotes do Python necessários para executar o servidor cliente.
Como adk-python é um repositório grande, use o recurso de checkout esparso do Git para baixar apenas a pasta contributing/samples/integrations/gcp_auth/client:
- Primeiro, acesse o diretório superior de
secure-agent-demopara clonar o cliente em uma pasta irmã:cd .. - Execute os comandos a seguir para clonar os metadados do repositório sem fazer o download de todos os arquivos (
--no-checkout), restringir o caminho de checkout acontributing/samples/integrations/gcp_auth/cliente fazer o checkout apenas dessa 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
- No diretório
adk-pythonque você acabou de acessar, navegue até a pastaclient:cd contributing/samples/integrations/gcp_auth/client - Crie e ative um ambiente virtual do Python e instale as dependências do cliente de
requirements.txt:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - Defina as variáveis de ambiente que apontam o cliente para o projeto na nuvem do Google Cloud, a região (
us-central1) e o ID do Agent Engine implantado (YOUR_ENGINE_ID). Em seguida, inicie o servidor FastAPI local na porta8501: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 - Verifique se o servidor foi iniciado com sucesso e está detectando em
http://localhost:8501.
9. Testar o fluxo do OAuth
Agora que todos os serviços foram implantados, as vinculações do IAM foram configuradas e as variáveis de ambiente foram definidas, você pode testar o fluxo seguro de autorização delegada pelo usuário de ponta a ponta.
Etapa A: iniciar a execução da ferramenta
- Abra uma guia do navegador e acesse o URL do cliente:
http://localhost:8501. - No painel à esquerda, em Configurações, defina Tipo de agente como
Remote Agent (Vertex AI)(ouRemote Agent Engine). - Insira o ID do projeto e o local (
us-central1) do Google Cloud e clique em Carregar agentes remotos. Isso carrega os agentes implantados no seu projeto. - Selecione o agente
appimplantado no menu suspenso Selecionar mecanismo e clique em Salvar e aplicar configurações. - Na caixa de chat, digite uma consulta segmentada (como buscar seus problemas ou repositórios recentes):
(Ou tenteGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") e pressione Enter. - 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 o consentimento do OAuth de três etapas
- Uma janela pop-up separada do navegador será aberta, redirecionando você pelo Gerenciador de autenticação do Google Cloud para a página de autorização do OAuth do GitHub.
- Revise as permissões solicitadas e clique em Autorizar.
- O GitHub vai redirecionar de volta para o Google Cloud, que redireciona o pop-up para o URL de callback
/validateUserIddolocalhost. - O serviço de callback processa e finaliza o handshake de credenciais.
Etapa C: retomar
- Quando a janela pop-up é fechada, a guia de chat principal detecta o fechamento automaticamente.
- O front-end envia um payload de retomada de volta ao agente.
- O agente recupera o token recém-trocado de forma segura do Google Cloud Auth Manager, chama as ferramentas do MCP do GitHub em seu nome e transmite os dados do GitHub diretamente para a janela de chat, dados que o agente não conseguiria acessar sozinho.
Etapa D: inspecionar os registros do Cloud
Para verificar se a troca e a finalização do token foram processadas com segurança:
- Acesse a Análise de registros do console do Google Cloud.
- Localize os registros do servidor que confirmam a extração do valor de uso único e a validação:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - Inspecionar os registros do Agent Runtime: também é possível conferir os registros de execução diretamente no console da plataforma de agentes:
- Acesse o console do Agent Runtime.
- Clique no agente implantado na lista.
- Mude para a guia Playground. Isso vai mostrar os registros agênticos em tempo real no painel inferior, mostrando o ciclo de raciocínio do agente, os detalhes de execução da ferramenta e o ciclo de vida de recuperação de tokens 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, limpe totalmente o ambiente local:
- Interrompa o servidor uvicorn local pressionando Ctrl+C no terminal em que ele está sendo executado.
- 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 atua em nome do usuário conectado.
O que você aprendeu:
- Identidade do sistema do agente: como o agente opera com a própria identidade de 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 do usuário: como o agente solicita autorização para agir em nome do usuário em plataformas externas (como o GitHub) acionando um fluxo de consentimento OAuth de três etapas (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 tokens de usuário de forma dinâmica, em vez de usar secrets codificados.
- Configuração da política do IAM: como configurar vinculações de permissão detalhadas 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
