Agenti AI di Vibe Coding: gestione del ciclo di vita degli agenti con Agents CLI e ADK 2.0

1. Panoramica

In questo codelab imparerai a utilizzare Agents CLI per gestire l'intero ciclo di vita dello sviluppo locale di un agente AI. Che tu stia eseguendo il wrapping di modelli Gemini esistenti o creando agenti personalizzati da zero con Agent Development Kit (ADK 2.0), Agents CLI fornisce gli strumenti per creare, compilare, analizzare e testare gli agenti in locale.

Obiettivi didattici

  • Come installare e configurare agents-cli e le relative skill.
  • Come creare la struttura di un nuovo progetto di agente.
  • La struttura e i file chiave di un progetto di agente del flusso di lavoro del grafico ADK 2.0.
  • Come eseguire la pulizia automatica del codice e il linting.
  • Come avviare e utilizzare il playground web locale per i test interattivi con ricaricamento automatico.

Cosa serve

  • Python 3.11 o versioni successive
  • Gestore di pacchetti uv
  • Node.js 18+ (se utilizzi le competenze dell'agente di programmazione)
  • Antigravity IDE (installazione e configurazione da Google Antigravity)

Prerequisiti

Questo codelab presuppone che tu abbia familiarità con:

  • Utilizzo di un terminale e della riga di comando.

Non è richiesta alcuna esperienza pregressa con gli agenti AI o ADK 2.0.

2. Configurare l'autenticazione e l'ambiente

Fornisci le credenziali di autenticazione per consentire all'agente di chiamare i modelli Gemini.

Opzione 1: chiave API Gemini (Google AI Studio)

Se utilizzi una chiave API Gemini standard (che puoi ottenere da Google AI Studio), esportala nella sessione del terminale IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Opzione 2: credenziali predefinite dell'applicazione Google Cloud

Se utilizzi Vertex AI su Google Cloud, esegui l'autenticazione con le credenziali predefinite dell'applicazione (ADC) di Google Cloud e imposta il progetto Google Cloud attivo:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Configurare Agents CLI e le skill

Il primo passaggio consiste nell'installare lo strumento agents-cli. Questo strumento si occupa del lavoro più pesante di gestione dei progetti degli agenti.

Con Antigravity installato, esegui il comando di configurazione direttamente nel terminale.

👉 Apri un terminale ed esegui:

uvx google-agents-cli setup

Questo comando installa automaticamente:

  1. Lo strumento Agents CLI a livello globale sul tuo sistema.
  2. Sette competenze di assistenza alla codifica specifiche per il dominio che Antigravity può utilizzare per aiutarti a creare, strutturare, valutare e implementare agenti. Queste skill vengono installate una sola volta a livello globale in ~/.agents/skills/ e vengono rilevate automaticamente da Antigravity.

Nota: le skill vengono installate in ~/.agents/skills/ e rilevate automaticamente da Antigravity. Puoi verificarlo utilizzando il comando /skills o le impostazioni di Antigravity.

Output previsto (troncato):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Crea il progetto dell'agente

In questa sezione creerai una directory di progetto completamente strutturata utilizzando il modello di prototipo.

👉 Prompt Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity esegue automaticamente il comando di scaffolding (agents-cli scaffold create customer-support-agent --prototype --yes) e configura i file di progetto.

5. Esplorare il codice dell'agente

👉 Chiedi ad Antigravity di spiegare il codice generato:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

Nell'IDE Antigravity, i file e gli artefatti del progetto appena creati vengono visualizzati direttamente nel riquadro ausiliario (a sinistra). Puoi visualizzarlo lì o aprirlo dall'Esplora file dell'IDE per esplorare il codice scaffolded.app/agent.py

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Concetti principali

  • Workflow e bordi: in ADK 2.0, le applicazioni dell'agente vengono orchestrate come un grafico utilizzando Workflow. L'elenco edges definisce il flusso di esecuzione, concatenando i nodi da START e consentendo la ramificazione condizionale in base alle route (ad es. il routing a faq_agent su "shipping" o handle_unrelated su "unrelated").
  • LlmAgent: nodi dichiarativi che definiscono attività basate su LLM con istruzioni, modelli e output strutturati specifici (output_schema).
  • Nodi e contesto: funzioni Python decorate con @node (o funzioni standard) che eseguono la logica, accedono allo stato di esecuzione tramite Context e generano oggetti Event per passare dati e segnali di routing lungo il grafico.
  • Modello: "gemini-3.1-flash-lite" viene utilizzato come modello di ragionamento rapido predefinito.
  • Wrapper app: l'oggetto App di primo livello racchiude il flusso di lavoro principale. Strumenti esterni come il playground locale, gli strumenti di valutazione ADK e Agent Runtime rilevano ed eseguono il tuo flusso di lavoro tramite questa interfaccia app standardizzata.

6. Linting automatizzato

Prima di eseguire o testare l'agente, è buona norma assicurarsi che il codice sia pulito e formattato correttamente.

👉 Prompt Antigravity:

Run linting on my agent project to verify its health.

Antigravity esegue agents-cli lint dietro le quinte per eseguire controlli preconfigurati, verificando l'importazione, la sintassi e la coerenza della formattazione nei file.

7. Test interattivi con il Playground

Il playground web locale è il modo più rapido per verificare il comportamento dell'agente. Fornisce un'interfaccia di chat interattiva in cui puoi chattare con l'agente e ispezionare le esecuzioni degli strumenti in tempo reale.

👉 Prompt Antigravity:

Launch the local development playground for my agent.

Antigravity avvierà il server di sviluppo locale (agents-cli playground). Apri l'URL fornito (in genere http://127.0.0.1:8080/dev-ui/?app=app) nel browser web, seleziona la cartella app dal menu a discesa per iniziare a chattare con l'agente.

Inizia a chattare con l'agente nell'interfaccia web. Prova a fare una domanda relativa alla spedizione:

How much is standard shipping?

Nota come il flusso di lavoro classifica e indirizza correttamente la richiesta a faq_agent per rispondere. Prova anche a porre una domanda non correlata per verificare che il flusso di lavoro venga indirizzato a handle_unrelated e che la risposta venga rifiutata correttamente:

What is the weather like?

Testare la ricarica automatica in tempo reale

Puoi vedere come le modifiche in tempo reale apportate al tuo agente vengono riflesse nel Playground.

  1. Modifica l'istruzione faq_agent in app/agent.py chiedendo ad Antigravity: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Invia un nuovo messaggio all'agente nel playground per testare il ricaricamento automatico: 
    How much is standard shipping?
    Il playground si ricarica ed esegue automaticamente il codice aggiornato in tempo reale senza richiedere il riavvio del server. Ora dovresti vedere alcune emoji nella risposta.

8. Esecuzione della riga di comando

Per test rapidi, automazione o scripting, puoi chiedere ad Antigravity di eseguire l'agente direttamente dal terminale.

👉 Prompt Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity eseguirà il comando di query (agents-cli run "How long does standard delivery take?"). In questo modo viene eseguita un'inferenza rapida a un solo turno e viene stampata la risposta finale dell'agente insieme ai dettagli di esecuzione dello strumento.

9. Esegui la pulizia

Per evitare di lasciare risorse indesiderate nel tuo ambiente locale, segui questi passaggi di pulizia:

  1. Arresta i server locali: se il server agents-cli playground è ancora in esecuzione, arrestalo nel terminale premendo Ctrl + C.
  2. Rimuovi file di progetto locali: elimina la directory del progetto dell'agente di scaffolding dalla macchina locale.
rm -rf customer-support-agent

10. Riepilogo e passaggi successivi

Complimenti! Hai gestito correttamente il ciclo di vita dello sviluppo locale end-to-end di un agente AI utilizzando Agents CLI e ADK 2.0.

Che cosa hai imparato

  • Configura i tuoi strumenti: hai installato la Agents CLI e configurato le skill del workflow specifiche per il dominio per Antigravity.
  • Progetto strutturato: è stato creato un progetto customer-support-agent completamente strutturato utilizzando modelli standardizzati.
  • Struttura ADK 2.0 analizzata: sono stati esplorati flussi di lavoro del grafico, agenti LLM, nodi, archi e routing condizionale.
  • Managed Local Health: esegue controlli automatici della qualità del codice utilizzando agents-cli lint.
  • Comportamento verificato: l'agente è stato testato in modo interattivo con il ricaricamento a caldo in tempo reale tramite il playground e sono stati eseguiti test rapidi sulla riga di comando.

Passaggi successivi

Ora che hai acquisito familiarità con il ciclo di sviluppo locale, ecco come puoi espandere e rendere operativo il tuo agente:

  • Valutazione: assegna un punteggio al tuo agente rispetto a un evalset utilizzando agents-cli eval run per misurare l'accuratezza e trovare le regressioni.
  • Enterprise Cloud Scale: Deployment e Osservabilità: impacchetta ed esegui il deployment dell'agente in ambienti di produzione come Agent Runtime o Cloud Run utilizzando agents-cli deploy. Configura la telemetria di produzione per trasmettere in streaming i log e le tracce di esecuzione a Cloud Trace e BigQuery.

Risorse aggiuntive