Esegui il deployment di un agente ADK in Agent Runtime utilizzando Agents CLI

1. Panoramica

Questo lab fa parte del corso 5-Day AI Agents: Intensive Vibe Coding Course with Google di Kaggle. Puoi trovare ulteriori codelab e risorse disponibili sul sito dell'evento.

In questo codelab, esegui la transizione di un agente ADK 2.0 da un ambiente di sviluppo locale a un deployment di livello di produzione. Utilizzerai agents-cli per creare pacchetti, verificare e ospitare il tuo workflow basato su grafi in tempo reale in Agent Runtime su Google Cloud.

Per esplorare questo processo di deployment, creerai un prototipo locale dell'agente per le spese ambientali da zero prima di eseguirne il deployment sul cloud. Per approfondire la progettazione della logica di base di questo agente, consulta i codelab di base sul sito dell'evento Kaggle. L'agente per le spese ambientali semplifica la segnalazione delle spese dei dipendenti approvando immediatamente le richieste standard e segnalando le spese più elevate per la revisione umana in the loop. Sotto il cofano, utilizza un flusso di lavoro basato su grafici ADK 2.0 per coordinare questi passaggi di approvazione automatica e analisi del rischio.

Obiettivi didattici

• Come preparare il progetto locale Ambient Expense Agent per l'hosting sul cloud.
• Come creare i descrittori di deployment e i wrapper di produzione necessari.
• Come eseguire prove generali ed eseguire il deployment del codice direttamente in Agent Runtime.
• Come monitorare le tracce di esecuzione dell'agente di produzione utilizzando Cloud Trace.

Che cosa ti serve

• Un progetto Google Cloud attivo con la fatturazione abilitata.
• gcloud SDK installato e autenticato.
• Il gestore di pacchetti uv è installato.
• Google Antigravity IDE installato.

Prerequisiti

Questo codelab presuppone che tu abbia familiarità con:

• Navigare nel sistema utilizzando un terminale.
• Concetti di base dello sviluppo in Python.
• Concetti fondamentali di Google Cloud.

2. Configura il tuo ambiente Google Cloud

Prima del deployment, devi configurare il tuo progetto Google Cloud e abilitare le API necessarie.

👉 Prompt Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Quando Antigravity esegue questo prompt, propone ed esegue i comandi del terminale gcloud necessari per configurare il progetto e attivare i servizi. Durante il passaggio di autenticazione, Antigravity visualizzerà un URL di autorizzazione nel terminale. Fai clic sul link per accedere tramite il browser web e concedere l'accesso. Una volta completato l'accesso al browser, Antigravity riprenderà l'esecuzione per impostare le variabili di ambiente del progetto e abilitare le API richieste.

Nota: se si tratta di un nuovo progetto, gcloud potrebbe chiederti di abilitare prima l'API Service Usage. Se richiesto, segui il link fornito nel terminale per abilitarlo nella console Cloud.

3. Configurare Agents CLI e le skill ADK

Per creare ed eseguire il deployment degli agenti ADK in modo efficace, Antigravity ha bisogno del set di competenze ADK. Questi sono riferimenti raggruppati per l'API ADK, lo scaffolding del progetto, il flusso di lavoro di deployment agents-cli e la valutazione. L'installazione della toolchain agents-cli installa anche queste competenze nell'agente di codifica, dotandolo delle funzionalità per gestire l'intero ciclo di vita dell'agente, dallo scaffolding locale al deployment sul cloud.

👉 Copia e incolla il seguente prompt in Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Quando Antigravity esegue questo prompt, esegue uvx google-agents-cli setup nel terminale per installare la CLI e le relative competenze complementari. Quindi esegue agents-cli info per verificare l'installazione ed elenca le competenze del dominio appena installate (come google-agents-cli-deploy e google-agents-cli-workflow) direttamente nella chat.

Nota per gli utenti di Antigravity: durante questo codelab, Antigravity potrebbe generare piani di implementazione o visualizzare popup prima di eseguire comandi o scrivere codice. Assicurati di rivedere e approvare questi piani o popup per consentire ad Antigravity di procedere con le attività.

Suggerimento per la quota:se esaurisci la quota durante il test o lo sviluppo, passa a un altro modello disponibile in Antigravity.

4. Crea il progetto dell'agente

Con l'ambiente cloud configurato e le competenze CLI installate, puoi generare la base di codice locale per il tuo agente. In questo passaggio, utilizzi Antigravity per creare un prototipo di agente per le note spese ambientali completamente funzionante e compatibile con ADK 2.0.

Nota per gli utenti di Kaggle 5 days of AI Agents: se hai completato correttamente questo Codelab di Vibecode Ambient Expense Agent per il giorno 4 e preferisci eseguire il deployment della codebase dell'agente personalizzato esistente, puoi saltare questo passaggio di scaffolding e andare al passaggio successivo.

👉 Prompt Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Quando Antigravity esegue questo prompt, utilizza le competenze di scaffolding appena installate per eseguire agents-cli scaffold create expense-agent --adk nel terminale. Quindi, verificherà e modificherà il codice del prototipo generato per garantire che expense-agent implementi correttamente la soglia di approvazione automatica e il flusso di revisione human-in-the-loop nel workflow del grafico del suo Agent Development Kit (ADK).$100

5. Prepararsi al deployment in produzione

Agent Runtime è un servizio Google Cloud completamente gestito che ti consente di eseguire il deployment, gestire e scalare gli agenti AI in produzione. Agent Runtime gestisce le complessità operative dell'hosting, offrendo un ambiente stateful con funzionalità come la gestione delle sessioni, la memoria a lungo termine e sandbox di esecuzione del codice sicure.

Perché eseguire il deployment in Agent Runtime?

Quando crei agenti localmente con Antigravity, l'agente viene eseguito sulla macchina locale rispetto a localhost. Sebbene siano ideali per la prototipazione rapida, gli agenti locali smettono di funzionare nel momento in cui chiudi il laptop.

Il deployment dell'agente in Agent Runtime sposta il flusso di lavoro in un ambiente Google Cloud completamente gestito e sempre attivo. In questo modo, viene stabilito un endpoint backend sicuro e live che rimane attivo 24 ore su 24, 7 giorni su 7. Nel prossimo codelab, creerai un frontend web che si connette direttamente a questo endpoint cloud, fornendo al tuo agente un URL pubblico.

Inoltre, Agent Runtime fornisce un'infrastruttura dedicata ottimizzata specificamente per gli agenti AI, offrendo funzionalità integrate come:

• Esecuzione stateful gestita:gestione delle sessioni integrata e persistenza della memoria a lungo termine nei turni conversazionali.
• Sandboxing sicura:esegue in modo sicuro chiamate di strumenti dinamici e codice generato dall'agente in ambienti isolati.
• Osservabilità aziendale:streaming della telemetria preconfigurato direttamente su Cloud Trace e Cloud Logging.

Per ospitare l'agente su Agent Runtime, devi migliorare la directory del progetto locale con descrittori di produzione, schemi e wrapper degli endpoint.

👉 Prompt Antigravity:

Scaffold the production deployment files for Agent Runtime.

Quando Antigravity esegue questo prompt, esegue agents-cli scaffold enhance --deployment-target agent_runtime --yes nella radice del progetto. Questo comando esegue la scansione della directory e genera automaticamente:

• app/agent_runtime_app.py: Il wrapper del servizio di livello di produzione.
• deployment_metadata.json: lo schema di layout utilizzato da Agent Runtime per avviare le risorse.

La logica principale dell'agente in app/agent.py rimane completamente invariata e preservata.

6. Pacchettizzazione e verifica locale

Prima di avviare un caricamento sul cloud, blocca i pacchetti ed esegui una prova generale locale per identificare potenziali conflitti di dipendenze.

👉 Prompt Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Quando Antigravity esegue questo prompt, esegue prima uv lock nel terminale per generare un file di blocco deterministico, garantendo versioni coerenti della libreria nel cloud. Esegue quindi agents-cli deploy --dry-run per verificare la validità della configurazione e visualizzare l'anteprima dei passaggi di deployment senza eseguire il provisioning delle risorse cloud. Puoi esaminare l'output della prova generale nel terminale per verificare che tutti i file e le impostazioni siano corretti.

7. Esegui il deployment su Agent Runtime

Esegui il deployment dell'agente Ambient Expense in Agent Runtime.

👉 Prompt Antigravity:

Deploy this agent to Agent Runtime.

Quando Antigravity esegue questo prompt, attiva la skill google-agents-cli-deploy ed esegue agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. La procedura di creazione del pacchetto, caricamento e provisioning di Agent Runtime richiede in genere 5-10 minuti. Antigravity monitorerà l'avanzamento del deployment nel terminale e, una volta completato, visualizzerà l'URL dell'endpoint live.

💡 Suggerimento professionale (gestisci le finestre di timeout): se preferisci non bloccare il terminale durante le implementazioni lunghe, puoi indicare ad Antigravity di utilizzare il flag --no-wait per avviare l'implementazione in modo asincrono e controllare l'avanzamento in un secondo momento utilizzando agents-cli deploy --status.

Se hai problemi con il deployment dell'agente, valuta la possibilità di utilizzare un'altra regione. Lo strumento Google Cloud per la selezione della regione può aiutarti a determinare la regione migliore per il tuo progetto in base a latenza, prezzo e impatto ambientale.

8. Testare l'agente

Una volta implementato l'agente, puoi verificare che approvi automaticamente le piccole spese e che contrassegni correttamente le spese più grandi per una verifica umana.

👉 Chiedi ad Antigravity di verificare il motore di gioco live:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Nota:quando Antigravity esegue questo prompt di test sull'endpoint live, se rileva errori di deployment o esecuzione, tenta automaticamente di eseguire il debug del problema, applica le correzioni del codice necessarie e riesegue il deployment dell'agente.

In alternativa, puoi testare l'agente manualmente utilizzando l'anteprima di Cloud Console Playground. Per aprire Playground:

1. Nella console Google Cloud, utilizza il menu di navigazione per selezionare Agent Platform > Deployment.
2. Seleziona l'agente di cui è stato eseguito il deployment dall'elenco dei deployment.
3. Fai clic sul pulsante Playground per aprire l'interfaccia di chat di test interattiva.

👉 Per testare l'approvazione automatica(< 100 $), incolla il seguente payload JSON nella casella di chat:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Dovresti ricevere una risposta JSON che mostra l'output del nodo auto_approve con lo stato "approvato".

👉 Per testare il flusso Human-in-the-Loop (HITL), incolla il seguente payload JSON.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Verrà attivato review_agent, verrà emesso l'avviso e l'esecuzione verrà messa in pausa, generando un RequestInput (Human-in-the-loop) che richiede l'approvazione.

9. Monitorare e osservare l'agente di produzione

Con Agent Runtime, la telemetria viene configurata automaticamente. Ogni interazione, chiamata del modello ed esecuzione dello strumento trasmette log e intervalli in tempo reale al tuo progetto.

1. Ispeziona le tracce: apri la console Cloud Trace per controllare le mappe delle transazioni live, modellare le latenze e i passaggi di esecuzione dello strumento.
2. Audit log: utilizza Cloud Logging per esaminare l'output standard in tempo reale e le analisi dello stack di diagnostica.

3. Analytics aggregato: se il flag --bq-analytics è stato attivato durante lo scaffolding, esegui query sui log in BigQuery utilizzando SQL per visualizzare i tassi di approvazione e le tendenze dei turni conversazionali.

La seguente query SQL fornisce un esempio per il calcolo dei tassi di approvazione. Puoi chiedere ad Antigravity di personalizzare questa query per il tuo progetto specifico e il set di dati BigQuery:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (Facoltativo) Verifica la registrazione in Agent Registry

Per consentire ad altri servizi, sviluppatori o agenti della tua organizzazione di scoprire e utilizzare in modo sicuro il tuo agente per le note spese, quest'ultimo deve essere registrato nel registro degli agenti aziendale (Gemini Enterprise).

Poiché hai eseguito il deployment dell'agente in Agent Runtime, viene registrato automaticamente in Agent Registry. Eventuali aggiornamenti o eliminazioni futuri dell'agente in Agent Runtime verranno sincronizzati automaticamente anche con il registro degli agenti.

👉 Chiedi ad Antigravity di verificare la registrazione automatica dell'agente:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Quando Antigravity esegue questo prompt, esegue agents-cli publish gemini-enterprise --list nel terminale. Esegue una query in Agent Registry ed elenca tutti gli agenti Gemini Enterprise registrati nel tuo progetto, consentendoti di verificare che Ambient Expense Agent sia attivo e rilevabile in tutta l'organizzazione.

11. Esegui la pulizia

Partecipanti al corso Kaggle: se stai completando questo lab nell'ambito del corso 5-Day AI Agents di Kaggle e prevedi di passare al lab successivo (Vibecode and Deploy a Frontend for an ADK Agent) per creare il client frontend e l'integrazione Pub/Sub, non eliminare l'agente di cui è stato eseguito il deployment. Avrai bisogno di questa infrastruttura cloud attiva per il lab successivo.

Per evitare che al tuo account Google Cloud vengano addebitati costi continui, devi arrestare e liberare spazio dalle risorse di cui è stato eseguito il deployment al termine dell'operazione.

👉 Prompt Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Quando Antigravity esegue questo prompt, automatizza l'intero processo di pulizia delle risorse:

1. Elimina l'agente di cui è stato eseguito il deployment: legge deployment_metadata.json per ottenere l'ID runtime dell'agente remoto, quindi elimina a livello di programmazione l'istanza del motore live da Vertex AI.
2. Pulisci workspace locale: rimuove il file deployment_metadata.json obsoleto dalla radice del progetto.
3. Pulisci Artifact Registry: esegue gcloud artifacts docker images delete per rimuovere le immagini container create da Artifact Registry, liberando spazio di archiviazione cloud.

12. Complimenti

Complimenti! Hai eseguito il deployment e la verifica di un agente Ambient Expense di livello di produzione su Google Cloud.

Che cosa hai imparato

• Configurazione di Google Cloud: sono state configurate le credenziali del progetto e sono state attivate le API della piattaforma richieste.
• Strumenti e competenze: agents-cli installato e competenze complementari ADK caricate in Antigravity.
• Impalcatura di produzione: impalcatura di Agent Runtime generata per un agente ADK 2.0.
• Verifica locale: sono stati creati file di blocco deterministici (uv lock) ed eseguiti controlli di prova.
• Deployment cloud: l'agente è ospitato live sull'infrastruttura di Agent Runtime gestita.
• Osservabilità e analisi: esecuzione tracciata in Cloud Trace e telemetria analizzata in BigQuery.
• Enterprise Discovery: registrazione automatica verificata nel registro degli agenti dell'azienda.

Passaggi successivi

• Esegui BigQuery Analytics: esegui query sui log di telemetria del tuo agente in BigQuery per analizzare i tassi di approvazione e le tendenze dei turni conversazionali nel tempo.
• Codelab Vibe to Live: utilizza Google Antigravity per sviluppare un client frontend su Cloud Run e connettilo direttamente all'endpoint di backend di Agent Runtime live.

Ottieni il badge Agenti AI di Kaggle in 5 giorni 🎉

Hai completato questo lab nell'ambito del corso intensivo di programmazione 5-Day AI Agents: Intensive Vibe Coding Course with Google di Kaggle? Richiedi il tuo badge di completamento:

Ottieni il badge Agenti AI di 5 giorni

Riferimenti

• Documentazione di Agent Development Kit (ADK)
• Runtime della piattaforma agentica Gemini Enterprise
• Guida di riferimento di Agents CLI (agents-cli)
• Panoramica del registro degli agenti Gemini Enterprise
• Documentazione di Google Cloud Trace