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 Agent Development Kit (ADK) con l' interfaccia a riga di comando Agents in Agent Platform. ADK è un framework open source code-first per la creazione di agenti AI sofisticati. L'interfaccia a riga di comando Agents fornisce un'interfaccia unificata e leggibile dalla macchina per gli strumenti di sviluppo AI per interagire con ADK, consentendo la gestione end-to-end del ciclo di vita degli agenti. Incapsula la conoscenza esperta di ADK, la valutazione degli agenti e il deployment Google Cloud, consentendo agli strumenti di sviluppo AI di eseguire azioni complesse dai prompt in linguaggio naturale.

Utilizzando l'interfaccia a riga di comando Agents con lo strumento di sviluppo basato sull'AI che preferisci, come Gemini CLI, Claude Code o Codex, puoi utilizzare i prompt in linguaggio naturale per definire, testare localmente ed eseguire il deployment di un agente prototipo in un Google Cloud runtime.

Questo tutorial ti guida nella creazione di un agente "compressore di uomini delle caverne", che trasforma il testo dettagliato in riepiloghi concisi, ispirati a uomo delle caverne.

Prima di iniziare

Completa i seguenti prerequisiti:

Assicurati di avere un Google Cloud progetto e di aver abilitato l'API Agent Platform. In caso contrario, completa una delle seguenti guide rapide:
- Google Cloud Guida rapida alla console per Agent Studio per la piattaforma agentica Gemini Enterprise
- Guida rapida all'API per i modelli
Installa uno strumento di sviluppo basato sull'AI, come Antigravity, Gemini CLI, Claude Code o Codex. Questo strumento è necessario per interagire con l'interfaccia a riga di comando Agents.

Configurazione

Installa uv, un programma di installazione dei pacchetti Python. Per istruzioni, consulta la guida all'installazione di uv.
Esegui il comando di configurazione dell'interfaccia a riga di comando Agents utilizzando uvx (incluso in uv). Questo è l'unico comando dell'interfaccia a riga di comando Agents che esegui direttamente:
```
uvx google-agents-cli setup
```
Apri lo strumento di sviluppo AI, ad esempio Antigravity.

Impalcatura del progetto

Istruisci lo strumento di sviluppo AI con il seguente prompt:

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

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

Pone domande chiarificatrici, come la destinazione di deployment e i vincoli di sicurezza.
Scrive un file DESIGN_SPEC.md che acquisisce lo scopo dell'agente.

Impalcatura del progetto:

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

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

Crea agente

Lo strumento di sviluppo AI modifica app/agent.py, sostituendo l'agente predefinito con la logica del compressore di uomini delle caverne. Utilizza la competenza 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-flash-latest"),
   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 di sviluppo AI esegue quindi un test di funzionalità 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, istruisci lo strumento di sviluppo AI con il seguente prompt:

Write evaluations for the caveman agent and run them.

Lo strumento di sviluppo AI attiva la competenza google-agents-cli-eval ed esegue le seguenti attività:

Crea tests/eval/evalsets/caveman.evalset.json con casi di test che riguardano la qualità della compressione, la conservazione dei termini tecnici e il tono.
Configura i criteri LLM-as-judge in tests/eval/eval_config.json.
Esegue la valutazione:
```
agents-cli eval run
```

Se i casi di test non vanno a buon fine, fornisci un feedback correttivo allo strumento di sviluppo AI. Ad esempio:

La risposta al test di saluto è troppo educata. Rendila più brusca.

Lo strumento di sviluppo AI regola le istruzioni dell'agente, esegue di nuovo agents-cli eval run e ripete l'operazione finché non viene raggiunta la qualità desiderata.

Esegui il deployment dell'agente

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

Deploy this agent to Cloud Run.

Lo strumento di sviluppo AI attiva la competenza 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
```

L'agente è stato sottoposto a deployment in 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 il Cloud Trace explorer nella Google Cloud console e invia richieste all'agente di cui hai eseguito il deployment. Verranno visualizzati gli intervalli per le chiamate LLM e le esecuzioni degli strumenti.

Per abilitare un'osservabilità più dettagliata, istruisci lo strumento di sviluppo AI:

Set up observability infrastructure for my agent.

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

Riepilogo delle azioni

Questa tabella riassume i prompt e le azioni corrispondenti eseguite dallo strumento di sviluppo AI:

Istruzioni per l'utente	Azioni dello strumento di sviluppo AI
"Crea un agente compressore di uomini delle caverne"	Impalcatura del progetto, scrittura del codice dell'agente, test in locale.
"Scrivi le valutazioni ed eseguile"	Crea evalset, configura LLM-as-judge, esegue `agents-cli eval run`.
"Esegui il deployment in Cloud Run"	Aggiunge la configurazione della destinazione di deployment, 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 dell'interfaccia a riga di comando Agents forniscono il contesto necessario allo strumento di sviluppo AI per utilizzare i pattern ADK appropriati, strutturare le valutazioni e configurare i deployment.

Passaggi successivi

Esplora progetti di agenti più complessi con questi prompt:

Aggiungi strumenti: "Integra uno strumento di Ricerca Google in modo che l'agente possa accedere alle informazioni attuali."
Sistemi multi-agente: "Crea un agente in grado di 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:

ADK: crea, esegui il deployment e orchestra architetture agentiche.
Agent Runtime: crea, esegui il deployment e gestisci gli agenti.
Prezzi: scopri i prezzi di Agent Platform.
Guida rapida all'interfaccia a riga di comando Agents

Crea un agente con ADK e Agents CLI in Agent Platform Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.