Workshop per principianti per Antigravity CLI e ADK (crea il tuo primo compagno AI)

1. Obiettivi didattici

• Come installare e registrare una skill per l'Antigravity CLI per attivare le funzionalità di programmazione in un framework specifico (ADK).
• Come utilizzare l'interfaccia a riga di comando Antigravity per generare una configurazione completa dell'agente ADK.
• Come migliorare la personalità di un agente perfezionando le sue istruzioni.
• Come aggiungere "grounding" al tuo agente fornendogli un google_search per rispondere a domande su eventi recenti.

L'app AI Companion

In questo codelab, creerai un compagno AI visivo e interattivo. Si tratta di qualcosa di più di un semplice chatbot standard di testo in testo. Immagina un personaggio che vive in una pagina web. Digiti un messaggio e, invece di vedere solo il testo, il personaggio ti guarda e risponde ad alta voce, muovendo la bocca in sincronia con le parole.

Inizierai con un'applicazione web predefinita, una "marionetta" digitale con un volto, ma senza una mente propria. Può solo ripetere ciò che digiti. La tua missione è costruire il suo cervello e la sua personalità da zero.

Durante questo workshop, aggiungerai progressivamente livelli di intelligenza e personalizzazione, trasformando questa semplice marionetta in un compagno unico e capace. Sarai:

• Dotandolo di un'intelligenza di base utilizzando l'ADK(Python) per comprendere e generare il linguaggio.
• Creando la sua personalità unica scrivendo le istruzioni di base che ne definiscono il carattere.
• Concedendogli dei superpoteri, fornendogli strumenti per accedere a informazioni in tempo reale da internet.
• Progettare il suo aspetto personalizzato utilizzando l'AI per generare un avatar unico.

Alla fine, avrai un compagno AI completamente funzionale e personalizzato, creato da te.

Architettura

La nostra applicazione segue un pattern semplice ma potente. Abbiamo un backend Python che gestisce un'API. Questo backend conterrà il nostro agente ADK, che funge da "cervello". Qualsiasi interfaccia utente (come il frontend JavaScript dell'app scheletro, un'app mobile o anche uno strumento a riga di comando) può quindi interagire con questo cervello tramite l'API.

Inoltre, utilizzeremo le funzionalità di generazione di immagini integrate nella CLI Antigravity, chiedendole di generare un aspetto unico per il nostro compagno AI.

Ottenere una chiave API Gemini

Prima di procedere, devi disporre di una chiave API Gemini per autenticare le tue richieste con Google AI Studio.

1. Vai a Google AI Studio.
2. Esegui l'accesso con il tuo Account Google.
3. Fai clic sul pulsante Ottieni chiave API nel menu in alto a sinistra.
4. Fai clic su Crea chiave API (puoi crearla in un progetto Google Cloud nuovo o esistente).
5. Copia la chiave generata. Mantieni questa chiave privata e protetta.

Crea e configura il progetto

Per accedere a Cloud Shell, avrai comunque bisogno di un progetto Google Cloud. Se non ne hai uno:

1. Vai alla console Google Cloud.
2. Nella barra di navigazione in alto della console, fai clic su Seleziona un progetto, quindi su Nuovo progetto nell'angolo in alto a destra.
3. Assegna un nome al progetto e fai clic su Crea. (Nessuna organizzazione è obbligatoria).
4. Una volta creato il progetto, selezionalo dal menu a discesa dei progetti nella parte superiore della console.

Il tuo progetto è ora configurato per l'accesso a Cloud Shell.

2. Prima di iniziare

👉 Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud (l'icona a forma di terminale nella parte superiore del riquadro di Cloud Shell),

👉💻 Installa l'interfaccia a riga di comando Antigravity nel terminale Cloud Shell:

curl -fsSL https://antigravity.google/cli/install.sh | bash

👉💻 Per utilizzare la CLI "agy" a livello globale, aggiungila al profilo della shell:

echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

👉💻 Esporta la chiave API Gemini e salvala localmente nel terminale Cloud Shell:

# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>

👉💻 Salva per un utilizzo futuro:

echo $GEMINI_API_KEY > ~/gemini_key.txt

👉 Trova l'ID progetto Google Cloud:

• Apri la console Google Cloud: https://console.cloud.google.com
• Seleziona il progetto che vuoi utilizzare per questo workshop dal menu a discesa dei progetti nella parte superiore della pagina.
• Il tuo ID progetto viene visualizzato nella scheda Informazioni sul progetto della dashboard

👉💻 Nel terminale, clona il progetto di bootstrap da GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Esegui lo script di inizializzazione, che ti chiederà di inserire l'ID progetto Google Cloud. e inserisci l'ID progetto Google Cloud che hai trovato nell'ultimo passaggio quando richiesto dallo script init.sh.

cd ~/companion-python
./init.sh

👉💻 Imposta l'ID progetto necessario:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 Esegui il comando seguente per abilitare le API Google Cloud necessarie (per l'anteprima/l'hosting di Cloud Shell è necessario solo Compute Engine):

gcloud services enable compute.googleapis.com

Installa la skill per sviluppatori ADK

Per consentire alla CLI Antigravity (agy) di comprendere e scrivere codice utilizzando l'Agent Development Kit (ADK) Python, dobbiamo installare la competenza per sviluppatori ADK Python che abbiamo creato nello spazio di lavoro del progetto.

👉💻 Crea la directory delle competenze dell'agente locale e copia il file delle competenze:

mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md

In questo modo la skill viene registrata localmente all'interno del progetto. Quando avvii agy, questa skill viene rilevata e caricata automaticamente, consentendole di scrivere, modificare e orchestrare gli agenti ADK.

👉💻 Avvia l'interfaccia a riga di comando Antigravity nel terminale Cloud Shell:

cd ~/companion-python
agy

[!IMPORTANT] Accedere ad Antigravity CLI

Quando esegui per la prima volta il comando agy, ti viene chiesto di accedere:

Welcome to the Antigravity CLI. You are currently not signed in.

 Select login method:
 > 1. Google OAuth
   2. Use a Google Cloud project

1. Scegli l'opzione 1. Google OAuth premendo Enter.
2. Segui il prompt per aprire il browser, autenticarti con il tuo Account Google e seguire le istruzioni per accedere.

Ora ti trovi nel prompt interattivo di Antigravity CLI.

Avvia il server web tramite l'interfaccia a riga di comando di Antigravity

Poiché la CLI Antigravity può eseguire comandi per te, chiediamole di eseguire il server in background nella sessione.

👉✨ Nel prompt di Antigravity CLI, incolla la seguente richiesta:

Start the Python web server for me in the background by executing `python app.py`. Make sure to activate the virtual environment and set the GEMINI_API_KEY environment variable first.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

La CLI eseguirà il comando e confermerà che il server è in esecuzione. Rimarrà aperta la sessione CLI interattiva.

👀 Per visualizzare l'app, fai clic sull'icona Anteprima web nella barra degli strumenti di Cloud Shell. Seleziona Cambia porta, impostala su 5000 e fai clic su Cambia e visualizza anteprima. Verrà visualizzata un'anteprima del tuo sito web.

L'applicazione iniziale è solo un burattino. Non ha ancora intelligenza. Qualunque messaggio tu invii, lo ripeterà. Ciò conferma che il nostro server web di base funziona prima di aggiungere l'AI. Ricordati di accendere lo speaker.

3. Crea un personaggio con l'interfaccia a riga di comando Antigravity

Ora creiamo il cuore dell'intelligenza del nostro compagno. Poiché la CLI Antigravity è già in esecuzione nel terminale e gestisce il server web in background, puoi continuare direttamente nella sessione interattiva.

Utilizziamo la CLI per creare un agente. Un agente è molto più di una semplice chiamata a un modello linguistico: è il "cervello" o il controller centrale della nostra AI. Consideralo un'entità distinta in grado di ragionare, seguire un insieme specifico di istruzioni (la sua personalità) e, infine, utilizzare strumenti per svolgere attività. Nel nostro progetto, questo agente è il componente che riceverà i messaggi degli utenti, incarnerà la personalità unica del nostro compagno e formulerà risposte intelligenti e in linea con il personaggio.

👉✨ Nel prompt della CLI Antigravity, incolla quanto segue per generare il codice dell'agente:

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-3.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

La CLI genererà il codice Python.

👉 Fai clic sul pulsante "Apri editor" (ha l'aspetto di una cartella aperta con una matita). Si aprirà l'editor di codice di Cloud Shell nella finestra. Vedrai un esploratore di file sul lato sinistro.

👉 Utilizza l'editor e vai a character.py nella cartella companion-python. Controlla la riga model= e modificala manualmente impostando il valore gemini-3.5-flash se è stato scelto un modello diverso. In questo modo, garantiremo la coerenza per il resto del workshop.

Nota: i modelli linguistici di grandi dimensioni possono essere non deterministici e questo è un concetto chiave nello sviluppo assistito dall'AI. "Non deterministico" significa che, anche con lo stesso prompt, il modello potrebbe produrre risultati leggermente diversi ogni volta. Utilizza la sua creatività per generare il codice, quindi potresti notare variazioni nei commenti, nella spaziatura o persino nella denominazione delle variabili temporanee. Tuttavia, la logica e la struttura di base devono essere funzionalmente identiche a quelle richieste.

Per questo motivo, la programmazione con un'AI raramente è un comando singolo. In un progetto reale, gli sviluppatori lo trattano come una conversazione. Inizi con una richiesta generica (come abbiamo appena fatto), esamini l'output e poi lo perfezioni con prompt di follow-up come:

• "Ottimo, ora aggiungi commenti che spieghino ogni riga."
• "Puoi eseguire il refactoring in una funzione separata?"
• "Aggiungi la gestione degli errori per la chiamata API."

Questo processo iterativo e conversazionale ti consente di collaborare con l'AI, guidandola finché il codice non soddisfa esattamente le tue esigenze. Per questo workshop, utilizzeremo prompt specifici e diretti, ma ricorda che nei tuoi progetti la conversazione è il vero punto di forza. Se la struttura del codice generata dalla CLI è la stessa, puoi procedere.

Se il codice generato non funziona, puoi sostituire il seguente codice con il tuo character.py.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-3.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Testare il codice generato

Per assicurarti che il server carichi il modulo character.py appena generato, chiedi alla CLI Antigravity di riavviare il server web.

👉✨ Nel prompt di Antigravity CLI, incolla la seguente richiesta:

Please restart the Python web server for me.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

👀 Vai alla scheda di anteprima web.

👉 Tipo:

Hello, how are you?

e premi Invia. L'agente ora dovrebbe rispondere con un saluto amichevole anziché ripetere le tue parole. Ciò conferma che il nostro agente ora è basato su Gemini.

4. Migliorare la buyer persona dell'agente

Un'istruzione semplice è buona, ma una persona dettagliata crea un personaggio molto più coinvolgente e memorabile. In questo passaggio, progetterai la personalità del tuo compagno e poi darai istruzioni alla CLI Antigravity per modificare direttamente il codice dell'agente in modo che adotti questa nuova persona.

Fare brainstorming sulla personalità del tuo compagno

Innanzitutto, prenditi un momento per pensare al compagno AI che vuoi creare. Questa è la tua occasione per dare sfogo alla creatività. Ecco alcune domande per iniziare:

• Qual è il suo nome? (ad es. Sparky, Codex, Captain AI, Professor Know-it-all)
• Qual è la sua personalità principale? (ad es. amichevole e curioso, arguto e sarcastico, formale e professionale, un pirata allegro?)
• Qual è il suo ruolo o la sua competenza? (ad es. un assistente per uso generico, un esperto di programmazione, un partner di scrittura creativa, un personal trainer?)
• Quali sono alcune regole che deve sempre seguire? (ad es. "Inizia sempre con un saluto", "Non rivelare mai di essere un'IA", "Usa emoji nelle risposte").

Esempio di persona:

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

Elabora il prompt per l'interfaccia a riga di comando Antigravity

Ora che hai progettato la personalità del tuo compagno di avventure sulla carta, è il momento di darle vita all'interno del codice. La parte più importante di un agente ADK è il parametro instruction. Consideralo come la programmazione principale dell'agente, la sua "direttiva principale" o la costituzione che deve sempre seguire.

Questa istruzione è la chiave per controllare il comportamento dell'agente. Non si tratta solo di un suggerimento, ma del contesto fondamentale a cui l'AI fa riferimento prima di ogni interazione con l'utente. Determina la personalità dell'agente, il suo tono di voce, le regole che deve rispettare e il modo in cui deve presentarsi. Un'istruzione ben realizzata è la differenza tra un chatbot generico e un personaggio credibile e coerente. Pertanto, il prompt che stiamo per creare è fondamentale, in quanto inietterà direttamente questa personalità nel cervello del nostro agente.

👉✨ Nell'interfaccia a riga di comando di Antigravity, utilizza questo modello. Sostituisci il testo tra parentesi con la descrizione della tua persona. SOSTITUISCI [YOUR PERSONA DESCRIPTION HERE] con la tua persona preferita

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

Testare la nuova persona

Antigravity CLI genererà il codice aggiornato per character.py. Per assicurarti che il server rilevi la nuova configurazione dell'agente, chiedi alla CLI di Antigravity di riavviarlo.

👉✨ Nel prompt di Antigravity CLI, incolla la seguente richiesta:

Please restart the Python web server for me.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

👀 Nell'anteprima web, parla con il tuo compagno. Chiedi a how are you?. La risposta dovrebbe ora corrispondere perfettamente al personaggio unico che hai progettato.

Aggiungi la gestione dei nuovi tentativi per i limiti di frequenza dell'API (facoltativo, ma consigliato)

Durante i workshop o i periodi di utilizzo simultaneo elevato, potresti riscontrare errori di limite di frequenza API (HTTP 429: Resource Exhausted). Per garantire che il tuo companion rimanga reattivo e gestisca automaticamente le eccezioni del limite di frequenza, possiamo configurare le opzioni di ripetizione integrate direttamente nelle opzioni del client Google GenAI SDK.

👉✨ Nel prompt di Antigravity CLI, incolla la seguente richiesta:

Help me configure the LlmAgent in character.py to automatically retry API calls when hitting rate limits. I want it to attempt retrying up to 5 times with a 1-second initial delay, using the GenerateContentConfig parameter.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

La CLI modificherà il file character.py per gestire automaticamente i limiti di frequenza utilizzando i criteri di ripetizione a livello di client. Ricordati di chiedere alla CLI di riavviare il server web dopo aver aggiornato il file:

Please restart the Python web server for me.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

5. Aggiungere la base per gli eventi recenti

Il nostro agente è ora pieno di personalità, ma ha una limitazione significativa: le sue conoscenze sono congelate nel tempo, in base ai dati su cui è stato addestrato. Non può fornirti informazioni sulle notizie di ieri o sulle scoperte recenti. Per superare questo problema, forniamo agli agenti strumenti.

Pensa agli strumenti come a superpoteri o abilità speciali che concedi al tuo agente. Di per sé, l'agente può solo parlare. Con uno strumento di ricerca, acquisisce la capacità di navigare su internet. Con uno strumento di calendario, potrebbe controllare la tua agenda. Tecnicamente, uno strumento è una funzione o un'API specifica che l'agente può scegliere in modo intelligente di utilizzare quando si rende conto che le proprie conoscenze non sono sufficienti per rispondere alla richiesta di un utente.

Nei sistemi avanzati, gli strumenti possono essere forniti da sistemi esterni come i server MCP (Model Context Protocol). Per questo passaggio, però, non abbiamo bisogno di un server separato. L'ADK include un potente strumento google_search predefinito che possiamo aggiungere facilmente alle funzionalità del nostro agente.

Diamo al nostro compagno la potenza della Ricerca Google.

👉 Nell'editor di Cloud Shell, apri character.py in companion-python e modificalo nel seguente modo:

• Importa google_search da google.adk.tools.
• Aggiungi un elenco tools al costruttore LlmAgent.
• Aggiorna instruction per indicare esplicitamente al tuo compagno quando utilizzare il nuovo strumento.

# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.genai import types
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-3.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        generate_content_config=types.GenerateContentConfig(
          http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                attempts=5,
                initial_delay=1.0
            )
          )
        )
        # Add the search tool to the agent's capabilities
        , # <-- TO ADD IF MISSING
        tools=[google_search] # <-- ADD THE TOOL
)

Testare l'agente con informazioni reali

Per assicurarti che il server web carichi il nuovo codice con lo strumento google_search, chiedi alla CLI Antigravity di riavviarlo.

👉✨ Nel prompt di Antigravity CLI, incolla la seguente richiesta:

Please restart the Python web server for me.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

👉 Nell'anteprima web, poni una domanda che richieda conoscenze aggiornate, ad esempio:

Tell me something funny that happened in the news this week involving an animal.

👉 Invece di dire che non lo sa, l'agente utilizzerà ora il suo strumento di ricerca per trovare informazioni aggiornate e fornire un riepilogo utile e basato su dati concreti con la sua voce unica.

6. Personalizzare l'aspetto della modalità Complementare

Ora che il nostro compagno ha un cervello, diamogli un volto unico. Poiché l'interfaccia a riga di comando Antigravity è dotata di funzionalità di generazione di immagini predefinite, puoi semplicemente chiedere all'interfaccia a riga di comando Antigravity di generare direttamente gli avatar per te.

Questa è la tua occasione per progettare l'aspetto unico del tuo compagno. Pensa al suo stile, alla sua espressione e a qualsiasi altro dettaglio che si adatti alla persona che hai creato in precedenza.

👉✨ Nel prompt della CLI Antigravity, incolla la seguente richiesta (puoi modificare il prompt con la descrizione del tuo personaggio creativo):

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

Premi Invio per approvare la richiesta dell'agente di scrivere il file.

Lo strumento genererà il set di immagini con la bocca aperta e chiusa e le salverà automaticamente nella directory static/images del progetto.

Ora puoi interagire con il tuo compagno personalizzato visivamente.

Complimenti!

Hai creato un sofisticato compagno AI. Hai iniziato con un'app di base, hai utilizzato la CLI Antigravity per creare uno scheletro di agente, gli hai dato una personalità ricca e lo hai dotato di strumenti per accedere a informazioni in tempo reale e persino generare il proprio avatar. Ora puoi creare agenti AI ancora più complessi e capaci.

👉💻 Per concludere e chiudere la sessione, torna al terminale ed esci da Antigravity CLI digitando /exit nel prompt agy:

/exit