1. Introduzione
Un agente con le proprie credenziali e un'autorizzazione ampia vede i dati di tutti. In questo codelab creerai un agente che chiama un'API di terze parti con le credenziali dell'utente che ha eseguito l'accesso, in modo che veda esattamente ciò che può vedere quella persona e nient'altro.
Lo creerai con Google Agent Development Kit (ADK) e Gemini Enterprise.
In particolare, imparerai a progettare un'architettura a doppia identità in cui:
- L'agente agisce per proprio conto (identità dell'agente): utilizzando un'identità dell'agente supportata da SPIFFE, l'agente richiama Auth Manager, archivia la telemetria e chiama le API Google Cloud.
- L'agente agisce per conto dell'utente (identità delegata dall'utente): per accedere a risorse esterne come GitHub, l'agente attiva un flusso di consenso OAuth a tre vie (3LO) per eseguire query sugli strumenti in modo sicuro utilizzando le credenziali dell'utente.

Per raggiungere questo obiettivo, imparerai a:
- Crea un agente ADK che si connetta al server Model Context Protocol (MCP) di GitHub.
- Aggiorna lo strumento dell'agente da un token di accesso personale (PAT) GitHub statico al flusso OAuth a tre vie (3LO) utilizzando Google Cloud Auth Manager.
- Esegui il deployment dell'agente in modo sicuro in Agent Runtime ed esegui il provisioning di Agent Identity.
- Configura i ruoli IAM per fornire all'identità dell'agente l'accesso al vault dei token per conto dell'utente.
- Comprendere il flusso 3LO end-to-end per Auth Manager in Google Cloud.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Un progetto Google Cloud con fatturazione abilitata.
- Google Cloud SDK (
gcloudCLI) installato e autenticato nel tuo progetto sulla tua macchina locale. È richiesta la versione 586.0.0 o successiva: eseguigcloud components update. - Python dalla versione 3.10 alla 3.13 installato localmente.
- Il gestore di pacchetti
uvinstallato (pip install uv). - Un account GitHub per registrare un'applicazione OAuth e creare token. Se non hai un account GitHub, puoi sostituirlo con qualsiasi server MCP di terze parti che supporti OAuth 2.0 a tre vie.
2. Configurazione del progetto
1. Esegui l'autenticazione su Google Cloud
Esegui l'autenticazione su Google Cloud dalla riga di comando locale per assicurarti che il tuo ambiente disponga delle autorizzazioni necessarie per eseguire il deployment in Agent Runtime, eseguire il provisioning di Agent Identity e configurare Auth Manager durante questo lab.
Esegui i seguenti comandi per accedere al tuo account Google Cloud, impostare il progetto attivo (sostituisci YOUR_PROJECT_ID con l'ID progetto Google Cloud) e configurare le credenziali predefinite dell'applicazione (ADC):
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. Abilita i servizi Google Cloud richiesti
Abilita le API necessarie nel tuo progetto Google Cloud per eseguire questo lab. Esegui questo comando nel terminale:
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
L'esecuzione di questo comando potrebbe richiedere un minuto. Al termine, tornerai al prompt dei comandi che conferma che le API sono attive.
3. Installa l'interfaccia a riga di comando degli agenti e configura il progetto
agents-cli è lo strumento a riga di comando utilizzato per creare lo scaffold, gestire, testare ed eseguire il deployment degli agenti ADK in Gemini Enterprise. Installalo localmente:
uvx google-agents-cli setup
Verifica l'installazione:
agents-cli --help
Dovresti visualizzare il menu di aiuto dell'interfaccia a riga di comando con i comandi disponibili (ad esempio deploy, run e status).
Generare l'impalcatura iniziale del progetto. Inizierai con un prototipo locale e lo migliorerai in un secondo momento per il deployment di Agent Runtime:
agents-cli create secure-agent-demo --prototype --yes
In questo modo viene creata la directory secure-agent-demo contenente il codice dell'agente di base, le dipendenze e i file di test.
4. Aggiungi gli extra ADK richiesti
Aggiungi i due extra mancanti nel file pyproject.toml generato: mcp per il set di strumenti GitHub e agent-identity per Auth Manager utilizzato più avanti nel lab. Apri secure-agent-demo/pyproject.toml e sostituisci l'intero
google-adk
Linea di dipendenza con:
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
Poi installa:
cd secure-agent-demo
agents-cli install
3. Crea e testa l'agente
1. Crea l'agente
All'interno del progetto, sostituisci il codice in secure-agent-demo/app/agent.py con il seguente:
# 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",
)
Questo file definisce tre componenti chiave dell'agente:
- Istruzione di sistema (
INSTRUCTION): imposta la persona, limita l'assistente al triage di GitHub e applica regole di sicurezza rigorose (come l'accesso di sola lettura e la guida degli utenti all'autenticazione in caso di errori). - Configurazione dell'agente (
root_agent): crea un'istanza di un ADKAgentutilizzando il modellogemini-3.8-flash, configura la logica di ripetizione HTTP e dota l'agente del set di strumenti GitHub. - Wrapper dell'app (
app): incapsula l'agente root in un container ADKApp, rendendolo distribuibile in Agent Runtime.
2. Aggiungi lo strumento MCP di GitHub
L'agente si connette a GitHub utilizzando il Model Context Protocol (MCP). Crea un nuovo file in secure-agent-demo/app/tools.py per registrare i parametri di connessione del gateway MCP. Copia e incolla il seguente codice:
# 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",
},
)
)
Questa funzione crea uno strumento che chiama il server MCP di GitHub:
- Set di strumenti MCP (
McpToolset): rileva e registra dinamicamente le funzionalità di GitHub come strumenti dell'agente richiamabili. - Parametri di connessione (
StreamableHTTPConnectionParams): indirizza il set di strumenti al gateway MCP pubblico di GitHub. - Intestazioni di autorizzazione: inserisce
GITHUB_TOKENcome token di connessione e applica la modalità di sola lettura (X-MCP-Readonly: true) direttamente al livello di trasporto.
3. Esegui test in locale con un token di accesso personale (PAT) GitHub
Per eseguire l'agente localmente con credenziali statiche:
- Crea un token di accesso personale granulare nella pagina Token di accesso personale di GitHub:
- Fai clic su Genera nuovo token e assegna un nome al token.
- Nella sezione Accesso al repository, seleziona Tutti i repository (o seleziona i repository specifici con cui vuoi eseguire il test).
- In Permissions > Repositories (Autorizzazioni > Repository), fai clic su +Add permissions (+Aggiungi autorizzazioni) e seleziona Contents (Contenuti), Issues (Problemi) e Pull requests (Richieste di pull) su Read-only (Sola lettura) (Metadata (Metadati) viene impostato automaticamente su Sola lettura).
- Fai clic su Genera token e copia il valore del token generato. (In alternativa, se utilizzi un token di accesso personale (classico), seleziona l'ambito
repo.)
- Impostala nel tuo ambiente:
export GITHUB_TOKEN="your_github_pat_here" - Vai alla cartella
secure-agent-demo(se non ci sei già) e avvia il playground locale:cd secure-agent-demo agents-cli playground - Apri l'interfaccia del playground e seleziona la cartella
appdal menu a discesa. Nella chat, prova un prompt mirato come"Get the last 2 GitHub issues reported against my name"o"List my 3 most recently updated repositories"e verifica che l'agente chiami il set di strumenti MCP di GitHub e restituisca i tuoi dati di GitHub. Per verificare se l'agente utilizza effettivamente il tuo token PAT per agire per tuo conto, prova a chiedergli informazioni sui tuoi repository privati o sui tuoi contributi.
4. Configura Auth Manager
Sebbene l'impostazione come hardcoded delle credenziali statiche (come un PAT) sia utile per la prototipazione, espone le applicazioni di produzione alla fuga di credenziali, ai tempi di inattività per l'aggiornamento manuale dei token e alla mancanza di controlli degli accessi cloud-native.
Per risolvere questo problema, Google Cloud fornisce Agent Identity Auth Manager. Il gestore di autenticazione di Agent Identity è un vault di credenziali progettato per proteggere le credenziali. Consente agli agenti di autenticarsi utilizzando una chiave API o un ID client e un secret OAuth oppure per conto di un utente tramite la delega OAuth utilizzando i token di accesso dell'utente finale.
In Auth Manager, configuri i provider di autenticazione che definiscono il tipo di autenticazione e le credenziali per applicazioni di terze parti specifiche. I provider di autenticazione sono regionali e la regione deve corrispondere a quella in cui esegui il deployment dell'agente. Il flusso di lavoro end-to-end di Auth Manager funziona come segue:

- Intercettazione dinamica del consenso: quando l'agente tenta di eseguire uno strumento per conto di un utente, l'ADK verifica la presenza di una credenziale valida esistente in Auth Manager. Se non esiste, Auth Manager restituisce un URL di autorizzazione per avviare un flusso di consenso OAuth a tre vie (3LO).
- Archiviazione sicura nel vault: una volta che l'utente finale autorizza l'applicazione, Auth Manager intercetta automaticamente il callback OAuth e archivia i token di accesso e i token di aggiornamento dell'utente risultanti in un vault di credenziali sicuro gestito da Google.
- Ciclo di vita dei token automatizzato: Auth Manager gestisce completamente la scadenza e la rotazione dei token in background, eliminando la necessità di una logica di aggiornamento manuale dei token o di tempi di inattività.
- Esecuzione di strumenti senza secret: per le azioni successive, l'agente (che si autentica tramite la sua identità agente SPIFFE) richiede dinamicamente il token di accesso delegato dell'utente ad Auth Manager in fase di runtime, mantenendo il codice del client e dell'agente completamente privo di secret.
Passaggio A: configura GitHub come provider di autenticazione
Esegui il seguente comando gcloud per creare un provider di autenticazione GitHub nel tuo progetto Google Cloud. Fornirai l'ID client e il secret in un secondo momento: GitHub non li emetterà finché non conoscerà l'URL di callback di questo provider.
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"
Descrivi il provider per recuperare l'URL di reindirizzamento OAuth generato:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1"
Il campo è redirectUrl, nidificato in authProviderTypeParams.threeLeggedOauth. Per leggerlo direttamente:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
Sembra https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.
Passaggio B: registra l'app OAuth in GitHub
- Vai alla pagina delle impostazioni per gli sviluppatori di GitHub, seleziona App OAuth nella barra laterale sinistra e fai clic su Nuova app OAuth (o Registra una nuova applicazione se non ne hai ancora creata una).
- Compila i campi del modulo di richiesta OAuth:
- Nome applicazione: inserisci un nome per l'applicazione (ad esempio,
secure-agent-demo). - URL della home page: inserisci l'URL della tua applicazione frontend (
http://localhost:8501per la prototipazione locale; puoi aggiornarlo all'URL di cui è stato eseguito il deployment in produzione). - Descrizione dell'applicazione: facoltativa (puoi lasciare questo campo vuoto).
- URL di callback di autorizzazione (URI di reindirizzamento): incolla l'
redirectUrlrecuperato nel passaggio A. - Enable Device Flow (Attiva flusso dispositivo): lascia l'opzione deselezionata.
- Nome applicazione: inserisci un nome per l'applicazione (ad esempio,
- Fai clic su Registra applicazione.
- Nella pagina dell'applicazione risultante, copia l'ID client, quindi fai clic su Genera un nuovo client secret e copia il client secret generato. Salva entrambi i valori, che utilizzerai come
YOUR_GITHUB_CLIENT_IDeYOUR_GITHUB_CLIENT_SECRETnel passaggio successivo.
Passaggio C: aggiungi le credenziali GitHub al provider di autenticazione
Sostituisci YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID e YOUR_GITHUB_CLIENT_SECRET con i tuoi valori ed esegui questo 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"
Il comando restituisce il provider con clientId visibile; il secret non viene restituito.
👉 Una volta completato questo passaggio, Google Cloud Auth Manager è ora completamente configurato con le credenziali dell'applicazione OAuth di GitHub, configurando Google Cloud in modo che agisca come vault sicuro che gestisce i cicli di vita dei token e del consenso.
5. Passa dal token PAT ad Auth Manager
Ora che Auth Manager è completamente configurato, il passaggio successivo consiste nell'aggiornare il codice dello strumento dell'agente. Sostituisci i contenuti di secure-agent-demo/app/tools.py con il seguente codice.
👉 Sostituisci l'ID progetto e la località nella variabile OAUTH_PROVIDER_NAME di seguito.
# 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,
)
Informazioni sul codice dello strumento
La modifica principale è auth_scheme. Se lo colleghi al set di strumenti, ogni volta che l'agente effettua una chiamata agentica a GitHub, ADK chiede prima ad Auth Manager il token dell'utente e, se non ne esiste ancora uno, chiede all'utente di accedere anziché non riuscire. Il valore GITHUB_TOKEN impostato come hardcoded è stato completamente rimosso.
6. Esegui il deployment dell'agente in Agent Runtime
Ora che abbiamo aggiornato lo strumento MCP di GitHub per utilizzare Auth Manager, il passaggio successivo consiste nel eseguire il deployment dell'agente in Agent Runtime. Il deployment con l'identità dell'agente abilitata esegue il provisioning di un ID SPIFFE univoco per l'agente.
Inizializza la configurazione del deployment per il progetto. Assicurati che il terminale si trovi nella directory root del progetto secure-agent-demo, quindi esegui:
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
Questo comando ispeziona la struttura del progetto per verificare la compatibilità con ADK, prepara le configurazioni di pacchettizzazione dei container sottostanti e genera un file agents-cli-manifest.yaml nella directory root del progetto precompilato con le impostazioni di deployment predefinite.
👉 Apri il file agents-cli-manifest.yaml appena creato e verifica o aggiorna il campo region in us-central1 per assicurarti che il deployment dell'agente venga eseguito nella stessa regione del provider di autenticazione:
region: "us-central1"
Esegui il deployment dell'agente con un'identità agente
Esegui il deployment con adk deploy agent_engine. In questo modo, l'agente viene dotato di una propria identità agente, un'identità crittografica univoca supportata da SPIFFE appartenente a questo deployment, che l'agente utilizza per autenticarsi in Auth Manager e in altri servizi Google Cloud.
👉 Dalla directory secure-agent-demo, sostituisci YOUR_PROJECT_ID ed esegui questi comandi:
# 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"
Il deployment richiede alcuni minuti per creare e caricare il container. Al termine, l'interfaccia a riga di comando stampa il nome della risorsa di cui è stato eseguito il deployment. Prendi nota del valore reasoningEngines/ENGINE_ID, poiché ti serve per autorizzare l'agente e per indirizzare il client UI verso di esso.
Autorizza l'identità dell'agente
Ora che l'agente è in esecuzione nel cloud, deve avere l'autorizzazione per accedere all'archivio credenziali in Auth Manager. Per impostazione predefinita, l'identità SPIFFE dell'agente non ha accesso alle risorse cloud esterne.
Esegui questo comando gcloud per concedere il ruolo roles/agentidentity.user all'identità dell'agente sulla risorsa del provider di autenticazione. In questo modo, l'agente riceve le autorizzazioni esatte di cui ha bisogno per richiedere i token utente dal vault e nient'altro.
# 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)"
Quindi associa la policy IAM al provider di autenticazione (sostituendo YOUR_PROJECT_ID e l'entità --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"
👉 Puoi anche ottenere il valore --member="principal://..." completo per l'agente di cui hai eseguito il deployment dalla console Google Cloud: vai alla console Agent Runtime, seleziona l'agente di cui hai eseguito il deployment, vai alla scheda Identità e copia direttamente la stringa principal://... completa.
Ora concedi al tuo account lo stesso ruolo sul provider. Il client UI che esegui nel passaggio successivo chiama l'API di finalizzazione delle credenziali con le tue Credenziali predefinite dell'applicazione, quindi senza questo il flusso di consenso non va a buon fine con un errore 403 su 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. Informazioni sul flusso di consenso 3LO
Ora che è stato eseguito il deployment dell'agente in Agent Runtime con un'identità agente sicura, il passaggio successivo consiste nel fornire un'interfaccia frontend personalizzata per consentire agli utenti di chattare con l'agente. Ancora più importante, Google Cloud Auth Manager richiede un gestore callback dell'applicazione client per completare il loop di autenticazione.
Sebbene Google Cloud Auth Manager gestisca in modo sicuro le credenziali utente all'interno di un vault, non può finalizzare lo scambio di token OAuth in autonomia. L'handshake 3LO si basa sull'applicazione client per colmare il divario:
- Quando un utente autorizza l'app GitHub, GitHub lo reindirizza al
redirectUrldel provider di autenticazione Agent Identity . - Auth Manager reindirizza quindi il popup del browser dell'utente a un URL di callback lato client (
continue_uri). - È responsabilità dell'applicazione client intercettare questo reindirizzamento, leggere il nonce dai cookie del browser e chiamare l'endpoint
credentials:finalizedi Google Cloud per completare l'handshake. - Una volta che il client ha finalizzato lo scambio, Google Cloud salva in modo sicuro il token nel vault del provider di autenticazione, consentendo all'agente di chiamare lo strumento GitHub.
Senza questo client personalizzato che ospita l'endpoint di callback, l'handshake rimane incompleto e il vault non può archiviare le credenziali.
Il flusso OAuth 3LO interattivo si estende su più livelli. Ecco il ciclo di vita completo dell'esecuzione di una richiesta di strumento. Analizzeremo questo aspetto nella spiegazione di seguito e nel passaggio successivo.
👉 Fai clic sull'immagine per ingrandirla.
Le responsabilità principali del cliente nell'handshake
- Inoltra la verifica del consenso (passaggi 5-6): l'agente emette un
adk_request_credentialcontenente l'URL di consenso e un nonce monouso; il client apre il popup e memorizza il nonce come cookie. - Ospita il callback di reindirizzamento (passaggi 10-11):
/validateUserId, dove Auth Manager invia il popup dopo il consenso. - Finalizza il token (passaggi 12-14): combina lo stato di convalida del reindirizzamento con il nonce memorizzato nella cache e chiama
credentials:finalize, che memorizza il token nel vault.
Creazione del tuo client
Non è necessario scrivere questo client per il lab: il passaggio successivo esegue un client predefinito. Quando implementi questa funzionalità nella tua applicazione, questi sono i due riferimenti da cui partire:
- Aggiorna l'applicazione lato client nella documentazione di Auth Manager, che illustra la gestione della verifica del consenso e la chiamata di
credentials:finalize. - Il client di esempio eseguibile nel repository adk-python. Leggi
main.pyper un'implementazione completa e funzionante delle tre responsabilità sopra indicate.
8. Esegui il client UI in locale
Come mostrato nel diagramma di sequenza del flusso di consenso 3LO, Auth Manager reindirizza la finestra del browser a un endpoint di callback lato client. Il client di esempio nel repository adk-python ospita l'endpoint all'indirizzo /validateUserId. Scaricalo ed eseguilo localmente seguendo questi passaggi.
Scarica i file del client
La directory contributing/samples/integrations/gcp_auth/client in adk-python contiene tre risorse chiave:
main.py: il backend FastAPI che si connette all'Agent Engine di cui hai eseguito il deployment e ospita l'endpoint di callback/validateUserIdper finalizzare i token OAuth.static/: i file HTML e JavaScript per la UI della chat del browser.requirements.txt: i pacchetti Python necessari per eseguire il server client.
Poiché adk-python è un repository di grandi dimensioni, utilizza la funzionalità di checkout sparse di Git per scaricare solo la cartella contributing/samples/integrations/gcp_auth/client:
- Innanzitutto, sali di una directory fuori da
secure-agent-demoin modo da clonare il client in una cartella di pari livello:cd .. - Esegui i seguenti comandi per clonare i metadati del repository senza scaricare tutti i file (
--no-checkout), limitare il percorso di checkout acontributing/samples/integrations/gcp_auth/cliented eseguire il checkout solo di quella cartella: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
Esegui il client
- Dalla directory
adk-pythonin cui ti trovi, vai alla cartellaclient:cd contributing/samples/integrations/gcp_auth/client - Crea e attiva un ambiente virtuale Python, quindi installa le dipendenze del client da
requirements.txt:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - Imposta le variabili di ambiente che indirizzano il client al progetto cloud Google Cloud, alla regione (
us-central1) e all'ID Agent Engine di cui è stato eseguito il deployment (YOUR_ENGINE_ID), quindi avvia il server FastAPI locale sulla 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 - Verifica che il server sia stato avviato correttamente e che sia in ascolto su
http://localhost:8501.
9. Testa il flusso OAuth
Ora che è stato eseguito il deployment di tutti i servizi, sono state configurate le associazioni IAM e sono state impostate le variabili di ambiente, puoi testare il flusso di autorizzazione delegata dall'utente end-to-end sicuro.
Passaggio A: avvia l'esecuzione dello strumento
- Apri una scheda del browser e vai all'URL del client:
http://localhost:8501. - Nel riquadro a sinistra, in Impostazioni di configurazione, imposta Tipo di agente su
Remote Agent (Vertex AI)(oRemote Agent Engine). - Inserisci l'ID progetto e la località (
us-central1) di Google Cloud, quindi fai clic su Carica agenti remoti. Verranno caricati gli agenti di cui è stato eseguito il deployment nel tuo progetto. - Seleziona l'agente
appdi cui hai eseguito il deployment dal menu a discesa Seleziona motore e fai clic su Salva e applica impostazioni. - Nella finestra di chat, digita una query mirata (ad esempio per recuperare i problemi o i repository recenti):
(In alternativa, provaGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") e premi Invio. - Osserva la UI della chat: poiché l'agente non dispone ancora delle credenziali per la tua sessione utente, riceve una richiesta di autenticazione e visualizza la scheda Autenticazione richiesta nel thread della conversazione.
Passaggio B: completa il consenso OAuth a tre vie
- Si aprirà una finestra popup del browser separata, che ti reindirizzerà tramite Auth Manager di Google Cloud alla pagina di autorizzazione OAuth di GitHub.
- Rivedi le autorizzazioni richieste e fai clic su Autorizza.
- GitHub ti reindirizzerà a Google Cloud, che reindirizza il popup al tuo
localhostURL di callback/validateUserId. - Il servizio di callback elabora e finalizza l'handshake delle credenziali.
Passaggio C: riprendi
- Una volta chiusa la finestra popup, la scheda della chat principale rileva automaticamente la chiusura.
- Il frontend invia un payload di ripresa all'agente.
- L'agente recupera in modo sicuro il token appena scambiato da Google Cloud Auth Manager, chiama gli strumenti MCP di GitHub per tuo conto e trasmette i dati di GitHub direttamente nella finestra della chat, dati che l'agente non avrebbe potuto raggiungere da solo.
Passaggio D: esamina i log di Cloud
Per verificare che lo scambio e la finalizzazione dei token siano stati elaborati in modo sicuro:
- Vai a Esplora log nella console Google Cloud.
- Individua i log del server che confermano l'estrazione del nonce e la convalida riuscita:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - Ispeziona i log di runtime dell'agente: in alternativa, puoi visualizzare i log di esecuzione direttamente nella console della piattaforma dell'agente:
- Vai alla console Agent Runtime.
- Fai clic sull'agente di cui hai eseguito il deployment nell'elenco.
- Passa alla scheda Playground. Nel riquadro inferiore verranno visualizzati i log dell'agente in tempo reale, che mostrano il ciclo di ragionamento dell'agente, i dettagli di esecuzione degli strumenti e il ciclo di vita del recupero dei token in tempo reale.
10. Elimina
Per evitare addebiti continui su Google Cloud, esegui la pulizia delle risorse di cui hai eseguito il deployment:
# 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
Elimina i file locali
Facoltativamente, per ripulire completamente l'ambiente locale:
- Arresta il server uvicorn locale premendo Ctrl+C nel terminale in cui è in esecuzione.
- Rimuovi le directory del progetto create durante questo lab:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. Complimenti!
Hai creato e protetto con successo un agente che agisce per conto dell'utente che ha eseguito l'accesso.
Che cosa hai imparato:
- Identità del sistema dell'agente: come l'agente opera con la propria identità dell'account per interfacciarsi in modo sicuro con l'infrastruttura GCP, gestire i log di telemetria e chiamare le API di finalizzazione delle credenziali.
- Identità delegata dell'utente: il modo in cui l'agente richiede l'autorizzazione ad agire per conto dell'utente su piattaforme esterne (come GitHub) attivando un flusso di consenso OAuth a tre vie (3LO).
- Integrazione sicura degli strumenti: come connettere gli agenti ADK ai server Model Context Protocol (MCP) utilizzando Google Cloud Auth Manager per recuperare dinamicamente i token utente anziché utilizzare secret impostati come hardcoded.
- Configurazione delle policy IAM: come configurare associazioni di autorizzazioni granulari per autorizzare sia l'identità di Agent Runtime sia il tuo account sul provider di autenticazione.
Per approfondire
- Gestore di autenticazione di Agent Identity per comprendere la configurazione e gli ambiti del flusso di autenticazione.
- Panoramica di Agent Runtime
- Documentazione ADK
- Model Context Protocol
