Crea un agente con ADK e Agents CLI in Agent Platform

Questo documento mostra come creare, valutare ed eseguire il deployment di un prototipo di agente AI utilizzando l'Agent Development Kit (ADK) con l'interfaccia a riga di comando Agents in Agent Platform. L'ADK è un framework open source code-first per la creazione di agenti AI sofisticati. Agents CLI fornisce un'interfaccia unificata e leggibile da macchina per consentire agli strumenti di sviluppo dell'AI di interagire con l'ADK, consentendo la gestione end-to-end del ciclo di vita degli agenti. Racchiude pattern di progettazione e best practice per ADK, valutazione degli agenti e deployment suGoogle Cloud, consentendo agli strumenti per sviluppatori AI di eseguire azioni complesse da prompt in linguaggio naturale.

Utilizzando Agents CLI con lo strumento per sviluppatori basato sull'AI che preferisci, come Gemini CLI, Claude Code o Codex, puoi utilizzare prompt in linguaggio naturale per definire, testare localmente ed eseguire il deployment di un agente prototipo in un runtimeGoogle Cloud .

Questo tutorial ti guida nella creazione di un agente "compressore cavernicolo", che trasforma il testo dettagliato in riassunti concisi, ispirati ai cavernicoli.

Prima di iniziare

Completa i seguenti prerequisiti:

  1. Assicurati di avere un progetto Google Cloud e di aver abilitato l'API Agent Platform. In caso contrario, completa una delle seguenti guide rapide:

  2. Installa uno strumento per sviluppatori basato sull'AI, come Antigravity, Gemini CLI, Claude Code o Codex. Questo strumento è necessario per interagire con l'interfaccia a riga di comando degli agenti.

Configurazione

  1. Installa uv, un programma di installazione di pacchetti Python. Per istruzioni, consulta la guida all'installazione di uv.

  2. Esegui il comando di configurazione di Agents CLI utilizzando uvx (incluso in uv). Questo è l'unico comando di Agents CLI che esegui direttamente:

    uvx google-agents-cli setup
    
  3. Apri lo strumento per sviluppatori AI, ad esempio Antigravity.

Progetto di scaffolding

Istruisci il tuo strumento per sviluppatori AI con il seguente prompt:

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

Lo strumento per sviluppatori AI attiva le competenze di google-agents-cli-workflow e google-agents-cli-scaffold. Esegue le seguenti azioni:

  • Pone domande di chiarimento, ad esempio sul target di deployment e sui vincoli di sicurezza.
  • Scrive un file DESIGN_SPEC.md che acquisisce lo scopo dell'agente.
  • Crea lo scaffolding del progetto:

    agents-cli create caveman-agent --prototype --yes
    cd caveman-agent && agents-cli install
    

Questo processo crea un progetto con codice dell'agente boilerplate, test e set di valutazione.

Crea agente

Lo strumento per sviluppatori AI modifica app/agent.py, sostituendo l'agente predefinito con la logica del compressore dell'uomo delle caverne. Utilizza la skill google-agents-cli-adk-code per i pattern di progettazione ADK.

La definizione dell'agente risultante è simile alla seguente:

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="""You are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules:
   - Omit articles, filler words, and politeness.
   - Use short sentences and simple words.
   - Preserve technical terms.
   - The tone should be abrupt and funny, but the core meaning must be retained.

   Example input:  "I would like to deploy the application to production environment."
   Example output: "Me deploy. Production. Now."
   """,
)

Lo strumento per sviluppatori AI esegue quindi un test funzionale di base:

agents-cli run "Please help me understand the deployment options available for my project"

Questo è l'output previsto dal test:

"Opzioni di deployment: Agent Runtime, Cloud Run, GKE. Scegline una. Spedisci."

Valuta agente

Per valutare l'agente, fornisci allo strumento per sviluppatori AI il seguente prompt:

Write evaluations for the caveman agent and run them.

Lo strumento per sviluppatori AI attiva la skill google-agents-cli-eval ed esegue queste attività:

  • Crea tests/eval/evalsets/caveman.evalset.json con scenari di test che coprono la qualità della compressione, la conservazione dei termini tecnici e il tono.
  • Configura i criteri LLM-as-a-judge in tests/eval/eval_config.json.
  • Esegue la valutazione:

    agents-cli eval run
    

Se gli scenari di test non vanno a buon fine, fornisci un feedback correttivo allo strumento per sviluppatori AI. Ad esempio:

La risposta al test di saluto è troppo educata. Rendilo più brusco.

Lo strumento per sviluppatori AI modifica le istruzioni dell'agente, esegue nuovamente agents-cli eval run e itera fino a raggiungere la qualità desiderata.

Fai il deployment dell'agente

Per eseguire il deployment e l'agente su Google Cloud, istruisci lo strumento di sviluppo AI come segue:

Deploy this agent to Cloud Run.

Lo strumento per sviluppatori AI attiva lo skill google-agents-cli-deploy e:

  • Aggiunge la configurazione dell'infrastruttura di deployment necessaria:

    agents-cli scaffold enhance --deployment-target cloud_run
    
  • Esegue il deployment dell'agente:

    agents-cli deploy
    

Il deployment dell'agente è stato eseguito su Cloud Run. L'output include l'URL del servizio, che utilizzi per accedere all'agente.

Osserva l'agente

Cloud Trace è abilitato per impostazione predefinita. Per visualizzare le tracce, apri Esplora tracce di Cloud Trace nella console Google Cloud e invia richieste all'agente di cui hai eseguito il deployment. Vedrai gli intervalli per le chiamate LLM e le esecuzioni degli strumenti.

Per abilitare un'osservabilità più dettagliata, istruisci il tuo strumento per sviluppatori AI:

Set up observability infrastructure for my agent.

Lo strumento per sviluppatori AI esegue il provisioning di un account di servizio, di un bucket Cloud Storage e di un set di dati BigQuery e aggiorna il servizio di cui è stato eseguito il deployment per utilizzare queste risorse. Per maggiori dettagli, consulta la Guida all'osservabilità.

Riepilogo delle azioni

Questa tabella riassume i prompt e le azioni corrispondenti eseguite dallo strumento per sviluppatori AI:

Istruzione per l'utente Azioni dello strumento per sviluppatori AI
"Crea un agente compressore per l'uomo delle caverne" Crea l'impalcatura del progetto, scrive il codice dell'agente, esegue i test localmente.
"Scrivi le valutazioni ed eseguile" Crea un set di valutazione, configura LLM-as-a-judge, esegue agents-cli eval run.
"Esegui il deployment in Cloud Run" Aggiunge la configurazione della destinazione di deployment ed esegue il deployment in Cloud Run.
"Configura l'osservabilità" Esegue il provisioning account di servizio, del bucket Cloud Storage e del set di dati BigQuery.

Le competenze di Agents CLI forniscono il contesto necessario affinché lo strumento di sviluppo AI utilizzi i pattern ADK appropriati, strutturi le valutazioni e configuri i deployment.

Passaggi successivi

Esplora design di agenti più complessi con questi prompt:

  • Aggiungi strumenti: "Integra uno strumento della Ricerca Google in modo che l'agente possa accedere alle informazioni aggiornate."
  • Sistemi multi-agente: "Crea un agente che possa interagire con altri agenti utilizzando il modello adk_a2a."
  • RAG: "Crea un agente che risponda alle domande in base alla nostra documentazione utilizzando il modello agentic_rag."

Scopri di più su Agent Platform: