Next '26 Developer Keynote: Debugging Agents At Scale

1. Introduzione

In questo codelab, imparerai a eseguire il debug degli agenti AI in esecuzione su Google Cloud. Implementerai un agente simulatore in Agent Runtime, utilizzerai Cloud Observability per rilevare i problemi e Gemini Cloud Assist e l'IDE Antigravity per individuare la causa principale e correggere gli errori in tempo reale.

Il presupposto di questa demo è che abbiamo appena aggiunto ADK EventCompaction all'agente simulatore. In questo modo, il simulatore può riassumere periodicamente il suo flusso di lavoro utilizzando Gemini, riducendo il contesto totale inviato al modello a ogni turno, migliorando così la qualità della risposta e riducendo i costi totali. Tuttavia, scopriremo che esiste un bug in EventCompactionConfig, che causa errori nell'agente. Questo codelab illustra come trovare questo tipo di problema e risolverlo rapidamente.

Attività previste

• Esegui il deployment dell'agente Marathon Simulator in Agent Runtime.
• Configura un avviso di Cloud Monitoring per rilevare gli errori dell'agente.
• Analizza gli errori utilizzando Cloud Trace e Gemini Cloud Assist.
• Identifica la causa principale e applica una patch all'agente utilizzando Antigravity e MCP.

Nota: Gemini Cloud Assist è attualmente in anteprima privata. Non è necessario essere inclusi nella lista consentita per eseguire questo codelab con Cloud Assist. Tutti i passaggi di Cloud Assist sono isolati al punto 8 (facoltativo): utilizza le indagini di Cloud Assist. Salta questa pagina se non riesci ancora ad accedere a Cloud Assist.

Che cosa ti serve

• Un browser web come Chrome.
• Un Account Google
• Antigravity (supporta Mac, Linux e Windows)
• Python 3.13 o versioni successive.
• uv (gestore di pacchetti Python)

Durata stimata: 45 minuti

Costo stimato: meno di 5 $

2. Prima di iniziare

Crea un progetto Google Cloud

1. Nella console Google Cloud, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud.

Configura l'ambiente

Apri Antigravity e accedi. Poi, apri un terminale premendo cmd-shift-P (o ctrl-shift-P) e digitando "Create New Terminal" (Crea nuovo terminale).

1. Dal terminale, esegui l'autenticazione con Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Imposta l'ID progetto:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

Abilita API

Esegui il comando seguente per abilitare le API Cloud richieste:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Se sei nella lista consentita per Gemini Cloud Assist (anteprima privata), abilita queste API aggiuntive:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Configurare l'agente simulatore

In questo passaggio, clonerai il repository demo e configurerai le variabili di ambiente per l'agente simulatore.

Clona il repository

Clona il repository next-26-keynotes e vai alla directory demo:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Configura le variabili di ambiente

L'agente simulatore utilizza un file .env per la configurazione.

Individua il file sample.env sul lato sinistro della finestra di Antigravity (Esplora risorse):

Apri sample.env e aggiorna il campo GCP_PROJECT_ID con l'ID progetto Google Cloud effettivo. Il file dovrebbe essere simile a questo:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Stiamo abilitando le integrazioni OpenTelemetry per acquisire tracce granulari delle chiamate agli strumenti e del flusso di ragionamento dell'agente.

4. Esegui il deployment dell'agente simulatore in Agent Runtime

Ora eseguirai il deployment dell'agente in Agent Runtime utilizzando l'Agent Development Kit (ADK).

Installa le dipendenze

uv sync

Esegui il deployment in Agent Runtime

1. Esegui il comando adk deploy. Questo passaggio comprime l'agente ed esegue il deployment su Google Cloud (Agent Runtime).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

L'operazione potrebbe richiedere fino a 5 minuti. Alla fine dovresti vedere un output simile a questo:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Prendi nota dell'ID Agent Runtime generato. Ti servirà in un secondo momento.

2. Da un browser web, apri la console Agent Runtime. Dovresti vedere simulator_agent in esecuzione su Agent Runtime, con la raccolta di dati di telemetria abilitata.

5. Configura un criterio di avviso

Per rilevare automaticamente gli errori di runtime dell'agente, creerai un avviso basato su log nella console Google Cloud.

1. Vai alla console Cloud Monitoring - Avvisi.

2. Fai clic su Modifica canali di notifica. Scorri verso il basso fino al tipo Email, quindi crea un canale di notifica via email da inviare alla tua email personale. Fai clic su Salva.

3. Torna alla dashboard Avvisi e fai clic su Crea criterio.
4. Sul lato destro dello schermo, fai clic su Crea avviso basato sui log.

5. Si aprirà la pagina di Esplora log. Incolla la seguente query di log, sostituendo con il tuo ID progetto.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Questa query di log cerca i log Error all'interno dell'agente Agent Runtime, dove ReasoningEngine è il nome dell'API sottostante per Agent Runtime.

6. Fai clic su Esegui query. Non vedrai ancora alcun log, come previsto.
7. Fai clic su Azioni nella barra degli strumenti dei risultati, quindi fai clic su Crea avviso log.

8. Configura l'avviso basato su log. Assegna un nome all'avviso (qualsiasi), quindi imposta il livello di gravità su Errore.

9. Fai clic su Avanti per la sezione "Imposta la frequenza delle notifiche" (mantieni le impostazioni predefinite).

10. Per Chi dovrebbe ricevere le notifiche?, imposta l'avviso in modo che attivi il canale di notifica via email che hai appena configurato (ad es. My Email).
11. Fai clic su Salva.

6. Attiva l'incidente

Ora che l'agente è stato implementato e monitorato, proviamo a richiamare la simulazione della maratona in modo da generare un errore.

1. Nella console Google Cloud, vai alla console Agent Runtime.
2. Fai clic su simulator_agent.
3. Nella barra degli strumenti in alto, fai clic su Playground. Verrà avviata una nuova sessione con l'agente ADK.

4. Nella finestra della chat della sessione, digita Test Simulation e premi Invio per inviare il prompt.

Verrà avviata la simulazione della maratona, con il monitoraggio di migliaia di corridori simulati lungo il percorso pianificato. Dovresti vedere più chiamate di strumenti a get_runner_telemetry e analyze_medical_risk, poiché la simulazione valuta più "zone" della gara.

Dopo alcuni minuti, l'agente dovrebbe interrompere l'esecuzione e non restituire alcuna risposta.

5. Entro un minuto circa, dovresti ricevere un'email nella posta in arrivo che ti avvisa di un nuovo incidente nell'agente.

Fai clic su Visualizza incidente per aprire la console Cloud Monitoring. Vai alla pagina successiva per esaminare il problema all'interno della console.

7. Esamina l'incidente nella console

1. Visualizza l'incidente nella console Cloud Monitoring. Dovresti visualizzare i log degli errori provenienti dall'agente Simulator.

Da questa visualizzazione è difficile capire esattamente in quale punto l'agente non è riuscito a rispondere. Per visualizzare le chiamate agli strumenti e il flusso di ragionamento sottostanti dell'agente, esamineremo le tracce dell'agente.

2. Apri di nuovo la console Agent Runtime. Fai clic su simulator_agent, quindi apri la scheda Tracce.

3. Fai clic sulla traccia più recente nell'elenco. Poi, in alto a destra, fai clic su Cronologia. Dovresti vedere una visualizzazione della traccia con singoli "intervalli". Un intervallo rappresenta una chiamata di modello o strumento all'interno del flusso di lavoro dell'agente.

4. Fai clic sull'ultimo intervallo nella visualizzazione della traccia. Dovrebbe essere rosso.
5. Fai clic su Stacktrace. Dovresti visualizzare i log degli errori relativi a una chiamata del modello dell'API Gemini. Nello specifico, un errore 400: Invalid Argument. Indica un problema a livello di richiesta con un payload inviato dall'agente simulatore all'API Gemini.

8. [Facoltativo] Utilizza le indagini di Cloud Assist per il debug

Segui questi passaggi solo se sei nella lista consentita per Gemini Cloud Assist (anteprima privata). In caso contrario, procedi alla pagina successiva.

1. All'interno dell'intervallo non riuscito, fai clic su Log ed eventi. Trova il log "Eccezione" con il pulsante a forma di stella accanto. Quindi, fai clic su Analizza log.

2. Viene avviata un'indagine di Cloud Assist da una barra laterale sul lato destro dello schermo. Il caricamento richiederà circa 3-5 minuti.

3. Una volta completata, apri l'indagine.

4. Visualizza il Riepilogo dell'indagine.

5. Scorri verso il basso e visualizza le Ipotesi. Gemini Cloud Assist dovrebbe aver identificato la riga specifica del file agent.py dell'agente simulatore che genera l'errore 400 dell'API Gemini.

Analizziamo il problema in modo più approfondito aprendo il codice sorgente del nostro agente e utilizziamo Antigravity per trovare la causa principale del problema. Vai alla pagina successiva.

9. Utilizzare Antigravity per individuare la causa principale e correggere il problema

1. Riapri Antigravity.
2. Apri Agent Manager in alto a destra dello schermo.

3. Assicurati che il modello sia impostato su Gemini 3 Flash e sulla modalità Pianificazione.

4. Inserisci il seguente prompt e premi Invio.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Dovresti vedere Antigravity esaminare il codice in agent.py e cercare problemi pertinenti su GitHub:

La causa principale dell'errore 400 dell'API Gemini è che stiamo superando il limite di token del contesto di input di circa 1 milione di Gemini 3 Flash. Il motivo è che non attiviamo EventCompaction con la frequenza necessaria per riepilogare in modo efficace le risposte enormi delle chiamate di funzioni dello strumento Agenti simulatore.

Per risolvere il problema, Antigravity dovrebbe suggerire di aggiungere un parametro token_threshold a EventsCompactionConfig per comprimere periodicamente il contesto all'interno di ogni chiamata una volta raggiunto un determinato numero di token.

Ciò è in linea con la correzione suggerita in questo problema di GitHub.

Applica la correzione a agent.py.

Verifica di visualizzare un risultato simile a questo:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

È importante impostare token_threshold e event_retention_size.

10. Esegui nuovamente il deployment e convalida la correzione

Ora che abbiamo applicato la correzione token_threshold al EventCompactionConfig dell'agente ADK, possiamo rieseguire il deployment dell'agente simulatore in Agent Runtime.

1. Apri Antigravity > Nuovo terminale.
2. Imposta le variabili di ambiente. AGENT_RUNTIME_ID deve essere il nome risorsa completo del tuo simulator_agent. Puoi trovarlo nella console Agent Runtime, nell'elenco degli agenti.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Esegui nuovamente il deployment dell'agente:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

L'esecuzione richiederà alcuni minuti. Una volta completata l'operazione, dovresti visualizzare:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Apri la console Agent Runtime. Riapri simulator_agent. Fai clic su Playground.
5. Inserisci lo stesso prompt: Test Simulation, quindi premi Invio.
6. L'esecuzione della simulazione completa del backend Marathon dovrebbe richiedere alcuni minuti. Dovresti visualizzare più chiamate di strumenti. Alla fine, dovresti visualizzare una risposta simile a questa:

Ciò indica che il simulatore è stato eseguito correttamente. ✅

7. Apri la visualizzazione Traccia per la sessione ADK.
8. Dovresti vedere tutti gli intervalli "blu", senza errori rossi. Nota come il conteggio totale dei token delle sessioni superi il limite di 1 milione di token contestuali dell'API Gemini. Non preoccuparti, perché ora EventCompaction viene eseguito abbastanza spesso all'interno di ogni chiamata per evitare di superare il limite di contesto complessivo per le singole chiamate del modello.

🎊 Evviva! Abbiamo corretto l'errore nell'agente Simulator.

11. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi, elimina le risorse create durante questo codelab.

Eliminare l'app Agent Runtime

Puoi eliminare l'istanza Reasoning Engine tramite la console o utilizzando il comando gcloud (se hai il nome della risorsa). Per semplicità, utilizza la console:

1. Vai alla pagina Agent Runtime.
2. Seleziona simulator_agent -> fai clic sul pulsante con tre puntini sul lato destro.
3. Fai clic su Elimina.

Elimina il criterio Cloud Monitoring

1. Vai alla console Cloud Monitoring -> Avvisi.
2. Scorri verso il basso fino a Norme, poi fai clic sul pulsante con tre puntini per Eliminare le norme.

12. 🎊 Complimenti!

Complimenti! Hai appena eseguito il debug di un agente AI su Google Cloud.

Cosa hai imparato

• Come eseguire il deployment degli agenti in Agent Runtime.
• Come rilevare gli errori utilizzando gli avvisi di Cloud Monitoring.
• Come esplorare gli incidenti attivi utilizzando Cloud Logging e la visualizzazione delle tracce di Agent Runtime.
• Come analizzare gli errori utilizzando Gemini Cloud Assist.
• Come utilizzare Antigravity per identificare la causa principale e correggere i bug degli agenti.
• Come ottimizzare la compressione degli eventi ADK per gestire i turni degli agenti di lunga durata e con molti strumenti.

Passaggi successivi

• Scopri di più su Agent Runtime.
• Scopri di più sull'Agent Development Kit.
• Scopri di più sugli avvisi in Cloud Monitoring.
• Scopri di più su Gemini Cloud Assist.