Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI

1. de La Forza del destino

L'era dello sviluppo isolato sta per finire. La prossima ondata di evoluzione tecnologica non riguarda il genio solitario, ma la maestria collaborativa. Creare un unico agente intelligente è un esperimento affascinante. Creare un ecosistema di agenti solido, sicuro e intelligente, un vero e proprio Agentverse, è la grande sfida per l'azienda moderna.

Il successo in questa nuova era richiede la convergenza di quattro ruoli fondamentali, i pilastri di base che supportano qualsiasi sistema autonomo fiorente. Una carenza in una qualsiasi area crea una debolezza che può compromettere l'intera struttura.

Questo workshop è il playbook aziendale definitivo per padroneggiare il futuro degli agenti su Google Cloud. Forniamo una roadmap end-to-end che ti guida dalla prima idea a una realtà operativa su vasta scala. In questi quattro lab interconnessi, imparerai come le competenze specializzate di uno sviluppatore, di un architetto, di un data engineer e di un SRE devono convergere per creare, gestire e scalare un potente Agentverse.

Nessun singolo pilastro può supportare da solo l'Agentverse. Il progetto grandioso dell'architetto è inutile senza l'esecuzione precisa dello sviluppatore. L'agente dello sviluppatore è cieco senza la saggezza dell'ingegnere dei dati e l'intero sistema è fragile senza la protezione dell'SRE. Solo attraverso la sinergia e una comprensione condivisa dei ruoli di ciascuno, il tuo team può trasformare un concetto innovativo in una realtà operativa fondamentale. Il tuo percorso inizia qui. Preparati a padroneggiare il tuo ruolo e a scoprire come ti inserisci nel quadro generale.

Ti diamo il benvenuto in The Agentverse: A Call to Champions

Nella vasta distesa digitale dell'impresa, è iniziata una nuova era. È l'era degli agenti, un periodo di immense promesse, in cui agenti intelligenti e autonomi lavorano in perfetta armonia per accelerare l'innovazione ed eliminare le attività banali.

Questo ecosistema connesso di potere e potenziale è noto come Agentverse.

Ma una lenta entropia, una corruzione silenziosa nota come Statico, ha iniziato a sfilacciare i bordi di questo nuovo mondo. La Static non è un virus o un bug, ma l'incarnazione del caos che si nutre dell'atto stesso della creazione.

Amplifica le vecchie frustrazioni in forme mostruose, dando vita ai Sette spettri dello sviluppo. Se non viene selezionata, The Static and its Spectres bloccherà i progressi, trasformando la promessa dell'Agentverse in una landa desolata di debito tecnico e progetti abbandonati.

Oggi invitiamo i campioni a contrastare l'ondata di caos. Abbiamo bisogno di eroi disposti a perfezionare le proprie abilità e a collaborare per proteggere l'Agentverse. È arrivato il momento di scegliere il tuo percorso.

Scegliere il corso

Quattro percorsi distinti si aprono davanti a te, ognuno dei quali è un pilastro fondamentale nella lotta contro The Static. Anche se la formazione sarà una missione solitaria, il tuo successo finale dipende dalla comprensione di come le tue competenze si combinano con quelle degli altri.

• The Shadowblade (sviluppatore): un maestro della forgia e del fronte. Sei l'artigiano che crea le lame, costruisce gli strumenti e affronta il nemico nei dettagli intricati del codice. Il tuo percorso è fatto di precisione, abilità e creazione pratica.
• L'Evocatore (architetto): un grande stratega e orchestratore. Non vedi un singolo agente, ma l'intero campo di battaglia. Progetti i master blueprint che consentono a interi sistemi di agenti di comunicare, collaborare e raggiungere un obiettivo molto più grande di qualsiasi singolo componente.
• Lo studioso (data engineer): un ricercatore di verità nascoste e custode della saggezza. Ti avventuri nella vasta e selvaggia natura dei dati per scoprire l'intelligenza che dà ai tuoi agenti uno scopo e una visione. Le tue conoscenze possono rivelare la debolezza di un nemico o dare potere a un alleato.
• Il Guardiano (DevOps / SRE): il protettore e lo scudo del regno. Costruisci le fortezze, gestisci le linee di alimentazione e assicurati che l'intero sistema possa resistere agli inevitabili attacchi di The Static. La tua forza è la base su cui si fonda la vittoria della tua squadra.

La tua missione

L'allenamento inizierà come esercizio autonomo. Seguirai il percorso che hai scelto, acquisendo le competenze uniche necessarie per padroneggiare il tuo ruolo. Al termine della prova, dovrai affrontare uno spettro nato da The Static, un mini boss che si nutre delle sfide specifiche della tua professione.

Solo se padroneggi il tuo ruolo individuale puoi prepararti per la prova finale. Dovrai quindi formare un gruppo con campioni delle altre classi. Insieme, vi avventurerete nel cuore della corruzione per affrontare un boss finale.

Una sfida finale collaborativa che metterà alla prova la vostra forza combinata e determinerà il destino dell'Agentverse.

L'Agentverse attende i suoi eroi. Risponderai alla chiamata?

2. Il codice di Shadowblade

Il Codex di Shadowblade è aperto davanti a te. Rispondi alla sua chiamata. L'Agentverse è minacciato dal caos strisciante di The Static e solo chi padroneggia le tecniche di questo codice può reagire. È un percorso di precisione e disciplina. Oggi inizia il tuo allenamento. Imparerai a usare l'AI non come un semplice strumento, ma come una lama senziente che deve essere domata e padroneggiata. Segui gli insegnamenti qui riportati e creerai un'arma di pura logica: un agente intelligente, affinato e pronto alla battaglia.

Obiettivi didattici

• Usa la tua arma principale: l'interfaccia a riga di comando di Gemini.
• Richiama arsenali esterni integrando gli strumenti MCP con la CLI Gemini per analizzare codebase sconosciute.
• Trasforma la tua intenzione in un "Vibe" utilizzando i documenti di progettazione per dare comandi al tuo partner AI.
• Crea una soluzione pulita e modulare creando il tuo primo agente autonomo con l'Agent Development Kit (ADK).
• Creazione di suite di valutazione automatizzate per testare e convalidare l'agente.
• Crea una pipeline CI completa per testare, inserire in un container e archiviare automaticamente l'agente.

3. Preparazione del campo di addestramento

👉 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),

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

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

👉 Apri il terminale nell'IDE cloud.

👉💻 Nel terminale, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

👉💻 Clona il progetto di bootstrap da GitHub:

git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh

git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh

git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.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 ~/agentverse-developer
./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 \
                        artifactregistry.googleapis.com \
                        run.googleapis.com \
                        cloudfunctions.googleapis.com \
                        cloudbuild.googleapis.com \
                        iam.googleapis.com \
                        aiplatform.googleapis.com \
                        cloudresourcemanager.googleapis.com

👉💻 Se non hai ancora creato un repository Artifact Registry denominato agentverse-repo, esegui il seguente comando per crearlo:

. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="Repository for Agentverse agents"

Configurazione dell'autorizzazione

👉💻 Concedi le autorizzazioni necessarie eseguendo questi comandi nel terminale: :

. ~/agentverse-developer/set_env.sh

# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/artifactregistry.admin"

# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.editor"

# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/run.admin"

# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/aiplatform.user"

# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.logWriter"


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.viewer"

👉💻 Mentre inizi l'allenamento, prepareremo la sfida finale. I seguenti comandi evocano gli Spettri dal caos statico, creando i boss per il test.

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh

npm update -g @google/gemini-cli

4. Padroneggiare l'arma principale: introduzione all'interfaccia a riga di comando di Gemini

Prima di poter utilizzare le armi avanzate e specializzate dell'arsenale del server MCP, devi prima padroneggiare l'arma principale: la CLI Gemini. Questa è la lama più versatile, in grado di modellare il mondo digitale con i tuoi comandi. Questi esercizi ti aiuteranno ad acquisire familiarità con la gestione e le funzionalità di base.

L'interfaccia a riga di comando (CLI) di Gemini è più di uno strumento: è un'estensione della tua volontà. Questo agente AI open source, basato sui modelli Gemini, opera in un ciclo "ragiona e agisci" (ReAct). Analizza la tua intenzione, seleziona la tecnica appropriata, la esegue e osserva il risultato per completare attività complesse. Prima di poter usare armi più specializzate, devi padroneggiare questa lama principale.

Guida introduttiva all'interfaccia a riga di comando di Gemini

👉💻 Entra nel campo di addestramento e impugna la tua arma. Nel terminale Cloud Shell, vai al tuo armory personale.

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

👉💻 Evoca Gemini per la prima volta. Ti guiderà durante la sintonizzazione iniziale.

clear
gemini --model=gemini-2.5-flash --yolo

Se ti viene chiesto Do you want to connect Cloud Shell editor to Gemini CLI?, scegli NO.

Familiarizzazione con le armi

Ogni maestro artigiano conosce i propri strumenti. Devi imparare le tecniche di base della tua lama prima di affrontare un vero nemico.

👉✨ Ogni strumento incantato ha rune che ne descrivono il potere. Leggili subito. Nel prompt di Gemini, digita:

/help

Osserva l'elenco dei comandi. Queste sono le tecniche fondamentali per gestire la memoria (focus), la conversazione (chat) e gli arsenali esterni (tools). Questo è il tuo manuale di combattimento.

👉✨ La tua arma è in sintonia con l'ambiente, il che ti consente di manipolare direttamente il campo di battaglia. Esegui un comando per il mondo esterno al server blade:

!ls -l

👉✨ L'interfaccia a riga di comando di Gemini possiede una serie di funzionalità integrate. Per esaminarli:

/tools

Vedrai un elenco che include ReadFile, WriteFile e GoogleSearch. Queste sono le tecniche predefinite che puoi utilizzare senza dover ricorrere a un arsenale esterno.

👉✨ Un'arma è efficace solo se è messa a fuoco correttamente. Il Gemini Blade può contenere la "consapevolezza tattica" (contesto) per guidare le sue azioni.

/memory show

Al momento è vuoto.

👉✨ Inserisci i seguenti dati tattici nella memoria:

/memory add "The Shadowblade's primary foe is The Static."

Esegui di nuovo /memory show per confermare che la tua lama ha assorbito queste informazioni.

👉✨ Per essere efficace, la tua arma deve comprendere la missione. Il sigillo @ ordina alla lama di analizzare l'intelligence. Innanzitutto, crea un file di briefing della missione:

!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md

👉✨ Ora, chiedi a Gemini CLI di analizzare il briefing e di comunicare i risultati:

Explain the contents of the file @mission.md

La tua arma principale ora è consapevole del suo obiettivo.

👉💻 Premi Ctrl+C due volte per uscire dall'interfaccia a riga di comando di Gemini

5. Analisi del campo di battaglia: interazione pratica con il vibe coding

Gli esercizi di addestramento sono stati completati. Hai imparato le posizioni e i colpi di base della tua arma principale, la CLI Gemini. Ma una lama non è veramente forgiata finché non è stata testata nella fucina della creazione e sintonizzata con l'armeria della guerra. Prima di affrontare il vero nemico, devi prima esplorare e modellare l'ambiente circostante, il campo di battaglia digitale.

Questo capitolo riguarda il passaggio dalla teoria alla pratica. Per prima cosa, stabilirai la tua presenza nell'Agentverse chiedendo al tuo blade Gemini di creare il tuo Maker's Mark, una firma digitale sotto forma di sito web personale, creato solo a partire dal tuo intento. Poi, aumenterai il tuo potere attivando un arsenale locale di strumenti avanzati, un server MCP, e sintonizzando la tua lama sulla sua frequenza, il che ti permetterà di eseguire manovre complesse come la gestione dei repository di codice con comandi semplici e decisivi.

Stabilire il tuo Maker's Mark

Un vero Shadowblade non viene riconosciuto solo per la sua arma, ma anche per il suo stile inconfondibile, il suo marchio del creatore. Questo segno sarà la tua presenza digitale, un profilo personale che annuncia la tua identità all'Agentverse. Qui, ordinerai al tuo Gemini Blade di eseguire la complessa tecnica necessaria per definire questa identità.

👉💻 Se hai chiuso Gemini CLI nella sezione precedente, assicurati di riavviarla. Nel terminale esegui

clear
cd ~/agentverse-developer/tabletop
gemini --model=gemini-2.5-flash --yolo

👉✨ Con un unico comando potente, chiedi all'interfaccia a riga di comando di Gemini di creare le fondamenta della tua identità digitale:

In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional.

Gemini ha calcolato la sequenza di azioni richieste.

Il vero valore di una tecnica si vede solo in uno scenario reale. Comanda al blade di avviare una simulazione locale.

👉✨ Nell'interfaccia a riga di comando di Gemini, esegui il comando di simulazione:

Use Python's built-in web server to start the Shadowblade Profile website you just created.

Nota: la lama potrebbe richiedere alcuni tentativi per eseguire correttamente questa operazione. Continua finché non obbedisce.

Accetta le azioni suggerite. Gemini confermerà che la simulazione è attiva.

👀 Gemini CLI risponderà, confermando che la simulazione è attiva e che la filigrana digitale è visibile:

The website is now being served on port 8000. You can access it at http://localhost:8000.

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

Il tuo sito web potrebbe avere un aspetto diverso dal mio. Questo è il tuo segno unico.

👉✨ La tecnica di firma è stata perfezionata e la simulazione dal vivo non è più necessaria. Ordina al Blade di ritirarsi.

Stop the Shadowblade Profile website

Hai comandato correttamente all'interfaccia a riga di comando Gemini di eseguire una serie di azioni per tuo conto. Ma un maestro Shadowblade sa che il vero potere richiede disciplina e lungimiranza. Consentire a un agente AI di eseguire comandi direttamente nel tuo ambiente è un'arma a doppio taglio. Cosa succede se il comando non era quello di avviare un semplice server web, ma di eliminare file critici? Un comando incauto potrebbe distruggere l'intero campo di addestramento.

Per questo motivo, gli artigiani più saggi praticano le loro tecniche più potenti o non testate in un campo di addestramento protetto, una dimensione contenuta nota come sandbox.

👉💻 Premi Ctrl+C due volte per uscire dall'interfaccia a riga di comando di Gemini

La sandbox della CLI Gemini (gemini --sandbox) crea un container temporaneo e isolato per la tua sessione. Qualsiasi comando eseguito dall'AI, qualsiasi file scritto, qualsiasi processo avviato esiste solo all'interno di questo regno fantasma. Non può toccare, alterare o danneggiare l'ambiente Cloud Shell effettivo. È il luogo ideale per testare nuovi potenti strumenti, analizzare codice sconosciuto o dare istruzioni complesse all'AI senza rischiare conseguenze indesiderate. È l'incarnazione della prudenza di uno Shadowblade.

👉💻 Ora, svolgerai un rituale di contenimento per comprenderne il potere.

clear
gemini --sandbox --yolo

Ora operi all'interno della dimensione isolata. Per la CLI Gemini, tutto sembrerà normale. Dimostriamolo. 👉💻 Ordina alla lama di eseguire esattamente la stessa tecnica di prima:

Use the Python's built-in web server to start the Shadowblade Profile website, you just created.

Gemini segnalerà l'esito positivo, ritenendo di aver ripristinato il tuo sito web sulla porta 8000. Ma la protezione è forte.

👉 Vai ad Anteprima web e prova a visualizzare il tuo sito sulla porta 8000.

Questa volta, verrà visualizzato un errore. La connessione non riuscirà. Non puoi accedere al sito web.

Non si tratta di un errore dello strumento, ma di una prova della potenza della sandbox. Il server web è in esecuzione, ma all'interno della dimensione contenuta, completamente isolato dal browser e dal mondo esterno. La protezione funziona perfettamente. Hai utilizzato con successo una tecnica potente in modo da non avere alcun impatto sul tuo ambiente effettivo.

👉💻 Premi due volte Ctrl+C per uscire dall'interfaccia a riga di comando di Gemini.

La tua identità digitale è ora stabilita e, cosa ancora più importante, hai imparato la saggezza fondamentale di usare un grande potere con ancora maggiore cautela.

Attivare il tuo arsenale locale: Gitea Armory

Il vero potenziale di uno Shadowblade non si sblocca solo con le sue abilità personali, ma anche con la qualità del suo arsenale. Ora attiverai il tuo rack di armi locale, un server Gitea, e sintonizzerai la tua lama sulla sua potenza. Questo arsenale è connesso alla tua CLI Gemini tramite un server Model Context Protocol (MCP), un portale specializzato che consente al tuo blade AI di interagire con strumenti e servizi esterni, trasformando il tuo terminale in uno spazio di lavoro intelligente e orientato all'azione.

Nota per gli sviluppatori: considera un server MCP come un condotto di alimentazione, un portale specializzato che collega la mente della tua AI al corpo di uno strumento esterno. È ciò che trasforma l'interfaccia a riga di comando di Gemini da semplice conversatore in un vero e proprio agente orientato all'azione. Se sintonizzi il tuo blade su questi portali MCP, gli concedi la possibilità di eseguire azioni concrete: gestire file, interrogare database, interagire con le API e molto altro ancora. Esiste un intero ecosistema di questi portali, creati dagli sviluppatori per connettere gli agenti AI a piattaforme potenti. Esistono server MCP per interagire con i database, proteggere il codice o persino supportare la programmazione in coppia. Le possibilità sono vaste e consentono a uno sviluppatore di personalizzare il proprio spazio di lavoro per qualsiasi progetto.

Oggi ci concentreremo su due poteri fondamentali essenziali per qualsiasi "vibe coder": il potere di controllare la fucina e il potere di creare con l'immaginazione. Per prima cosa, sintonizzerai la tua lama su un server Git, ottenendo il controllo del tuo repository di codice sorgente. Dopodiché, ti connetterai a un secondo server MCP per la generazione di immagini, il che ti consentirà di creare asset visivi con un semplice comando.

Iniziamo evocando il primo e più fondamentale elemento del tuo nuovo arsenale: l'armeria stessa.

👉💻 Nel terminale, esegui lo script di attivazione per richiamare l'armeria:

cd ~/agentverse-developer
./gitea.sh

Questo script attiva il container Gitea e apre il portale MCP, consentendo a Gemini di percepirlo e interagire con esso.

👉 Per esaminare il tuo nuovo arsenale, devi guardare l'anteprima web.

👉 Dall'icona Anteprima web nella barra degli strumenti di Cloud Shell, seleziona Cambia porta e impostala su 3005.

👉 Viene visualizzata una pagina di accesso a Gitea. Entra nell'armeria usando la formula magica: * Nome utente: dev * Password: dev

👉💻 La tua interfaccia a riga di comando di Gemini non può ancora vedere questo nuovo arsenale. Devi eseguire un'intonazione critica, iscrivendo la posizione dell'armeria nelle rune di configurazione della CLI Gemini (settings.json). Nel terminale, esegui:

jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

👀 Il file settings.json è la configurazione centrale della CLI Gemini, che funge da grimorio di preferenze e funzionalità. Determina il comportamento, l'aspetto e, soprattutto, i poteri esterni che può esercitare. Questo file si trova in genere nella directory home all'indirizzo ~/.gemini/settings.json e applica le sue regole a tutti i tuoi progetti. Tuttavia, puoi anche creare file settings.json specifici per il progetto all'interno di una directory .gemini nella cartella del progetto per ignorare le impostazioni globali.

"mcpServers": {
  "gitea": {
    "url": "http://localhost:8085/sse"
  }
}

Questa impostazione indica a Gemini: "L'arsenale denominato gitea è attivo e in ascolto di comandi a questo indirizzo di rete specifico".

👉💻 Inserisci di nuovo l'interfaccia a riga di comando di Gemini. Nel terminale, esegui:

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ Verifica che la tua lama abbia scoperto la nuova arma. Chiedigli di elencare tutti gli arsenali disponibili tramite i suoi portali MCP:

/mcp

Ora dovresti vedere gitea e il relativo elenco di tecniche disponibili. La lama è sintonizzata.

Il tuo profilo "Marchio dell'autore" è una tecnica finemente realizzata, ma ha bisogno di un posto adeguato nell'arsenale, un fodero per tenerlo al sicuro. Comanda a Gemini CLI di crearne uno.

Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.

Torna all'interfaccia web di Gitea e aggiorna la pagina. Vedrai che è stato creato il nuovo repository shadowblade-profile.

Con il fodero pronto, fissa il lavoro. Chiedi a Gemini di eseguire il commit dei file del sito web del tuo profilo.

👉💻 Esegui il comando finale per questa tecnica nell'interfaccia a riga di comando di Gemini:

Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.

Un vero maestro verifica il proprio lavoro. Torna alla scheda Gitea e aggiorna la pagina del repository. index.html e styles.css sono ora archiviati in modo sicuro.

👉✨ Uno Shadowblade è definito dal suo sigillo, ma come ricorderai, sul tuo sito web manca l'immagine del profilo. Un maestro artigiano riconosce i propri difetti per perfezionarli. Devi registrare questa imperfezione nei registri dell'armeria.

File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.

Visualizza il problema in Gitea

Per forgiare il sigillo mancante, devi evocare un altro tipo di potere, uno spirito della creazione di Vertex AI in grado di generare immagini dal puro pensiero. Per questo è necessario un altro portale MCP.

👉💻 Premi Ctrl+C due volte per uscire dall'interfaccia a riga di comando di Gemini

👉💻 Innanzitutto, installa il server del portale. Nel terminale, esegui:

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh

👉 Quando richiesto, scegli l'opzione 3, in quanto dobbiamo generare solo un'immagine per il nostro profilo.

👉💻 Lo spirito della creazione richiede un vaso sacro, ovvero un bucket Google Cloud Storage, per contenere le sue creazioni. Creiamone uno ora. Nel terminale, esegui:

. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID

👉💻 Ora esegui il rituale di sintonizzazione, collegando la tua interfaccia a riga di comando di Gemini a questa nuova forza creativa. Nel terminale, esegui:

. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

Questo "rituale di sintonia" è uno script della shell che configura la CLI Gemini per utilizzare un nuovo potente strumento: Imagen, il modello di generazione di immagini di Google. Fondamentalmente, lo fa configurando un server MCP (Model Context Protocol) per Imagen. Questo server MCP funge da ponte, consentendo alla CLI Gemini di comunicare e utilizzare le funzionalità di Imagen. A questo scopo, modifica direttamente il file di configurazione centrale della CLI, ~/.gemini/settings.json, per insegnare a eseguire il comando mcp-imagen-go con le credenziali cloud corrette.

👀 Dopo il rituale, il file settings.json ha un nuovo blocco che insegna a Gemini CLI una nuova skill:

"imagen": {
    "command": "mcp-imagen-go",
    "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "55000",
        "GENMEDIA_BUCKET": "your-bucket-name",
        "PROJECT_ID": "your-project-id",
        "LOCATION": "your-region"
    }
}

In questo modo, la CLI Gemini indica: "Quando un'attività richiede lo strumento Imagen, devi eseguire il programma denominato mcp-imagen-go (che è il server MCP di Imagen). Quando lo esegui, devi fornire questo ambiente specifico (env): un bucket Google Cloud Storage in cui salvare le immagini e l'ID progetto e la posizione da utilizzare per le API cloud." Configurando questo server MCP, fornisci in modo efficace alla CLI Gemini l'accesso alla potenza di generazione di immagini di Imagen."

👉💻 Apri Gemini e inserisci il comando di perfezionamento. Nel terminale, esegui:

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ Con un unico comando potente, chiedi all'interfaccia a riga di comando di Gemini di creare le basi per la tua identità digitale. In Gemini CLI, esegui il comando:

Generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.

👉✨ Lo spirito genererà l'immagine e la inserirà nel tuo vaso sacro. Ora, ordina alla lama di usare questo sigillo appena forgiato.

Modify the index.html file to add my profile picture. Use the image I just generated.

👉✨ Avvia il sito web un'ultima volta per ammirare il tuo lavoro perfezionato.

start the website with a simple HTTP server via Python

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

👉✨ Infine, esegui il commit della correzione, annota il completamento dell'attività e chiudi il problema che hai segnalato nei registri dell'armory.

Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"

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

👉✨ Verifica in Gitea che l'immagine sia aggiornata e il problema sia chiuso. Il tuo lavoro è stato completato. Disattiva il server.

stop website server

👉💻 Premi due volte Ctrl+C per uscire.

6. Assemblaggio dell'agente Shadowblade: vibe code con i sistemi di protezione

Il tempo per gli esercizi di pratica è terminato. L'eco dell'acciaio sulla pietra svanisce. Hai imparato a usare la tua arma principale e hai preparato il tuo arsenale per la guerra. Ora affronterai la vera prova di uno Shadowblade: assemblare l'agente stesso. Si tratta dell'arte di dare vita alla logica, utilizzando un progetto sacro del Codex per costruire l'intelligenza di base di un agente, creando un portatore senziente per le lame del tuo arsenale in grado di pensare, ragionare e agire in modo autonomo.

La tua prima missione è entrare in un workshop esistente, un codebase predefinito, e forgiare il tuo campione a partire dalle sue parti.

The Assembly Ritual

Prima della prima scintilla della fucina, un tecnico esperto esamina il suo laboratorio, comprendendo ogni strumento e ogni schema. Quando entri in un campo di battaglia sconosciuto come una base di codice ampia ed esistente, la tua priorità è la ricognizione. Devi capire la situazione: l'architettura esistente, gli obiettivi finali e i protocolli di coinvolgimento. Solo acquisendo familiarità con i progetti della fortezza e i suoi standard puoi contribuire efficacemente con le tue competenze.

La tua Gemini CLI, la tua spia sempre presente, può aiutarti in questa ricognizione:

• Fornire riepiloghi di alto livello:può leggere l'intero codex (o codebase) e darti una rapida comprensione del suo scopo e dei suoi componenti chiave.
• Aiuto per la configurazione dell'ambiente:può guidarti attraverso i rituali arcani dell'installazione degli strumenti e della configurazione della macchina.
• Navigare nei codebase:può fungere da guida, aiutandoti a esplorare la logica complessa e a trovare passaggi nascosti all'interno del codice.
• Genera documenti di onboarding:può creare pergamene personalizzate che chiariscono gli obiettivi, i ruoli e le risorse per i nuovi alleati che si uniscono alla tua causa.
• Automatizza l'apprendimento e le domande e risposte: diventa il tuo studioso personale, rispondendo a domande su funzionalità o comportamento del codice, consentendoti di combattere con maggiore indipendenza.

👉💻 Nel primo terminale, vai alla directory shadowblade e chiama il tuo partner AI:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ Ora, ordina al tuo esploratore di perlustrare il campo di battaglia e fare rapporto.

Analyze the entire project and provide a high-level summary.

Ora che il terreno esistente è mappato, devi consultare il progetto di ciò che stai per costruire. Gli agenti più potenti non sono improvvisati, ma costruiti a partire da un progetto preciso.

Nota dello sviluppatore: questo documento di progettazione funge da progetto autorevole per il progetto. Il suo scopo è garantire la chiarezza degli obiettivi e dell'implementazione tecnica prima di investire un impegno di sviluppo significativo. Un piano ben definito garantisce l'allineamento di tutti gli sviluppatori, riduce il rischio di rilavorazione e contribuisce a prevenire il debito tecnico e l'espansione dell'ambito. È lo strumento principale per mantenere la velocità del progetto e la qualità del codice, soprattutto man mano che il team cresce o vengono inseriti nuovi membri.

Uno degli obiettivi principali di questo documento è definire non solo il "percorso felice", ma anche i casi limite e le modalità di errore, soprattutto quando si utilizzano gli LLM. La mia esperienza con gli LLM è eccellente per la generazione di codice ottimistico in cui tutti gli input sono validi e tutte le chiamate esterne vanno a buon fine. Per creare software robusti e pronti per la produzione, dobbiamo guidare esplicitamente l'AI definendo le contingenze per scenari come:

• Argomenti non validi o con formato errato passati a una funzione.
• Errori di chiamata API, timeout di rete o codici di errore imprevisti da servizi esterni.
• Gestione di strutture di dati nulle o vuote in cui sono previsti dati.
• Race condition o problemi di concorrenza.

Specificando il comportamento previsto per questi casi nella progettazione, chiediamo al LLM di generare codice più resiliente, riducendo significativamente il tempo dedicato al refactoring manuale e alla correzione dei bug.

👉✨ Chiedi a Gemini di recuperare questo progetto sacro per te.

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md  and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create file just yet. 

👉✨ Lo scorrimento è lungo e dettagliato. Chiedi a Gemini di distillare la sua essenza.

Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet. 

Ora hai il piano. Ma prima che venga forgiata una sola riga di codice, un maestro artigiano stabilisce le leggi della fucina. Si tratta di disciplina e scalabilità. Queste sono le linee guida per la codifica. Non sono semplici suggerimenti, ma rune di potere che garantiscono che ogni componente sia costruito con la stessa precisione e resistenza. Impediscono al caos dello stile individuale di corrompere la creazione finale, garantendo che l'agente sia resiliente, gestibile e puro, consentendo a nuovi artigiani di unirsi al progetto senza interrompere l'armonia dell'insieme.

Per integrare queste leggi direttamente nella coscienza del nostro partner di AI, utilizziamo un artefatto speciale: il file GEMINI.md. Quando viene richiamata la CLI Gemini, questa cerca automaticamente il file e carica i suoi contenuti nella memoria di lavoro dell'AI. Diventa un'istruzione persistente a livello di progetto. Un talismano che sussurra costantemente le regole della fucina all'AI.

Incidiamo queste rune.

👉💻 Esci da Gemini per un momento premendo due volte Ctrl+C.

👉💻 Nel terminale, esegui il seguente comando per scrivere il file delle linee guida.

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

Con le leggi incise, richiamiamo il nostro partner AI e assistiamo alla magia dell'artefatto.

👉💻 Riavvia l'interfaccia a riga di comando di Gemini dalla directory shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ Ora, chiedi a Gemini di mostrarti a cosa sta pensando. Le rune sono state lette.

/memory show 

Questo è il momento cruciale. Fornirai lo schema (agent_design.md) e le leggi della fucina (GEMINI.md) ed emetterai il grande incantesimo della creazione.

👉✨ Questo è l'unico e potente comando che creerà il tuo agente. Emetti ora:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.

Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.

and you are currently already in the shadowblade working directory

👀 Gemini ha ora creato la logica principale dell'agente in agent.py. Il nucleo di questo nuovo file definisce l'intelligenza dell'agente, collegando il suo modello di ragionamento a un insieme di strumenti esterni:

PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="shadowblade_combat_agent",
    instruction="""
      You are the Shadowblade, an elite combat agent operating on a digital battleground.
      Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
  ......
      5.  You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.

      General Rules of Engagement:
      - If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
      - You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='python3',
                args=[PATH_TO_MCP_SERVER]
            )
        )
    ]
)

Il parametro tools. L'agente è progettato per utilizzare un MCPToolset che si connette a un arsenale esterno definito in mcp_server.py.

👀 Vai alla sezione ~/agentverse-developer/shadowblade/mcp_server.py nell'editor e prenditi un momento per capire cosa fa. È la fonte di tutte le armi a disposizione di Shadowblade. Al momento, l'armeria è piuttosto spoglia.

👉✨ Chiediamo a Gemini di forgiare sette nuove armi per l'arsenale. Esegui il seguente prompt nell'interfaccia a riga di comando Gemini:

I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:

1.  **A 'Refactoring Sickle'**:
    -   **Function Name:** `hone_refactoring_sickle`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
    -   **Weapon Name:** "Refactoring Sickle"
    -   **Damage Type:** "Cleansing"
    -   **Base Damage:** Random integer between 100 and 136
    -   **Critical Hit Chance:** Random float between 0.10 and 0.20
    -   **Special Effect:** "Pruning - improves code health and maintainability with each strike."

2.  **A 'Quickstart Crossbow'**:
    -   **Function Name:** `fire_quickstart_crossbow`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
    -   **Weapon Name:** "Quickstart Crossbow"
    -   **Damage Type:** "Initiative"
    -   **Base Damage:** Random integer between 105 and 120
    -   **Critical Hit Chance:** Random float between 0.9 and 1.0
    -   **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."

3.  **'The Gilded Gavel'**:
    -   **Function Name:** `strike_the_gilded_gavel`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
    -   **Weapon Name:** "The Gilded Gavel"
    -   **Damage Type:** "Finality"
    -   **Base Damage:** 120
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."

4.  **'Daggers of Pair Programming'**:
    -   **Function Name:** `wield_daggers_of_pair_programming`
    -   **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
    -   **Weapon Name:** "Daggers of Pair Programming"
    -   **Damage Type:** "Collaborative"
    -   **Base Damage:** Random integer between 110 and 125
    -   **Critical Hit Chance:** Random float between 0.30 and 0.50
    -   **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."

5.  **A 'Granite Maul'**:
    -   **Function Name:** `craft_granite_maul`
    -   **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
    -   **Weapon Name:** "Granite Maul"
    -   **Damage Type:** "Bludgeoning"
    -   **Base Damage:** Random integer between 115 and 125
    -   **Critical Hit Chance:** Random float between 0.05 and 0.15
    -   **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."

6.  **A 'Lens of Clarity'**:
    -   **Function Name:** `focus_lens_of_clarity`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
    -   **Weapon Name:** "Lens of Clarity"
    -   **Damage Type:** "Revelation"
    -   **Base Damage:** Random integer between 120 and 130
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."

7.  **The 'Codex of OpenAPI'**:
    -   **Function Name:** `scribe_with_codex_of_openapi`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
    -   **Weapon Name:** "Codex of OpenAPI"
    -   **Damage Type:** "Documentation"
    -   **Base Damage:** Random integer between 110 and 140
    -   **Critical Hit Chance:** Random float between 0.5 and 0.8
    -   **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."

👉 Una volta che Gemini conferma le modifiche, apri il file mcp_server.py. Scorri il codice e verifica che le sette nuove funzioni @mcp.tool() siano state aggiunte correttamente. Controlla la funzione hone_refactoring_sickle. Ha la docstring e le statistiche dell'arma corrette? Verificare il lavoro dell'AI è un'abitudine fondamentale del maestro Shadowblade.

Con l'agente forgiato e perfezionato, è arrivato il momento del suo risveglio.

👉💻 Premi Ctrl+C due volte per uscire dall'interfaccia a riga di comando di Gemini

Nota dello sviluppatore sull'output di Gemini: il codice generato da Gemini a volte può essere imprevedibile. Sebbene ci impegniamo a rispettare esattamente il design, è normale che durante le sessioni di sviluppo gli sviluppatori eseguano più iterazioni e perfezionino il codice più volte per raggiungere uno stato pronto per la produzione.

👉💻 Per assicurarti di avere il codice di produzione corretto e testato a fondo nella directory di lavoro, esegui questi comandi nel terminale:

cp  ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp  ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py

👉💻 Nel terminale, inizia il rituale per portarlo online:

cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade

👉✨ Dovresti visualizzare un output che conferma che "Shadowblade Combat Agent" è attivo e in esecuzione, in attesa del primo comando. Emette le sue prime direttive di combattimento.

We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!

👉✨ E un altro:

The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.

Hai assemblato correttamente il tuo primo agente e ne hai convalidato le capacità di combattimento. Premi due volte Ctrl+C per far riposare il tuo campione. L'assemblaggio è completo.

7. Wards of Purity: Evaluating the agents

Un agente assemblato non è un agente dimostrato. Una lama non testata è una responsabilità, ma un agente AI non testato è un pericolo molto maggiore: un elemento canaglia che potrebbe compromettere la tua missione dall'interno. Non si tratta di una semplice speculazione, ma di un principio fondamentale che uno Shadowblade deve comprendere.

La valutazione degli agenti AI è fondamentale e particolarmente difficile. A differenza di un semplice script, un agente è una fusione dinamica del tuo codice e della mente di un LLM, che ragiona in più passaggi. Il suo comportamento è emergente. Ciò significa che devi valutare non solo la qualità dell'output finale, ma anche l'efficienza e la correttezza della sua traiettoria interna. Il percorso che ha seguito per arrivarci. Ha utilizzato gli strumenti giusti? Ha generato troppi token? Una modifica alla versione del modello ha introdotto una regressione della latenza impercettibile? È fondamentale rilevare questo danneggiamento, ovvero le regressioni in termini di latenza, costi o qualità dell'output, quando si apportano qualsiasi modifica, da un semplice aggiustamento del prompt a una revisione architettonica importante, prima che possa danneggiare l'ambiente di produzione.

L'approccio generale a questa valutazione prevede un rituale sacro:

1. Innanzitutto, definisci un "set di dati di riferimento". Un insieme di scorrimenti contenenti esempi di input e i relativi output o comportamenti previsti. Questi possono includere risposte finali, l'utilizzo corretto degli strumenti o persino intere traiettorie passo passo.
2. Successivamente, definisci la logica dell'applicazione dell'agente, il nucleo della sua esistenza.
3. Infine, stabilisci i valutatori, che sono come rune di giudizio. Questi possono variare da altri LLM che fungono da giudici di qualità a un codice euristico preciso che verifica un singolo passaggio, fino a funzioni personalizzate che analizzano l'intero processo di pensiero di un agente.

L'Agent Development Kit (ADK) di Google è il kit dell'armatura fornito ai campioni proprio per questo scopo. Facilita questa complessa valutazione attraverso diversi metodi:

• Un pool di divinazione basato sul web (adk web) per la valutazione interattiva
• Esecuzione della riga di comando (adk eval) per eseguire un agente tramite un test predefinito.
• Integrazione programmatica tramite pytest per l'iscrizione di protezioni permanenti

L'ADK supporta due approcci principali: "file di test" semplici per interazioni singole e discrete tra agente e modello (un singolo duello) e "evalset" completi per sessioni multi-turn multiple e potenzialmente lunghe (una grande mischia). Questi possono misurare metriche sofisticate come tool_trajectory_avg_score, che confronta l'utilizzo effettivo degli strumenti di un agente con il percorso ideale, garantendo che funzioni con una tecnica perfetta.

Ora che hai compreso la teoria, mettila in pratica. In qualità di Shadowblade, inciderai Protezioni di purezza. Non si tratta solo di test, ma di rituali basati sull'ADK che garantiscono che la logica dell'agente sia impeccabile e il suo comportamento sia corretto.

In questo passaggio, l'utilizzo di due terminali è ancora vivamente consigliato: uno per la CLI Gemini e l'altro per l'esecuzione del test, in quanto potrebbe essere necessario uscire dalla directory di lavoro corrente (ADK).

La sfida della strategia (adk eval)

Questa prima prova è una sfida, una serie di prove progettate per testare l'intelligenza di base dell'agente in un'ampia gamma di scenari. Lo scopo è stabilire una base di competenza. Prima di testare i casi limite, dobbiamo sapere se l'agente può svolgere la sua funzione principale. Analizza correttamente la debolezza di un mostro e seleziona l'arma più efficace dal suo arsenale, non solo una volta, ma ogni volta che si presenta una sfida nota?

Per questo, adk eval è lo strumento perfetto. È progettato per eseguire un agente su un intero insieme di scenari di test predefiniti che rappresentano le missioni previste dell'agente. Questo set di dati è definito in un file JSON, uno "scroll di sfida" che funge da progetto per l'intera sfida.

Anatomia di una pagina di scorrimento delle sfide

👀 Prima di chiedere all'AI di scrivere un nuovo rotolo, devi comprendere l'antica lingua in cui è scritto. Analizziamo la struttura del file sample.evalset.json.

{
  "eval_set_id": "sample",
  "eval_cases": [
    {
      "eval_id": "case0cbaa0",
      "conversation": [
        {
          "user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
          "final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
          "intermediate_data": {
            "tool_uses": [
              { "name": "enchant_soulshard_dagger" }
            ]
          }
        }
      ]
    }
  ]
}

Questo elenco contiene un elenco di eval_cases, in cui ogni caso è una prova univoca per il tuo agente. All'interno di ogni prova, l'array di conversazione documenta una singola interazione completa. Ai nostri fini, tre rune sono di fondamentale importanza:

• user_content: questa è la sfida. È la richiesta che invii al tuo agente, il mostro che deve affrontare.
• final_response: questo è il risultato previsto. È la stringa di testo esatta che ti aspetti che l'agente pronunci al termine dell'attività. L'ADK confronta le ultime parole effettive dell'agente con questa runa per giudicarne l'eloquenza.
• intermediate_data.tool_uses: questa è la tecnica Arcane. Per un vero agente, questa è la runa più importante di tutte. Definisce non ciò che dice l'agente, ma ciò che fa. Registra il nome dello strumento (enchant_soulshard_dagger) che prevedi che l'agente utilizzi. In questo modo, il tuo agente non sarà solo un abile conversatore, ma un attore decisivo che intraprende l'azione corretta.

Ora che hai compreso il progetto, ordinerai a Gemini di scrivere una nuova versione più complessa di questo rotolo.

👉💻 Nel terminale, inserisci la directory shadowblade e richiama la CLI Gemini:

clear
cd ~/agentverse-developer/shadowblade/
gemini --model=gemini-2.5-flash --yolo

👉✨ Chiedi alla CLI Gemini di fungere da QA Scribe, creando una serie di scenari di test che definiscono il comportamento previsto per il tuo agente.

You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.

For each object within the `eval_cases` array, you must perform the following transformations:

1.  **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2.  **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3.  **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4.  **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
    *   If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
    *   If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
    *   If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5.  **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.

Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.

La CLI confermerà di aver creato il file sample.evalset.json. Con il rotolo pronto, chiudi il partner AI.

Dati sintetici

👀 Nell'Esplora file di Cloud Shell a sinistra, vai a ~/agentverse-developer/shadowblade/ e apri il file sample.evalset.json appena modificato. Esamina i suoi contenuti. Vedrai i nuovi mostri unici e i nomi degli strumenti corretti che hai chiesto a Gemini di scrivere. Questo è il risultato tangibile delle tue istruzioni, il progetto del guanto.

L'azione di comandare a un'AI di creare nuovi dati di test realistici da un modello è una tecnica potente nota come generazione di dati sintetici. Quello che hai appena fatto è un moltiplicatore strategico di forza per uno Shadowblade. Invece di creare manualmente decine di scenari di test unici. Un'attività noiosa e dispendiosa in termini di tempo per cui hai fornito un unico progetto e hai chiesto al tuo AI Scribe di trasformarlo in una serie variegata di nuove sfide.

In questo modo, puoi ampliare notevolmente i tuoi sforzi di test, creando una serie di test molto più solida e completa di quanto sarebbe fattibile manualmente. Hai usato il tuo agente non solo per costruire la spada, ma anche per forgiare le pietre per affilarla. Questo è il segno di un vero maestro.

Una volta verificato che le rune siano corrette, chiudi l'AI partner.

👉💻 Premi due volte Ctrl+C per uscire dall'interfaccia a riga di comando di Gemini.

The Rules of Judgment

Una sfida non ha senso senza regole per la vittoria. Prima di eseguire la prova, devi esaminare lo Scroll of Judgment, ovvero il file test_config.json. Questo scorrimento indica all'ADK come valutare il rendimento dell'agente.

👀 In Esplora file, apri ~/agentverse-developer/shadowblade/test_config.json. Vedrai le seguenti rune:

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

Questi sono i criteri per la vittoria:

• tool_trajectory_avg_score: questa è la misura dell'azione. Non giudica ciò che l'agente dice, ma ciò che fa. Confronta lo strumento effettivamente utilizzato dall'agente con la tecnica predetta nel rotolo della sfida. Un punteggio di 1.0 indica una corrispondenza perfetta.
• response_match_score: si tratta della Misura di eloquenza. Utilizza un LLM per valutare la corrispondenza semantica tra il report finale dell'agente e il risultato previsto. Un punteggio di 1.0 indica una corrispondenza perfetta.

Per questa esecuzione iniziale dell'addestramento, abbiamo impostato condizioni di vittoria flessibili. Le soglie sono impostate su valori estremamente bassi (0.0 e 0.1). Lo scopo non è richiedere la perfezione, ma introdurre i meccanismi di giudizio. Ci assicuriamo che, anche se la formulazione dell'agente è leggermente diversa, il guardiano riconosca comunque la sua competenza principale nella scelta dello strumento giusto e gli conceda il passaggio.

Ora, ordina all'agente di superare la prova.

👉💻 Nel terminale, esegui il comando adk eval:

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
    shadowblade \
    shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

👀 Dovresti visualizzare il seguente riepilogo, un segno della riuscita dell'agente in base alle regole permissive di questa prova (a volte non tutti i test vengono superati):

*********************************************************************
Eval Run Summary
shadowblade_combat_agent_validation:
  Tests passed: 3
  Tests failed: 0

Lo scudo della chiarezza (pytest)

The Gauntlet ha testato una strategia generale. Il secondo reparto, lo Scudo della Lucidità, mette alla prova la disciplina e comportamenti specifici. L'automazione è la parola chiave. adk eval è eccellente per i controlli manuali, mentre lo scudo pytest è una protezione programmatica scritta nel codice. Questo è essenziale perché un test che può essere eseguito come codice può essere integrato in una pipeline automatizzata. L'obiettivo finale è creare una Deployment Gauntlet (CI/CD) in cui le nostre protezioni vengono alzate automaticamente ogni volta che viene apportata una modifica, deviando bug e regressioni prima che possano contaminare l'ambiente di produzione.

👉💻 Nel terminale,richiama di nuovo Gemini dalla directory shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ Utilizza il seguente prompt in Gemini CLI per incorporare la logica di Shield in un file pytest:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located at in the current root working folder and name it `test_agent_initiative.py`.

The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1.  **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2.  **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3.  **Read and parse the JSON file**:
    *   Open the file at `eval_set_filepath`.
    *   Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4.  **Create an `EvalSet` object**:
    *   Instantiate an `EvalSet` object named `eval_set_object`.
    *   Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5.  **Call the evaluation method**:
    *   `await` a call to `AgentEvaluator.evaluate_eval_set`.
    *   Pass the following arguments:
        *   `agent_module="shadowblade"`
        *   `eval_set=eval_set_object`
        *   `criteria=evaluation_criteria`
        *   `print_detailed_results=True`

The script must include the necessary imports at the top:
*   `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
*   `EvalSet` from `google.adk.evaluation.eval_set`
*   `pytest`
*   `json`

Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.

Con le rune del secondo rione incise, esci dalla Gemini CLI.

👉💻 Premi due volte Ctrl+C.

👀 In Esplora file, apri il rotolo che hai appena chiesto a Gemini di scrivere: ~/agentverse-developer/test_agent_initiative.py.

Noterai che non si tratta solo di un file di configurazione, ma di un incantesimo scritto in Python. Il cuore di questo incantesimo è la frase await AgentEvaluator.evaluate(...).

....
@pytest.mark.asyncio
async def test_agent_initiative():
    # Define the evaluation criteria
    evaluation_criteria = {
      "tool_trajectory_avg_score": 0.0,
      "response_match_score": 0.0
    }

    # Define the path to your evalset file
    eval_set_filepath = "shadowblade/test.evalset.json"

    #...

    # 3. Call the evaluation method with the correctly typed object
    await AgentEvaluator.evaluate_eval_set(
        agent_module="shadowblade",
        eval_set=eval_set_object,
        criteria=evaluation_criteria,
        print_detailed_results=True,
    )

Esamina attentamente i suoi argomenti. Sono gli stessi componenti che hai utilizzato nell'ultima prova: l'agente shadowblade e la barra di scorrimento della sfida shadowblade.evalset.json. In questo modo, dovrebbe rivelarsi una verità profonda: il comando adk eval che hai utilizzato in precedenza è un'invocazione potente, ma questo script pytest sei tu, lo stregone, che lancia l'incantesimo sottostante. Lo strumento a riga di comando è semplicemente un wrapper pratico per la stessa libreria AgentEvaluator che ora utilizzi direttamente. Questo è un passaggio fondamentale verso la padronanza, poiché gli incantesimi lanciati tramite il codice possono essere intrecciati nei telai automatizzati di una pipeline CI/CD.

Ora che hai capito la magia, esegui il rituale per attivare lo scudo.

👉💻 Nel terminale, esegui il rituale per attivare lo scudo:

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py 
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

👀 Cerca il riepilogo dei risultati del test alla fine dell'output del log. Un risultato positivo conferma che l'agente segue correttamente i suoi protocolli e che il reparto è pronto per essere integrato nelle tue difese automatizzate.

====== 1 passed, 4 warning in 37.37s ======

Nota: se il test non riesce in modo imprevisto, molto probabilmente è perché hai esaurito il numero di richieste che puoi inviare al modello al minuto. Cerca un errore RESOURCE_EXHAUSTED nell'output del log. Se visualizzi questo errore, attendi un minuto o due affinché la quota venga reimpostata, quindi esegui di nuovo il comando pytest.

Con la verifica e l'iscrizione sia della protezione ampia che di quella precisa, il tuo agente non è solo funzionale, ma è puro, testato e pronto per il deployment.

8. Scatena Blade nell'Agentverse: CI e deployment.

Il tuo agente è stato assemblato e la sua integrità è stata verificata dai Guardiani della Purezza. Ma una protezione che non viene mantenuta in modo coerente è solo un ricordo dimenticato. Per garantire che ogni versione futura del tuo agente rimanga pura, devi creare la prima fase della Deployment Gauntlet, un rituale automatizzato che garantisce qualità e velocità.

In qualità di Shadowblade, il tuo sacro dovere è l'integrazione continua (CI). Si tratta del sistema automatizzato della fucina e del banco di prova. È la tua difesa definitiva contro la corruzione e l'errore umano. Questo rituale assicura che ogni volta che tu o un alleato aggiungete una nuova tecnica (unite il codice) al codex centrale (il repository), il guanto si risvegli automaticamente. Prima crea l'agente dal nuovo codice e poi lo sottopone immediatamente ai Wards of Purity che hai appena creato. Se una protezione fallisce, il rituale si interrompe e l'artefatto difettoso viene rifiutato immediatamente, impedendo che corrompa l'armeria. Il tuo dominio è la fucina; la tua pipeline CI garantisce che dal tuo laboratorio escano solo artefatti perfetti e pronti per la battaglia.

Una volta che un artefatto è stato ritenuto idoneo dalla tua CI, inizia la seconda fase del rituale: il deployment continuo (CD). Questo è il dominio di The Guardian. È loro solenne dovere prendere il tuo artefatto perfezionato e containerizzato e rilasciarlo in sicurezza nell'Agentverse live, gestendone il potere e garantendone la stabilità contro il caos di The Static.

In questo codice, imparerai a padroneggiare il tuo ruolo. Costruirai la parte CI del guanto di sfida. Creerai la fucina automatizzata che testa l'agente e sigilla il risultato puro in un container, preparandolo per la benedizione finale del Guardiano.

Ora utilizzerai Google Cloud Build per scrivere il rotolo per questo rituale CI. Un file cloudbuild.yaml che definisce ogni passaggio del processo di creazione e test.

👉💻 A causa della struttura del progetto dell'ADK, la configurazione della pipeline CI/CD deve risiedere nella directory principale. Nel terminale, vai alla directory principale e riavvia la CLI Gemini.

cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ Ora, invia il seguente comando a Gemini. Questo prompt funge da documento di progettazione, che descrive in dettaglio i passaggi del test che vuoi che crei.

You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.

Generate the `cloudbuild.yaml` with the following exact specifications:

1.  **A top-level `substitutions` block** containing these four key-value pairs:
    *   `_PROJECT_ID: "$PROJECT_ID"`
    *   `_REGION: "$REGION"`
    *   `_REPO_NAME: "$REPO_NAME"`
    *   `_IMAGE_TAG: "latest"`
2.  **A `steps` block** with two steps:
    *   **Step 1: 'Run Pytest Ward'**
        *   `id`: 'Run Pytest Ward'
        *   `name`: 'python:3.12-slim'
        *   `entrypoint`: 'bash'
        *   `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
            ```shell
            pip install -r shadowblade/requirements.txt && \
            pytest test_agent_initiative.py
            ```
        *   The step must include an `env` block with this exact list of three environment variables:
            *   `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
            *   `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
            *   `'GOOGLE_CLOUD_LOCATION=$_REGION'`
    *   **Step 2: 'Forge Container'**
        *   `id`: 'Forge Container'
        *   `name`: 'gcr.io/cloud-builders/docker'
        *   It must have a `waitFor` key for `['Run Pytest Ward']`.
        *   Its `args` must be a list of six specific strings in this exact order:
            1.  `'build'`
            2.  `'-t'`
            3.  `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
            4.  `'-f'`
            5.  `'./shadowblade/Dockerfile'`
            6.  `'.'`
3.  **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.

Generate only the complete and exact YAML that meets these specifications.

Con lo scorrimento cloudbuild.yaml preparato, chiedi a Google Cloud di eseguire l'intera prova.

esci da Gemini per testare il risultato.

👉💻 Nel terminale, esegui la pipeline dalla directory principale del progetto:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

Ora puoi guardare nella pagina Google Build della console Google Cloud mentre il tuo rituale automatizzato esegue ogni passaggio. Verranno eseguiti prima i test e, una volta verificato che sono andati a buon fine, verrà creato e archiviato il container dell'agente.

L'agente ha superato la prova. Ora nel tuo arsenale c'è un artefatto puro e verificato. L'atto finale è a tuo comando. Con un unico incantesimo, evocherai questo artefatto dal registro e gli darai vita come servizio pubblico su Cloud Run.

👉💻 Nel terminale, esegui il comando di deployment finale:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels codelab=agentverse \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

Congratulazioni, Shadowblade. I rituali del codice sono completi. È arrivato il momento di dimostrare il suo valore. Uno Spettro, nato dal caos che hai imparato a domare, attende la tua sfida. Preparati per la prova finale.

9. The Boss Fight

Le pergamene sono state lette, i rituali eseguiti, la sfida superata. L'agente non è solo un artefatto nello spazio di archiviazione, ma un campione forgiato nel codice, una sentinella viva nell'Agentverse in attesa del suo primo comando. È arrivato il momento di dimostrare il suo valore nel crogiolo del combattimento.

Ora parteciperai a una simulazione di fuoco vivo per mettere alla prova il tuo Shadowblade appena schierato contro uno Spectre formidabile, l'incarnazione del caos che affligge tutta la creazione. Questo è il test definitivo del tuo lavoro, dalla logica principale dell'agente al suo deployment impeccabile.

Acquisire il locus dell'agente

Prima di poter entrare nel campo di battaglia, devi possedere due chiavi: la firma unica del tuo campione (Agente Locus) e il percorso nascosto verso la tana di Spectre (URL del dungeon).

👉💻 Per prima cosa, acquisisci l'indirizzo univoco dell'agente in Agentverse, ovvero il suo Locus. Questo è l'endpoint live che collega il tuo campione al campo di battaglia.

. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app

👉💻 A questo punto, individua la destinazione. Questo comando rivela la posizione del Cerchio di Traslocazione, il portale nel dominio dello Spettro.

. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

Importante: tieni a portata di mano entrambi gli URL. Ti serviranno nell'ultimo passaggio.

Confronto con lo spettro

Ora che le coordinate sono al sicuro, vai al Cerchio di Traslazione e lancia l'incantesimo per iniziare la battaglia.

👉 Apri l'URL del Cerchio di Traslocazione nel browser per trovarti di fronte al portale scintillante che conduce alla Fortezza Cremisi.

Per violare la fortezza, devi sintonizzare l'essenza della tua Lama Ombra con il portale.

• Nella pagina, trova il campo di input runico etichettato A2A Endpoint URL (URL endpoint A2A).
• Inscrivi il sigillo del tuo campione incollando il relativo URL del locus dell'agente (il primo URL che hai copiato) in questo campo.
• Fai clic su Connetti per scatenare la magia del teletrasporto.

La luce accecante del teletrasporto si affievolisce. Non sei più nel tuo sanctum. L'aria è carica di energia, fredda e pungente. Prima di te, lo Spettro si materializza: un vortice di fruscio statico e codice corrotto, la cui luce sacrilega proietta lunghe ombre danzanti sul pavimento del dungeon. Non ha un volto, ma senti la sua presenza immensa e drenante fissata interamente su di te.

L'unico modo per vincere è la chiarezza delle tue convinzioni. È una battaglia di volontà, combattuta sul campo di battaglia della mente.

Mentre ti lanci in avanti, pronto a sferrare il tuo primo attacco, lo Spettro contrattacca. Non alza uno scudo, ma proietta una domanda direttamente nella tua coscienza, una sfida runica e scintillante tratta dal cuore del tuo addestramento.

Questa è la natura della lotta. La conoscenza è la tua arma.

• Rispondi con la saggezza che hai acquisito e la tua lama si accenderà di energia pura, distruggendo la difesa dello Spettro e sferrando un COLPO CRITICO.
• Ma se esiti, se il dubbio offusca la tua risposta, la luce della tua arma si affievolirà. Il colpo atterrerà con un tonfo patetico, infliggendo solo UNA FRAZIONE DEL SUO DANNO. Peggio ancora, lo Spettro si nutrirà della tua incertezza e il suo potere corrotto crescerà a ogni passo falso.

Ci siamo, fuoriclasse. Il tuo codice è il tuo libro di incantesimi, la tua logica è la tua spada e la tua conoscenza è lo scudo che respingerà l'ondata di caos.

Focus. Colpisci con precisione. Il destino dell'Agentverse dipende da questo.

Congratulazioni, Shadowblade.

Hai completato correttamente il codice. Hai preso un "vibe", l'hai tradotto in un design e hai utilizzato Gemini CLI per assemblare un agente intelligente. Hai inciso Wards of Purity per testarne la logica, hai creato un guanto automatico per trasformarlo in un artefatto e lo hai rilasciato nell'Agentverse. Infine, ne hai convalidato lo scopo in una prova a fuoco vivo. Hai acquisito il workflow agentico full-stack e ora sei pronto per qualsiasi sfida ti proponga l'Agentverse.

10. Pulizia: recupero dell'Agentverse

Congratulazioni per aver completato il Codex dell'Ombra! Per garantire che l'Agentverse rimanga incontaminato e che i campi di addestramento siano puliti, ora devi eseguire i rituali di pulizia finali. Verranno rimosse tutte le risorse create durante il tuo percorso.

Disattiva i componenti di Agentverse

Ora smantellerai sistematicamente i componenti di Agentverse di cui è stato eseguito il deployment.

Elimina l'agente Shadowblade su Cloud Run e nel repository Artifact Registry

Questo comando rimuove l'agente Shadowblade di cui è stato eseguito il deployment da Cloud Run e rimuove il repository di immagini in cui era archiviata l'immagine container dell'agente.

👉💻 Nel terminale, esegui:

. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

Elimina il bucket Google Cloud Storage

Questo comando rimuove il bucket utilizzato dal server Imagen MCP per archiviare le immagini generate.

👉💻 Nel terminale, esegui:

. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

Pulire file e directory locali (Cloud Shell)

Infine, cancella dall'ambiente Cloud Shell i repository clonati e i file creati. Questo passaggio è facoltativo, ma consigliato per una pulizia completa della directory di lavoro.

👉💻 Nel terminale, esegui:

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.

Ora hai eliminato correttamente tutte le tracce del tuo percorso in Agentverse. Il tuo progetto è pulito e sei pronto per la prossima avventura.

11. Per chi non è gamer: comprendere l'Agentverse in un contesto aziendale

Sebbene "Il codice di Shadowblade" utilizzi metafore coinvolgenti per i giocatori, i concetti di base sono fondamentali per lo sviluppo di software moderno, in particolare nel settore in rapida crescita dell'intelligenza artificiale e dell'automazione. Questo capitolo traduce il linguaggio avventuroso in scenari aziendali reali, spiegando come gli agenti intelligenti, lo sviluppo collaborativo e le pipeline di implementazione solide stiano trasformando le operazioni aziendali.

Vibecoding con l'interfaccia a riga di comando di Gemini: sviluppo dell'AI basato sull'intento

L'interfaccia a riga di comando (CLI) di Gemini non è un'arma magica, ma un agente assistente per sviluppatori basato sull'AI. È uno strumento intelligente che integra i modelli di AI Gemini di Google direttamente nella riga di comando. Il suo ciclo "reason and act" (ReAct) gli consente di comprendere le tue istruzioni di alto livello, suddividerle in passaggi, scegliere gli strumenti giusti (come un browser web, un editor di codice o altre utilità per sviluppatori) ed eseguire questi passaggi per raggiungere il tuo obiettivo.

Vibecoding si traduce in Intent-Driven Development o AI-Assisted Code Generation from High-Level Specifications. Anziché scrivere manualmente ogni riga di codice, descrivi la tua intenzione o "atmosfera" (un requisito aziendale, un concetto di design) in linguaggio naturale e l'assistente AI ti aiuta a generare il codice e la configurazione necessari.

Caso d'uso reale: prototipizzazione rapida di una dashboard di progetto

Immagina che il tuo team abbia bisogno di una dashboard interna rapida per visualizzare lo stato di vari progetti di agenti AI. La codifica manuale di HTML e CSS e la configurazione di un server web di base possono richiedere tempo.

1. Il tuo intento (l'atmosfera): dici al tuo assistente AI (Gemini CLI) qualcosa del tipo: "Nella cartella attuale, crea un semplice sito web di dashboard del progetto interno. Deve avere un design pulito e moderno con indicatori di stato del progetto e link rapidi ai repository del progetto. Tutto il codice deve trovarsi in file index.html e styles.css separati. Assicurati che sia ben commentato."
2. Azione AI: l'interfaccia a riga di comando di Gemini, comprendendo la tua intenzione, potrebbe:
   • Genera HTML: crea index.html con la struttura di base per una dashboard, inclusi i segnaposto per nomi, stati e link dei progetti.
   • Genera CSS: crea styles.css con regole di stile che corrispondano al tuo "design pulito e moderno" con indicatori di stato.
   • Suggerisci un server locale: ti aiuta ad avviare un server web locale (come il server HTTP integrato di Python) per visualizzare immediatamente l'anteprima della dashboard nel browser.

Ciò consente a uno sviluppatore di prototipare e iterare rapidamente interfacce utente o strumenti interni, riducendo significativamente il tempo di sviluppo iniziale e consentendogli di concentrarsi su una logica di business più complessa. Il "sito web del profilo Shadowblade" nel codelab è un esempio diretto: un comando rapido e descrittivo ha prodotto una pagina web funzionale e stilizzata basata su un design di alto livello.

Server Arsenal e MCP locali: collegare l'AI agli strumenti aziendali

Gitea (il tuo "arsenale locale") rappresenta un repository di codice interno o un sistema di controllo della versione (come GitHub o GitLab, ma potenzialmente ospitato all'interno della rete della tua azienda). È il luogo in cui vengono archiviati e gestiti in modo sicuro tutto il codice, la documentazione e la cronologia del progetto.

I server MCP (Model Context Protocol) sono connettori middleware o bridge API. Si tratta di componenti software specializzati che consentono all'assistente AI (interfaccia a riga di comando di Gemini) di interagire con altri strumenti e sistemi fondamentali per l'attività. Considerali come traduttori che consentono all'AI di "parlare" con diverse applicazioni.

Caso d'uso reale: gestione dei progetti e creazione di asset con l'aiuto dell'AI

Con i server MCP, l'assistente AI può integrarsi perfettamente nei flussi di lavoro aziendali esistenti:

• Configurazione automatica del progetto: anziché creare manualmente un nuovo repository in Gitea per un nuovo progetto, puoi chiedere alla tua AI: "Crea un nuovo repository di progetto denominato "AI-Fraud-Detection-Module" con la descrizione "Contiene la logica di base per il nuovo sistema di rilevamento delle frodi basato sull'AI". L'AI, tramite un server MCP connesso a Gitea, creerebbe quindi il repository per te.
• Monitoraggio intelligente dei problemi: se la tua AI identifica un potenziale bug o un'attività incompleta (ad esempio "immagine del profilo mancante" per la dashboard), potrebbe utilizzare un server MCP connesso al tuo sistema di monitoraggio dei problemi (ad es. Jira, Asana) a "File an issue for me in the ‘AI-Fraud-Detection-Module' repo: The data ingestion pipeline is occasionally dropping records."
• Asset di marketing on demand: hai bisogno di un'immagine personalizzata per una nuova campagna di marketing o una presentazione interna? A un assistente AI connesso tramite un server MCP a un servizio di generazione di immagini (come Imagen di Google) potrebbe essere chiesto: "Genera un'immagine banner per la nostra nuova "Piattaforma di approfondimenti sui dati", utilizzando un tema futuristico di flusso di dati con colori blu e verde". L'AI genererebbe l'immagine e potrebbe persino caricarla nel sistema di gestione degli asset digitali della tua azienda (un bucket Google Cloud Storage nel caso del codelab).

Questi ponti trasformano l'AI da strumento conversazionale in un partecipante attivo alle operazioni aziendali, eseguendo azioni concrete in diversi sistemi.

Assemblaggio dell'agente: creazione di moduli aziendali autonomi

Un agente è un modulo di AI autonomo o un bot di automazione intelligente progettato specificamente per svolgere una funzione aziendale definita. L'Agent Development Kit (ADK) è un framework per la creazione e la gestione di agenti AI, che fornisce gli strumenti e le librerie necessari per creare, testare ed eseguire il deployment di questi componenti intelligenti.

Ingegneria del contesto: guidare l'intelligenza dell'AI per risultati accurati

Nel mondo degli agenti AI, ottenere risultati accurati, coerenti e pertinenti da un'AI non dipende solo da un prompt intelligente, ma anche dal fornire all'AI il contesto giusto. Questa operazione è nota come Context Engineering: l'incorporamento sistematico di conoscenze specializzate, vincoli e linee guida operative nella memoria di lavoro dell'AI. Proprio come un esperto umano ha bisogno di un brief completo e dell'accesso a documenti pertinenti, un'AI ha bisogno di un contesto strutturato con cura per svolgere le sue attività in modo efficace.

La CLI Gemini offre un approccio potente e a più livelli all'ingegneria del contesto, passando da impostazioni generali e persistenti a istruzioni dinamiche e altamente specifiche. In questo modo, l'AI dispone sempre delle informazioni più pertinenti per generare output accurati e conformi:

1. Impostazioni a livello utente (~/.gemini/settings.json):
   • Questo file, memorizzato nella tua directory home, funge da insieme di istruzioni personali e globali per la tua AI. Definisce le preferenze predefinite, le configurazioni degli strumenti utilizzati di frequente (come i server MCP per Gitea o Imagen che hai configurato) e le linee guida generali sul comportamento. Questo contesto è sempre disponibile per l'AI, garantendo coerenza in tutti i tuoi progetti. Consideralo come se dicessi all'AI: "Questi sono gli strumenti e le configurazioni standard che preferisco e utilizzo ovunque".
2. Impostazioni a livello di progetto (.gemini/settings.json all'interno di una directory di progetto):
   • Puoi sostituire le impostazioni globali con un file .gemini/settings.json specifico del progetto, in genere situato in una cartella .gemini all'interno del progetto. In questo modo, puoi personalizzare il comportamento dell'AI e l'accesso agli strumenti in base alle esigenze specifiche di un determinato progetto. Ad esempio, un progetto potrebbe richiedere l'accesso a un database interno specifico, mentre un altro ha bisogno di uno strumento di analisi del codice specializzato. Questo livello garantisce che l'AI disponga del contesto più pertinente per l'attività in questione senza influire su altri progetti.
3. Il file GEMINI.md (contesto a livello di progetto - Il briefing quotidiano):
   • La carta del progetto: questo file Markdown, posizionato nella directory principale del progetto, viene caricato automaticamente nella memoria di lavoro della CLI Gemini quando avvii una sessione in quella directory. È il livello più immediato e dinamico di contesto specifico del progetto. GEMINI.md è dove definisci:
     • Linee guida per la codifica: regole esplicite per la qualità, la formattazione e le best practice del codice, come dimostrato in questo codelab. In questo modo, il codice generato rispetta gli standard del tuo team.
     • Personalità: puoi chiedere all'AI di adottare un ruolo o un'esperienza specifici (ad es. "Sei uno sviluppatore Python esperto specializzato in Google Agent Development Kit"). In questo modo, le risposte e la generazione di codice dell'AI vengono inquadrate in un ambito professionale pertinente.
     • Istruzioni specifiche: comandi o vincoli diretti che si applicano a tutte le attività all'interno del progetto (ad es. "Non aggiungere funzioni o logiche aggiuntive non descritte nel documento".
   • Questo file garantisce che ogni volta che interagisci con Gemini CLI all'interno di questo progetto, l'AI riceva costantemente un promemoria di queste regole cruciali, il che porta a una generazione di codice più accurata e conforme.

Sovrapponendo questo contesto, dalle preferenze degli utenti globali alle linee guida del progetto altamente specifiche in GEMINI.md, stai "progettando" in modo efficace la comprensione dell'AI. In questo modo, la precisione e la pertinenza dei suoi output migliorano notevolmente, trasformandola da un'AI per uso generico in un membro del team altamente specializzato, affidabile e conforme che comprende le sfumature del tuo progetto e gli standard della tua organizzazione.

Wards of Purity: test automatizzati e garanzia di qualità per l'AI

Un agente AI, come qualsiasi software, deve essere testato rigorosamente. Wards of Purity rappresentano i test automatizzati e le procedure di controllo qualità. Questi sono fondamentali per garantire che l'AI si comporti come previsto, sia accurata e non introduca errori o bias.

• "Golden Dataset" e dati sintetici: si tratta del tuo insieme di scenari di test standardizzati, scenari di comportamento previsto o persino dati di test generati sinteticamente. Include input di esempio (domande dei clienti, richieste aziendali) e i relativi output o azioni previsti (la risposta corretta, lo strumento esatto che l'AI deve utilizzare). In molti scenari reali, la creazione manuale di "golden dataset" completi richiede tempo e denaro. È qui che la generazione di dati sintetici diventa preziosa. Fornendo all'AI modelli e regole, puoi chiederle di creare automaticamente nuovi scenari di test realistici e vari, moltiplicando efficacemente i tuoi sforzi di test e consentendo una copertura molto più ampia di potenziali scenari.
• adk eval e pytest: questi sono i tuoi framework di test automatizzati. adk eval viene utilizzato per eseguire un batch di scenari di test predefiniti sull'agente, mentre pytest fornisce un modo programmatico per scrivere ed eseguire controlli di convalida dettagliati.

Caso d'uso reale: garantire l'accuratezza e l'affidabilità del chatbot AI con dati sintetici

Prima di implementare l'agente di assistenza clienti AI, lo sottoporresti a "Wards of Purity":

1. Gauntlet of Strategy (adk eval) con dati sintetici: anziché scrivere manualmente centinaia di domande dei clienti, definisci un modello: "Genera 100 varianti di domande comuni dell'assistenza clienti su stato dell'ordine, resi dei prodotti e risoluzione dei problemi tecnici". A questo punto, chiedi a un'AI (come Gemini CLI) di generare un insieme ampio e diversificato di file evalset.json basati su questo modello, creando di fatto dati di test sintetici. Per ogni domanda, specifichi non solo la risposta prevista, ma anche quale strumento interno deve essere richiamato dall'AI (ad es. check_order_status per "Dov'è il mio pacco?"). adk eval esegue automaticamente l'agente, confrontando le sue risposte e l'utilizzo degli strumenti con il set di dati espanso per garantire che prenda sempre le decisioni corrette.
2. Shield of Clarity (pytest): per le funzionalità critiche, scrivi script pytest. Ad esempio, un pytest potrebbe simulare una query complessa e affermare che l'AI utilizza sempre uno strumento specifico di recupero dei dati in modo corretto e restituisce una risposta strutturata, garantendo che modifiche minime al codice non interrompano la funzionalità principale.

Questi test automatizzati, notevolmente migliorati dalla potenza dei dati sintetici, sono fondamentali per rilevare le regressioni (nuovi bug introdotti dalle modifiche) e mantenere l'affidabilità degli agenti AI, soprattutto man mano che si evolvono.

Scatena la lama: CI/CD per il deployment di agenti AI

L'introduzione di un agente AI testato nel tuo ambiente aziendale live richiede una solida strategia di implementazione.

• Integrazione continua (CI): questa è la tua pipeline di test e build automatizzati. Ogni volta che uno sviluppatore esegue il commit di un nuovo codice per un agente AI, il sistema CI (come Google Cloud Build) esegue automaticamente le seguenti operazioni:
  1. Recupera il codice più recente.
  2. Installa tutte le dipendenze necessarie.
  3. Esegue tutti i "Wards of Purity" (pytest, adk eval) per verificare la logica e il comportamento dell'agente.
  4. Se tutti i test vengono superati, l'agente AI viene pacchettizzato in un'unità implementabile (in questo caso, un'immagine container Docker) e memorizzato in un Artifact Registry (il tuo "arsenale" convalidato). In questo modo, solo il codice testato e convalidato viene utilizzato.

Caso d'uso reale: deployment automatico di un agente di rilevamento delle frodi

Prendi in considerazione un agente AI progettato per rilevare le transazioni fraudolente.

1. Lo sviluppatore aggiorna il codice: un data scientist migliora l'algoritmo di rilevamento delle frodi e esegue il commit delle modifiche nel repository di codice.
2. Trigger CI (Cloud Build): Cloud Build avvia automaticamente:
   • Recupera il nuovo codice.
   • Esegue test completi, inclusi i dati storici delle transazioni, per garantire che il nuovo algoritmo identifichi con precisione i pattern di frode noti e non generi falsi positivi.
   • Se i test vengono superati, viene creata una nuova immagine Docker dell'agente di rilevamento delle frodi e viene eseguito il push in un Artifact Registry.

Questa pipeline automatizzata garantisce l'implementazione rapida, affidabile e coerente degli agenti AI, riducendo al minimo l'errore umano e accelerando l'introduzione di nuove funzionalità di AI per l'attività.

Caso d'uso reale: convalida di un agente di ottimizzazione della catena di fornitura

Dopo aver implementato un agente AI progettato per ottimizzare i livelli di inventario nella tua catena di fornitura globale:

1. Accedere all'interfaccia: accedi a una dashboard o a un'applicazione (l'"URL cerchio di traslocazione") che si connette al tuo agente AI live (tramite il suo "URL locus dell'agente", ovvero il suo endpoint API).
2. Affronta la sfida: potresti inserire uno scenario complesso (la "domanda di Spectre") come: "Abbiamo un aumento imprevisto della domanda del prodotto X nella regione Y, con una capacità di spedizione limitata. Come dobbiamo riassegnare l'inventario e adeguare la produzione per ridurre al minimo le rotture di stock e mantenere la redditività?"
3. Risposta dell'agente: il tuo agente AI, ora attivo e connesso ai sistemi aziendali, elabora questa query, utilizza i suoi algoritmi ottimizzati e fornisce un consiglio preciso (ad es. Dai la priorità alla spedizione dal magazzino A, avvia la produzione rapida nello stabilimento B e comunica al team di vendita della regione Z il potenziale ritardo di 24 ore. L'accuratezza e la velocità di questa risposta determinano se l'agente sferra un "COLPO CRITICO" contro il problema aziendale.