Crea il tuo primo AI Companion: un workshop per principianti

1. Obiettivi didattici

  • Come utilizzare la CLI Gemini 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.
  • Come generare un avatar personalizzato per il tuo companion utilizzando un server MCP con Imagen.

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 su 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 efficace. 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, esploreremo un concetto più avanzato avviando un server MCP (Model Context Protocol) locale. Questo server funge da ponte per strumenti specializzati per la generazione di immagini. Utilizzeremo quindi la CLI Gemini per comandare questo server MCP, istruendolo a generare un aspetto unico per il nostro compagno AI.

Richiedi i tuoi crediti

Segui attentamente queste istruzioni per eseguire il provisioning delle risorse del workshop.

Prima di iniziare

AVVISO.

  • Utilizza un account Gmail personale. Gli account aziendali o gestiti dalla scuola NON funzionano.
  • Utilizza Google Chrome in modalità di navigazione in incognito per evitare conflitti tra account.

Apri una nuova finestra in incognito, incolla il link dell'evento e accedi con il tuo account Gmail personale.

👉 Fai clic di seguito per copiare il link dell'evento speciale:

goo.gle/devfest-boston-ai

Accetta i Termini di servizio della piattaforma Google Cloud. Una volta applicato, vedrai il messaggio che indica che il credito è stato applicato.

Crea e configura il progetto

Ora che i crediti sono stati applicati, configura l'ambiente del progetto.

👉 Vai alla console Google Cloud. Fai clic di seguito per copiare il link:

https://console.cloud.google.com/

👉 Nella barra di navigazione in alto della console, fai clic su Seleziona un progetto, poi su Nuovo progetto nell'angolo in alto a destra.

👉 Assegna un nome al progetto e fai clic su Crea. (Nessuna organizzazione)

👉 Una volta creato, selezionalo. Nel menu a sinistra, vai a Fatturazione.

👉 Fai clic su Collega un account di fatturazione, seleziona Account di fatturazione di prova di Google Cloud Platform dal menu a discesa e fai clic su Imposta account. Se non vedi il menu a discesa, attendi un minuto che il credito venga applicato e ricarica la pagina.

I tuoi crediti sono attivi e il tuo progetto è configurato.

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 Cloud Shell),

👉 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.
  • L'ID progetto viene visualizzato nella scheda informativa del progetto nella 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:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

Avvia l'app

Avviamo il progetto iniziale. Questa versione iniziale è un semplice server "echo": non ha intelligenza e ripete solo ciò che gli invii.

👉💻 Nel terminale di Cloud Shell, crea e attiva un ambiente virtuale Python e installa le librerie richieste dal file requirements.txt.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 Avvia il server web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 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.

A volte, in un nuovo ambiente Cloud Shell, il browser potrebbe aver bisogno di un piccolo aiuto per caricare tutti gli asset dell'applicazione (come immagini e librerie audio) per la prima volta. Eseguiamo un rapido passaggio per "preparare il browser" e assicurarci che tutto venga caricato correttamente.

  1. Tieni aperta la scheda di anteprima web per la tua applicazione.
  2. Apri una nuova scheda del browser.
  3. In questa nuova scheda, incolla l'URL della tua applicazione, ma aggiungi il seguente percorso alla fine: /static/images/char-mouth-open.png.Ad esempio, l'URL sarà simile a questo: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Premi Invio. Dovresti vedere solo l'immagine del personaggio con la bocca aperta. Questo passaggio consente di assicurarsi che il browser abbia recuperato correttamente i file dall'istanza Cloud Shell.

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

👉 Per arrestare il server, premi CTRL+C.

3. Crea un personaggio con la CLI Gemini

Ora creiamo il cuore dell'intelligenza del nostro compagno. Per questo, lavoreremo con due terminali contemporaneamente (questo è il terminale Google Cloud Shell):

  • Terminale 1: verrà utilizzato per eseguire il nostro server web Python, consentendoci di testare le modifiche in tempo reale.
  • Terminale 2: questa sarà la nostra "stazione di creazione", dove interagiremo con l'interfaccia a riga di comando di Gemini.

Utilizzeremo l'interfaccia a riga di comando di Gemini, una potente interfaccia a riga di comando che funge da assistente alla programmazione AI. Ci consente di descrivere il codice che vogliamo in inglese semplice e genera la struttura per noi, accelerando notevolmente lo sviluppo.

👉💻 Nel terminale Gemini CLI esci dalla sessione Gemini CLI corrente facendo clic su ctrl+c due volte, poiché la nostra directory del progetto si trova in ~/companion-python e riavvia Gemini CLI.

cd ~/companion-python
clear
gemini --yolo

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 che può 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 dell'interfaccia a riga di comando di Gemini, incolla il seguente codice 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-2.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".

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. Sul lato sinistro vedrai un esploratore di file.

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

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 dei 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 è esattamente quello che ti serve. Per questo workshop, utilizzeremo prompt specifici e diretti, ma ricorda che nei tuoi progetti la conversazione è il vero punto di forza. Finché la struttura del codice generata dalla CLI è la stessa, non avrai problemi.

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-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Testa il codice generato:

👉💻 Vai al primo terminale (quello per eseguire il codice Python) e avvia il server web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Vai alla scheda Anteprima web.

👉 Digita Hello, how are you? e premi Invia. L'agente ora dovrebbe rispondere con un saluto cordiale anziché ripetere le tue parole. Ciò conferma che il nostro agente ora è basato su Gemini.

👉 Al termine del test, arresta il server con CTRL+C. Per uscire dall'interfaccia a riga di comando di Gemini nel terminale in cui è in esecuzione , premi due volte CTRL+C.

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 chiederai alla CLI Gemini di modificare direttamente il codice dell'agente per adottare questa nuova persona.

Fare brainstorming sulla personalità del tuo compagno

Per prima cosa, 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 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'AI", "Usa emoji nelle tue 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.

Elaborare il prompt per l'interfaccia a riga di comando di Gemini

Ora che hai progettato la personalità del tuo compagno sulla carta, è il momento di darle vita all'interno del codice. La parte più importante di un agente ADK è il parametro instruction. Consideralo il programma 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 è solo un suggerimento, ma il contesto di base a cui l'AI fa riferimento prima di ogni interazione con l'utente. Definisce 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 fa 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 Gemini, 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]

Testare la nuova persona

L'interfaccia a riga di comando di Gemini genererà il codice aggiornato per character.py.

👉💻 Riavvia il server web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 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.

👉 Al termine, arresta il server con CTRL+C.

5. Aggiungere la base per gli eventi recenti

Il nostro agente è ora pieno di personalità, ma ha un limite significativo: 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 specifica o un'API 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) che abbiamo menzionato nella nostra architettura; lo faremo in un secondo momento per la generazione di immagini. 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.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.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.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

Testare l'agente con informazioni reali

👉💻 Avvia di nuovo il server.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 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.

Per arrestare il server, premi CTRL+C.

6. Personalizzare l'aspetto del tuo compagno (facoltativo)

Ora che il nostro compagno ha un cervello, diamogli un volto unico. Utilizzeremo un server MCP (Model Context Protocol) locale che consente alla CLI Gemini di generare immagini. Questo server utilizzerà i modelli di AI generativa disponibili tramite Google AI Studio.

Che cos'è esattamente un server MCP?

Il Model Context Protocol (MCP) è uno standard aperto progettato per risolvere un problema comune e complesso: come fanno i modelli di AI a comunicare con strumenti e origini dati esterni? Invece di scrivere codice personalizzato e una tantum per ogni integrazione, MCP fornisce un "linguaggio" universale per questa comunicazione.

Consideralo come un adattatore universale o una porta USB per l'AI. Qualsiasi strumento che "parla" MCP può connettersi a qualsiasi applicazione AI che "parla" anche MCP.

Nel nostro workshop, il server nano-banana-mcp che stiamo per eseguire funge da ponte cruciale. La CLI Gemini invierà una richiesta standardizzata al nostro server MCP locale. Il server traduce quindi la richiesta in una chiamata specifica ai modelli di AI generativa per creare l'immagine. In questo modo, possiamo integrare in modo semplice potenti funzionalità di generazione di immagini direttamente nel nostro flusso di lavoro della riga di comando.

Configurare il server di generazione di immagini locale

Ora cloneremo ed eseguiremo un server MCP predefinito che gestisce le richieste di generazione di immagini.

👉💻 In un primo terminale Cloud Shell (quello in cui esegui Python), clona il repository del server.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

Diamo una rapida occhiata al server, al file mcp_server.py all'interno della cartella nano-banana-mcp. Questo server è progettato per esporre due "strumenti" specifici che l'interfaccia a riga di comando di Gemini può utilizzare. Considerale come due competenze distinte che il nostro servizio di generazione di immagini ha appreso.

  1. generate_image: si tratta di uno strumento per uso generico. Prende un singolo prompt di testo e genera un'immagine basata su di esso. È semplice e utile per molte attività.
  2. generate_lip_sync_images: si tratta di uno strumento altamente specializzato progettato perfettamente per le nostre esigenze. Quando fornisci un prompt di base che descrive un personaggio, esegue un processo intelligente in due passaggi:
    • Innanzitutto, aggiunge "con la bocca aperta" al prompt e genera la prima immagine.
    • In secondo luogo, prende l'immagine appena creata e la invia di nuovo al modello con una nuova istruzione: "chiudi la bocca".

La capacità di Gemini 2.5 Flash Image (Nano Banana) di alterare o modificare un'immagine esistente in base a un comando in linguaggio naturale è incredibilmente potente. Il modello ridisegna solo le parti necessarie dell'immagine, mantenendo tutto il resto perfettamente intatto. In questo modo, le due immagini sono assolutamente coerenti in termini di stile, illuminazione e design del personaggio e differiscono solo per la posizione della bocca, che è esattamente ciò di cui abbiamo bisogno per un effetto di sincronizzazione labiale convincente.

Nei passaggi successivi, chiederemo alla Gemini CLI di utilizzare lo strumento specializzato generate_lip_sync_images per creare l'avatar unico del nostro compagno.

👉💻 Attiva l'ambiente virtuale del progetto e installa i requisiti specifici del server.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 Ora esegui il server MCP in background in modo che possa rimanere in attesa delle richieste dell'interfaccia a riga di comando di Gemini.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

Questo comando avvierà il server e il simbolo & lo manterrà in esecuzione in background.

Successivamente, dobbiamo configurare la CLI Gemini per inviare richieste di generazione di immagini al nostro server locale appena avviato. A questo scopo, modificheremo il file di configurazione centrale della CLI.

Quindi, che cos'è questo file settings.json?

Il file ~/.gemini/settings.json è il file di configurazione centrale per la CLI Gemini. È qui che la CLI memorizza le impostazioni, le preferenze e la directory di tutti gli strumenti esterni che sa utilizzare.

All'interno di questo file, c'è una sezione speciale chiamata mcpServers. Considera questa sezione come una rubrica o un elenco di servizi specifico per gli strumenti che utilizzano il protocollo di contesto del modello. Ogni voce di questa directory ha un nickname (ad es. "nano-banana") e le istruzioni su come connettersi (nel nostro caso, un URL).

Il comando che stiamo per eseguire aggiungerà a livello di programmazione una nuova voce a questa directory dei servizi. L'interfaccia a riga di comando di Gemini:

"Ehi, da ora in poi, conoscerai uno strumento chiamato nano-banana. Ogni volta che un utente ti chiede di utilizzarlo, devi connetterti al server MCP in esecuzione all'URL http://localhost:8000/sse."

Modificando questa configurazione, rendiamo l'interfaccia a riga di comando di Gemini più potente. Gli stiamo insegnando dinamicamente una nuova abilità, ovvero come comunicare con il nostro server locale di generazione di immagini, senza mai toccare il codice principale della CLI. Questo design estensibile consente all'interfaccia a riga di comando di Gemini di orchestrare attività complesse richiamando un intero ecosistema di strumenti specializzati.

👉💻 Nel primo terminale, esegui questo comando. Verrà creato o aggiornato il file di impostazioni di Gemini, indicando dove trovare il servizio "nano-banana".

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

Dovresti vedere i contenuti del file stampati, ora inclusa la configurazione nano-banana.

Generare gli avatar dei personaggi

Con il server in esecuzione e la CLI configurata, ora puoi generare le immagini. Ma prima di chiedere all'AI di essere creativa, facciamo ciò che fa ogni buon sviluppatore: verifichiamo la configurazione. Dobbiamo verificare che la CLI Gemini possa comunicare correttamente con il nostro server MCP locale.

👉💻 Nel terminale della CLI Gemini (quello che non esegue un server), avviamo la shell interattiva di Gemini. Se è già in esecuzione, esci con CTRL+C due volte e riavviala per assicurarti che carichi le nuove impostazioni.

clear
gemini --yolo

Ora ti trovi nell'ambiente interattivo della CLI Gemini. Da qui, puoi chattare con l'AI, ma puoi anche dare comandi diretti alla CLI stessa.

👉✨ Per verificare se il nostro server MCP è connesso, utilizzeremo un "comando slash" speciale. Non si tratta di un prompt per l'AI, ma di un'istruzione per l'applicazione CLI. Digita quanto segue e premi Invio:

/mcp list

Questo comando indica all'interfaccia a riga di comando di Gemini: "Controlla la configurazione, trova tutti i server MCP che conosci, prova a connetterti a ciascuno e segnalane lo stato".

👀 Dovresti vedere l'output seguente, che conferma che tutto funziona perfettamente:

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

Analizziamo il significato di questa risposta riuscita:

  • 🟢 nano-banana: Il cerchio verde è il nostro segnale di successo. Conferma che la CLI è riuscita a raggiungere il server nano-banana all'URL specificato in settings.json.
  • - Ready: questo stato conferma che la connessione è stabile.
  • (2 tools): questa è la parte più importante. Significa che la CLI non solo si è connessa, ma ha anche chiesto al nostro server MCP: "Cosa puoi fare?". Il nostro server ha risposto pubblicizzando i due strumenti che abbiamo visto nel suo codice: generate_image e generate_lip_sync_images.

Ciò conferma che l'intera catena di comunicazione è stabilita. La CLI ora conosce il nostro servizio di generazione di immagini locale ed è pronta per essere utilizzata su nostro comando.

Ora passiamo alla parte più creativa del workshop. Utilizzeremo un prompt singolo e potente per comandare all'interfaccia a riga di comando di Gemini di utilizzare lo strumento speciale generate_lip_sync_images sul nostro server MCP in esecuzione.

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

👉✨ Ecco un esempio di prompt ben strutturato. Puoi utilizzarla come punto di partenza o sostituire completamente la parte descrittiva con la tua visione.

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.

Lo strumento genererà una serie di immagini (per bocca aperta, chiusa e così via) e le salverà. Verranno visualizzati i percorsi in cui sono stati salvati i file.

Riavvia l'applicazione

Una volta creati gli avatar personalizzati, puoi riavviare il server web per vedere il nuovo aspetto del tuo personaggio.

👉💻 Avvia il server un'ultima volta nel primo terminale

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Per garantire che le nuove immagini vengano caricate correttamente, caricheremo in anticipo l'immagine char-mouth-open.png.

  1. Tieni aperta la scheda di anteprima web per la tua applicazione.
  2. Apri una nuova scheda del browser.
  3. In questa nuova scheda, incolla l'URL della tua applicazione, ma aggiungi il seguente percorso alla fine: /static/images/char-mouth-open.png.Ad esempio, l'URL sarà simile a questo: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Premi Invio. Dovresti vedere solo l'immagine del personaggio con la bocca aperta. Questo passaggio consente di assicurarsi che il browser abbia recuperato correttamente i file dall'istanza Cloud Shell.

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 Gemini 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.