Creare un agente AI che agisca per conto dell'utente con Agent Identity e Auth Manager

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 e nient'altro.

Lo creerai con Google Agent Development Kit (ADK) e Gemini Enterprise.

Nello specifico, imparerai a progettare un'architettura a doppia identità in cui:

1. L'agente agisce per proprio conto (identità dell'agente): utilizzando un'identità dell'agente basata su SPIFFE, l'agente richiama Auth Manager, archivia la telemetria e chiama le API Google Cloud.
2. 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 passaggi (3LO) per eseguire query in modo sicuro sugli strumenti utilizzando le credenziali dell'utente.

Per farlo, imparerai a:

1. Crea un agente ADK che si connette al server Model Context Protocol (MCP) di GitHub.
2. Aggiorna lo strumento dell'agente da un PAT (token di accesso personale) GitHub statico al flusso OAuth a 3 vie (3LO) utilizzando Google Cloud Auth Manager.
3. Esegui il deployment dell'agente in modo sicuro in Agent Runtime e il provisioning di Agent Identity.
4. Configura i ruoli IAM per fornire l'accesso all'identità dell'agente al token vault per conto dell'utente.
5. 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 la fatturazione abilitata.
• Google Cloud SDK (gcloudCLI) installato e autenticato nel tuo progetto sulla tua macchina locale. È necessaria la versione 586.0.0 o successive: esegui gcloud components update.
• Python 3.10-3.13 installato localmente.
• Il gestore di pacchetti uv è installato (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 passaggi.

2. Configurazione del progetto

1. Esegui l'autenticazione in Google Cloud

Esegui l'autenticazione a Google Cloud dalla riga di comando locale per assicurarti che il tuo ambiente disponga delle autorizzazioni necessarie per il deployment in Agent Runtime, il provisioning di Agent Identity e la configurazione di Auth Manager durante questo lab:

Esegui questi comandi per accedere al tuo account Google Cloud e configurare le credenziali predefinite dell'applicazione (ADC):

gcloud auth login
gcloud auth application-default login

2. Attiva 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, verrà visualizzato il 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, gestire, testare ed eseguire il deployment di agenti ADK in Gemini Enterprise. Installalo localmente:

uvx google-agents-cli setup

Verifica l'installazione:

agents-cli --help

Dovresti visualizzare il menu di assistenza della CLI con i comandi disponibili (ad esempio deploy, run e status).

Genera la struttura 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

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

Il pyproject.toml generato include google-adk[gcp,otel-gcp], a cui mancano due componenti aggiuntivi necessari a questo agente: mcp per il set di strumenti GitHub e agent-identity per Auth Manager più avanti nel lab. Apri secure-agent-demo/pyproject.toml e modifica la riga google-adk in:

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

Quindi 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 nel file 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 per l'autenticazione in caso di errori).
• Configurazione dell'agente (root_agent): crea un'istanza di un ADK Agent utilizzando il modello gemini-3.8-flash, configura la logica di ripetizione dei tentativi HTTP e dota l'agente del set di strumenti GitHub.
• Wrapper app (app): incapsula l'agente principale in un contenitore ADK App, rendendolo implementabile in Agent Runtime.

2. Aggiungere lo strumento MCP di GitHub

L'agente si connette a GitHub tramite il Model Context Protocol (MCP). Crea un nuovo file denominato tools.py nella cartella app/ 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:

• Strumenti MCP (McpToolset): rileva e registra dinamicamente le funzionalità di GitHub come strumenti di agenti richiamabili.
• Parametri di connessione (StreamableHTTPConnectionParams): indirizza il toolset al gateway MCP pubblico di GitHub.
• Intestazioni di autorizzazione: inserisce GITHUB_TOKEN come token Bearer e applica la modalità di sola lettura (X-MCP-Readonly: true) direttamente al livello di trasporto.

3. Testare localmente con un PAT (Personal Access Token) di GitHub

Per eseguire l'agente localmente con credenziali statiche:

1. Crea un token di accesso personale GitHub. Concedi l'accesso in lettura ai tuoi repository, altrimenti l'agente può visualizzare solo i dati pubblici e il prompt seguente non restituisce nulla.
2. Impostalo nel tuo ambiente:

   export GITHUB_TOKEN="your_github_pat_here"
   

3. Vai alla cartella secure-agent-demo. Esegui:

   cd secure-agent-demo
   agents-cli playground
   

4. Apri l'interfaccia del playground e seleziona la cartella "app" dal menu a discesa. Nella casella di chat, digita "Fetch my contributions across my private repositories over the last 6 months" e verifica che l'agente chiami lo strumento GitHub e restituisca i dati dai tuoi repository privati.

4. Configura Auth Manager

Sebbene la codifica hardcoded delle credenziali statiche (come un PAT) sia comoda per la prototipazione, espone le applicazioni di produzione alla perdita di credenziali, ai tempi di inattività per l'aggiornamento manuale dei token e a una mancanza di controlli dell'accesso cloud-native.

Per risolvere questo problema, Google Cloud fornisce gestore di autenticazione di Agent Identity. Agent Identity auth manager è un archivio di credenziali progettato per proteggerle. 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 token di accesso per gli utenti finali.

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 viene eseguito il deployment dell'agente. Il workflow Auth Manager end-to-end funziona nel seguente modo:

1. 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 passaggi (3LO).
2. Archiviazione sicura di Vault: una volta che l'utente finale autorizza l'applicazione, Auth Manager intercetta automaticamente il callback OAuth e archivia i token di accesso e aggiornamento dell'utente risultanti in un vault delle credenziali sicuro e gestito da Google.
3. Ciclo di vita automatico dei token: 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à.
4. Esecuzione dello strumento senza secret: per le azioni successive, l'agente (che esegue l'autenticazione tramite la propria Agent Identity SPIFFE) richiede dinamicamente il token di accesso delegato dell'utente ad Auth Manager in fase di runtime, mantenendo il codice client e dell'agente completamente privo di secret.

Importante: in questo codelab vedrai variabili segnaposto in maiuscolo (ad esempio YOUR_PROJECT_ID, YOUR_PROJECT_NUMBER, YOUR_ORG_ID e YOUR_ENGINE_ID). Assicurati di sostituirle con i valori del tuo progetto Google Cloud e delle tue risorse quando esegui i comandi.

Passaggio A: configura GitHub come provider di autenticazione

Esegui questo comando gcloud per creare un provider di autenticazione GitHub nel tuo progetto Google Cloud. Fornisci l'ID client e il client 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="${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="${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="${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

1. Vai alla pagina delle impostazioni per sviluppatori di GitHub e fai clic su Registra una nuova app OAuth.
2. Per l'URL della home page, inserisci l'URL della tua applicazione frontend (ad es. http://localhost:8501 per la prototipazione locale). In un secondo momento puoi modificarlo e impostare l'URL di cui è stato eseguito il deployment in produzione.
3. Imposta l'URI di reindirizzamento su redirectUrl recuperato nel passaggio precedente.
4. Fai clic su Registra applicazione, poi su Genera un nuovo client secret e salva sia l'ID client che il client secret.

Passaggio C: aggiungi le credenziali GitHub al provider di autenticazione

Sostituisci l'ID progetto, l'ID client e il client secret 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 ripete il provider con clientId visibile; il segreto non viene ripetuto.

👉 Una volta completato questo passaggio, Google Cloud Auth Manager è ora completamente configurato con le credenziali dell'applicazione GitHub OAuth, impostando Google Cloud in modo che funga da vault sicuro che gestisce il consenso e i cicli di vita dei token.

5. Passare dal token PAT ad Auth Manager

Ora che Auth Manager è completamente configurato, il passaggio successivo consiste nell'aggiornamento del codice dello strumento dell'agente. Sostituisci app/tools.py con il seguente codice.

👉 Sostituisci l'ID progetto e la località nella variabile OAUTH_PROVIDER_NAME riportata 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 chiama 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 GITHUB_TOKEN codificato è stato completamente rimosso.

6. Esegui il deployment dell'agente in Agent Runtime

Ora che abbiamo aggiornato lo strumento GitHub MCP per utilizzare Auth Manager, il passaggio successivo consiste nel deployment dell'agente in Agent Runtime. La sua implementazione con Agent Identity abilitato fornisce un ID SPIFFE univoco per l'agente.

Iniziamo inizializzando la configurazione del deployment per il progetto. Esegui nel terminale:

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

Questo comando esamina la struttura del progetto per verificare la compatibilità con l'ADK, prepara le configurazioni di packaging dei container sottostanti e genera un file agents-cli-manifest.yaml nella 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 a us-central1 per assicurarti che l'agente venga implementato nella stessa regione del tuo fornitore di autenticazione:

region: "us-central1"

Esegui il deployment dell'agente con un'Agent Identity

Esegui il deployment con adk deploy agent_engine. In questo modo viene eseguito il provisioning dell'agente con la propria Agent Identity, un'identità crittografica unica supportata da SPIFFE appartenente a questo deployment, che l'agente utilizza per l'autenticazione in Auth Manager e in altri servizi Google Cloud.

👉 Sostituisci YOUR_PROJECT_ID prima di eseguire questi comandi:

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

Il deployment richiede alcuni minuti per creare e caricare il container. Al termine, la CLI stampa il nome della risorsa di cui è stato eseguito il deployment. Prendi nota del valore di reasoningEngines/ENGINE_ID, in quanto ti servirà per autorizzare l'agente e per indirizzare il client UI.

Utilizza adk deploy agent_engine, non agents-cli deploy --agent-identity. Entrambi vengono implementati correttamente, ma producono forme di risorse diverse. agents-cli deploy crea un server contenitore senza classMethods; il client UI che esegui in un secondo momento chiama create_session() sull'agente di cui è stato eseguito il deployment e non riesce a eseguire l'operazione con 'AgentEngine' object has no attribute 'create_session'. adk deploy agent_engine produce la forma serializzata AdkApp, che espone i 13 metodi necessari al client.

Dove viene indirizzato l'utente dopo il consenso: una volta che un utente approva l'accesso, il suo browser viene inviato all'indirizzo in OAUTH_CONTINUE_URI, che viene gestito dalla tua applicazione client. In questo lab, il client viene eseguito sulla tua macchina, quindi l'agente utilizza il valore predefinito già impostato in app/tools.py (http://localhost:8501/validateUserId) e non devi modificare nulla. Se in un secondo momento ospiti il client altrove, aggiorna il valore predefinito prima del deployment.

Autorizzare l'identità dell'agente

Ora che l'agente è in esecuzione nel cloud, ha bisogno dell'autorizzazione per accedere alle credenziali archiviate in Auth Manager. Per impostazione predefinita, l'identità SPIFFE dell'agente non ha accesso alle risorse cloud esterne.

Esegui il seguente comando gcloud per concedere il ruolo roles/agentidentity.user all'identità dell'agente nella risorsa del provider di autenticazione. In questo modo, all'agente vengono concesse le autorizzazioni esatte necessarie per richiedere token utente dal vault e nient'altro.

👉 Sostituisci YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER e YOUR_ENGINE_ID (l'ID motore si trova nell'output del deployment riportato sopra).

Per ottenere YOUR_ORG_ID, esegui il comando riportato di seguito:

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"

Ora concedi al tuo account lo stesso ruolo sul fornitore. Il client UI che esegui nel passaggio successivo chiama l'API di finalizzazione delle credenziali con le credenziali predefinite dell'applicazione, quindi senza questo passaggio il flusso di consenso non va a buon fine e viene visualizzato 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"

Questo secondo binding è necessario solo per eseguire il lab in locale. Consente al client sulla tua macchina di finalizzare il consenso utilizzando le tue credenziali. In produzione, il client viene eseguito con la propria identità ed è necessario solo il binding dell'agente riportato sopra.

7. Informazioni sul flusso di consenso di terze parti

Ora che l'agente è stato eseguito il deployment in Agent Runtime con un'Agent Identity sicura, il passaggio successivo è 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 ciclo di autenticazione.

Sebbene Google Cloud Auth Manager gestisca in modo sicuro le credenziali utente all'interno di un vault, non può completare lo scambio di token OAuth autonomamente. L'handshake 3LO si basa sull'applicazione client per colmare il divario:

1. Quando un utente autorizza l'app GitHub, GitHub lo reindirizza al redirectUrl del provider di autenticazione di Agent Identity .
2. Auth Manager reindirizza quindi il popup del browser dell'utente a un URL di callback lato client (continue_uri).
3. È responsabilità dell'applicazione client intercettare questo reindirizzamento, leggere il nonce dai cookie del browser e chiamare l'endpoint credentials:finalize di Google Cloud per completare l'handshake.
4. Una volta che il client finalizza 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 riportata di seguito e nel passaggio successivo.

👉 Fai clic sull'immagine per ingrandirla.

Responsabilità principali del client nell'handshake

• Trasmetti la richiesta di consenso (passaggi 5-6): l'agente emette un adk_request_credential contenente l'URL del 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 archivia il token nel vault.

Creare il tuo client

Non devi scrivere questo client per il lab: il passaggio successivo ne esegue uno predefinito. Quando implementi questa funzionalità nella tua applicazione, puoi fare riferimento a questi due elementi:

• Aggiorna l'applicazione lato client nella documentazione di Auth Manager, che illustra la gestione della richiesta di consenso e la chiamata di credentials:finalize.
• Il client di esempio eseguibile nel repository adk-python. Leggi main.py per un'implementazione completa e funzionante delle tre responsabilità sopra indicate.

8. Esegui il client UI localmente

Come abbiamo visto nel diagramma di sequenza del flusso di consenso 3LO, Auth Manager deve reindirizzare il popup del browser a un endpoint di callback lato client. Il client di esempio ospita questo endpoint all'indirizzo /validateUserId. Eseguiamola localmente.

Copia i file del client in Locale

Vai alla cartella gcp_auth/client nel repository GitHub adk-python. Questa cartella contiene gli asset necessari per creare il nostro contenitore client di chat.

👉 Copia tutti i file in gcp_auth/client nel tuo ambiente locale:

• main.py: lo script dell'applicazione FastAPI contenente il callback di finalizzazione del token (/validateUserId) di cui abbiamo parlato nella sezione precedente.
• static/: contiene le pagine HTML.

In alternativa, puoi anche eseguire un checkout parziale della 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

1. Vai alla cartella client che hai appena copiato:

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

2. Crea un ambiente virtuale e installa le dipendenze del client. La cartella include un requirements.txt e nessun pyproject.toml, quindi uv run uvicorn ... da solo non funziona e restituisce 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. Punta il client all'agente che hai implementato, quindi avvialo sulla 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. Verifica che il server sia stato avviato correttamente e sia in ascolto su http://localhost:8501.

Utilizza localhost, non 127.0.0.1. Il reindirizzamento OAuth richiede il nome host localhost; i due non sono intercambiabili qui anche se si risolvono nello stesso indirizzo.

9. Testare il flusso OAuth

Ora che tutti i servizi sono stati implementati, i binding IAM sono configurati e le variabili di ambiente sono impostate, puoi testare il flusso di autorizzazione delegata dall'utente end-to-end sicuro.

Passaggio A: avvia l'esecuzione dello strumento

1. Apri una scheda del browser e vai all'URL client: http://localhost:8501.
2. Nel riquadro a sinistra, imposta il tipo di agente su Remote Agent Engine.
3. Digita il progetto Google Cloud e la località. Fai clic su Load Remote Agents. Dovrebbero essere caricati tutti gli agenti di cui è stato eseguito il deployment nel tuo progetto.
4. Seleziona l'agente giusto dal menu a discesa e salva le impostazioni.
5. Nella casella della chat, digita:

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

   e premi Invio.
6. Osserva la UI della chat: poiché l'agente non dispone ancora delle credenziali per la 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

1. Si aprirà una finestra popup separata del browser, che ti reindirizzerà tramite Auth Manager di Google Cloud alla pagina di autorizzazione OAuth di GitHub.
2. Rivedi le autorizzazioni richieste e fai clic su Autorizza.
3. GitHub reindirizzerà di nuovo a Google Cloud, che reindirizza il popup all'localhost URL di callback /validateUserId.
4. Il servizio di callback elabora e finalizza l'handshake delle credenziali.

Passaggio C: riprendi

1. Una volta chiusa la finestra popup, la scheda della chat genitore rileva automaticamente la chiusura.
2. Il frontend invia un payload di ripresa all'agente.
3. L'agente recupera il token appena scambiato in modo sicuro da Google Cloud Auth Manager, chiama gli strumenti GitHub MCP per tuo conto e trasmette in streaming i dati dai tuoi repository privati 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:

1. Vai a Esplora log nella console Google Cloud.
2. 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.
   

3. Esamina i log di Agent Runtime: in alternativa, puoi visualizzare i log di esecuzione direttamente nella console di Agent Platform:
   • Vai alla console Agent Runtime.
   • Fai clic sull'agente di cui è stato eseguito il deployment nell'elenco.
   • Passa alla scheda Playground. Nel riquadro inferiore vengono visualizzati i log dell'agente live, che mostrano il ciclo di ragionamento dell'agente, i dettagli di esecuzione dello strumento e il ciclo di vita del recupero dei token in tempo reale.

10. Elimina

Per evitare addebiti continui su Google Cloud, libera spazio dalle risorse di cui è stato 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

Liberare spazio nei file locali

(Facoltativo) Per liberare spazio nell'ambiente locale:

1. Arresta il server uvicorn locale premendo Ctrl+C nel terminale in cui è in esecuzione.
2. 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 correttamente un agente che agisce per conto dell'utente che ha eseguito l'accesso.

Cosa hai imparato:

• Identità di sistema dell'agente: come l'agente opera con la propria identità dell'account per interfacciarsi in modo sicuro con l'infrastruttura Google Cloud, gestire i log di telemetria e chiamare le API di finalizzazione delle credenziali.
• Identità delegata dall'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 passaggi (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 hardcoded.
• Configurazione delle policy IAM: come configurare binding delle 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