1. Overture
L'era dello sviluppo isolato sta per finire. La prossima ondata di evoluzione tecnologica non si baserà sul genio solitario, ma sulla 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 agentico fiorente. Una carenza in una qualsiasi area crea una debolezza che può compromettere l'intera struttura.
Questo workshop è il manuale aziendale definitivo per padroneggiare il futuro dell'agentività 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, un architetto, un data engineer e 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 del Data Engineer 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 Static, ha iniziato a sfilacciare i bordi di questo nuovo mondo. 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 controllato, Static e i suoi spettri bloccherà i progressi, trasformando la promessa dell'Agentverse in una terra 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.
Scegli il corso
Quattro percorsi distinti si aprono davanti a te, ognuno dei quali è un pilastro fondamentale nella lotta contro 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.
- La Lama d'Ombra (sviluppatore): un maestro della forgia e della prima linea. 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 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 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 Codex di Shadowblade
Il Codex dello Shadowblade è aperto davanti a te. Rispondi alla sua chiamata. L'Agentverse è minacciato dal caos strisciante di The Static e solo chi padroneggia le tecniche contenute in 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: Gemini CLI.
- Amplia il tuo arsenale con le estensioni Gemini CLI e le competenze dell'agente.
- Richiama arsenali esterni integrando gli strumenti MCP con Gemini CLI.
- 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 costruendo il tuo primo agente autonomo con Agent Development Kit (ADK).
- Inserisci hook per intercettare e proteggere il comportamento del tuo agente.
- Crea suite di valutazione automatizzate per testare e convalidare l'agente.
- Crea una pipeline CI completa per testare, inserire in container e archiviare automaticamente l'agente.
3. Preparazione del campo di addestramento
Richiedere il credito Google Cloud
⚠️ Prerequisiti importanti:
- Utilizza un account Gmail personale:devi utilizzare un account personale (ad es.
name@gmail.com). Gli account aziendali o gestiti dalla scuola non funzionano.
👉 Passaggi:
- Vai al sito per la richiesta di crediti: fai clic qui
- Accedi:incolla il link nella barra degli indirizzi e accedi con il tuo account Gmail personale.
- Accetta termini:accetta i Termini di servizio della piattaforma Google Cloud.
- Verifica del credito:cerca un messaggio di conferma dell'applicazione del credito.
- *Nota: se ti viene chiesto di inserire i dati della carta di credito, puoi ignorare la richiesta e chiudere la finestra.
A questo punto, puoi chiudere la finestra.
Configurare l'ambiente di lavoro
👉 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. Vedrai un esploratore di file sul lato sinistro. 
👉 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
👉💻 Esegui lo script di configurazione dalla directory del progetto.
⚠️ Nota sull'ID progetto: lo script suggerirà un ID progetto predefinito generato in modo casuale. Puoi premere Invio per accettare questa impostazione predefinita.
Tuttavia, se preferisci creare un nuovo progetto specifico, puoi digitare l'ID progetto che preferisci quando ti viene richiesto dallo script.
cd ~/agentverse-developer
./init.sh
Lo script gestirà automaticamente il resto della procedura di configurazione.
👉 Passaggio importante al termine: al termine dello script, devi assicurarti che nella console Google Cloud sia visualizzato il progetto corretto:
- Vai all'indirizzo console.cloud.google.com.
- Fai clic sul menu a discesa del selettore progetti nella parte superiore della pagina.
- Fai clic sulla scheda "Tutti" (poiché il nuovo progetto potrebbe non essere ancora visualizzato in "Recenti").
- Seleziona l'ID progetto che hai appena configurato nel passaggio
init.sh.
👉💻 Torna al terminale. Imposta l'ID progetto necessario:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Esegui il comando seguente per abilitare le API 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"
Configura l'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 a Gemini CLI
Prima di poter utilizzare le armi avanzate e specializzate dell'arsenale del server MCP, devi prima padroneggiare l'arma principale: Gemini CLI. 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 "reason and act" (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 a Gemini CLI
👉💻 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
👉💻 Richiedi l'aiuto di Gemini per la prima volta. Ti guiderà durante la sintonizzazione iniziale.
clear
gemini
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
👉✨ Gemini CLI 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.
👉✨ La tua lama può anche essere migliorata con le estensioni, incantesimi pre-forgiati creati da altri maestri che raggruppano strumenti, comandi e contesto in un'unica unità installabile. Controlla quali estensioni sono attualmente sintonizzate sulla tua lama:
/extensions list
Per il momento l'elenco potrebbe essere vuoto, in quanto non hai ancora installato estensioni. Evocare la prima estensione in un secondo momento, quando l'addestramento richiede la potenza della creazione di immagini.
👉✨ Oltre alle estensioni, i maestri esperti hanno codificato le loro competenze in competenze dell'agente, ovvero pergamene on demand di conoscenze specializzate. Controlla le competenze che la tua lama può scoprire:
/skills list
Le skill non vengono caricate in memoria per impostazione predefinita, ma vengono attivate solo quando necessario, in modo che il tuo blade sia sempre veloce e leggero. Imparerai a usare le competenze più avanti nel corso della formazione.
👉✨ Un'arma è efficace solo se è messa a fuoco correttamente. Il Gemini Blade può contenere la "consapevolezza tattica" (il contesto) per guidare le sue azioni.
/memory show
Al momento è vuoto, una tela bianca.
👉✨ Memorizza i seguenti dati tattici:
/memory add "The Shadowblade's primary foe is The Static."
Esegui di nuovo /memory show per confermare che la lama ha assorbito queste informazioni.
👉✨ Per essere efficace, la tua arma deve comprendere la missione. Il sigillo @ ordina alla lama di analizzare le informazioni. 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 riportare 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 da Gemini CLI
5. Analisi del campo di battaglia: interazione pratica con il vibe coding
Gli esercizi di addestramento sono stati completati. Hai imparato le pose e i colpi di base della tua arma principale, la Gemini CLI. Ma una lama non è davvero perfetta finché non viene 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 riquadro Gemini di creare il tuo Maker's Mark, una firma digitale sotto forma di sito web personale, costruito 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 consentirà di eseguire manovre complesse come la gestione dei repository di codice con comandi semplici e decisivi.
Definizione del tuo Maker's Mark
Un vero Shadowblade non viene riconosciuto solo dalla sua arma, ma anche dal 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, dovrai comandare la tua Gemini Blade per eseguire la tecnica complessa necessaria a definire questa identità.
👉💻 Se hai chiuso Gemini CLI nella sezione precedente, assicurati di riavviarla. Nel terminale, esegui
clear
cd ~/agentverse-developer/tabletop
gemini
👉✨ Con un unico e potente comando, chiedi a Gemini CLI 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. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.
Gemini ha calcolato la sequenza di azioni richieste.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI ed eseguire questo comando nel terminale.*
python -m http.server
👀 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 distintivo. 
La tua tecnica di firma è ora perfezionata e la simulazione dal vivo non è più necessaria. Ordina al Blade di ritirarsi.
👉💻 Premi Ctrl+C per uscire dal server http.
La tua identità digitale è ora stabilita e, cosa ancora più importante, hai imparato la saggezza fondamentale di esercitare un grande potere con ancora maggiore cautela.
Attiva 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 portarmi locale, un server Gitea, e sintonizzerai la tua lama sulla sua potenza. Questo arsenale è connesso a Gemini CLI 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 Gemini CLI 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 forgia 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 riattiva 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 Gemini CLI non può ancora vedere questo nuovo arsenale. Devi eseguire un'intonazione critica, iscrivendo la posizione dell'armeria nelle rune di configurazione di Gemini CLI (settings.json). Nel terminale, esegui:
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 Il file settings.json è la configurazione centrale della Gemini CLI, 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 dei comandi a questo indirizzo di rete specifico".
👉💻 Inserisci di nuovo Gemini CLI. Nel terminale, esegui:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Verifica che la tua lama abbia scoperto la nuova arma. Comandagli 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, una guaina per tenerlo al sicuro. Chiedi 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 aggiornala. 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 in Gemini CLI:
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 diverso tipo di potere, uno spirito della creazione in grado di generare immagini dal puro pensiero. Nella sezione Gitea, hai modificato manualmente le rune di configurazione per sintonizzare il blade su un server MCP, l'approccio "raw". Ora imparerai la tecnica moderna: le estensioni Gemini CLI.
Un'estensione è un incantesimo predefinito che raggruppa server MCP, comandi personalizzati, contesto e impostazioni in un'unica unità installabile. Un incantesimo sostituisce decine di righe di configurazione manuale.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI
Prima di evocare lo spirito della creazione, devi prima sbloccare il suo potere nel tuo regno. L'estensione Nano Banana utilizza l'API Generative Language, un gateway separato dai servizi Vertex AI che hai utilizzato. Devi attivare questo gateway e creare una chiave univoca per concedere l'accesso allo spirito.
👉💻 Nel terminale, abilita l'API:
gcloud services enable generativelanguage.googleapis.com
👉💻 Ora crea una chiave API, il token di accesso personale dello spirito:
- Vai alla pagina Credenziali della console Google Cloud.
- Fai clic su + CREA CREDENZIALI in alto e seleziona Chiave API.
- Assegna alla chiave API un nome significativo, ad esempio Chiave API Generative Language.
- Nel menu a discesa delle limitazioni dell'API, scegli API Generative Language.
- Crea e copia la chiave: ti servirà nel passaggio successivo.
👉💻 Installa l'estensione Nano Banana, uno strumento di creazione basato sui modelli di conversione da testo a immagine specializzati di Gemini di Google. Nel terminale, esegui:
gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
Quando ti viene richiesta la chiave API, incolla la chiave che hai appena creato e premi Invio.
👉💻 È necessario un ultimo aggiustamento. L'ambiente di Cloud Shell indirizza tutte le richieste di AI tramite Vertex AI per impostazione predefinita, ma lo spirito di creazione parla attraverso un gateway diverso. Esegui questo comando per configurare correttamente il portale dell'estensione:
NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"
Questo singolo comando ha fatto tutto: ha scaricato il server MCP, registrato i suoi strumenti e installato i comandi personalizzati, il tutto senza che tu toccassi settings.json.
👀 Nota per gli sviluppatori: estensioni e server MCP non elaborati. Confronta questa configurazione con quella di Gitea. Lì hai eseguito manualmente un comando jq per inserire un URL server MCP in settings.json. Questo approccio "grezzo" è utile per comprendere il funzionamento, ma per la maggior parte degli utilizzi reali, sono preferite le estensioni. Raggruppano il server MCP, i comandi personalizzati (come /generate, /edit, /story), la configurazione dell'ambiente e persino le istruzioni contestuali (tramite un GEMINI.md in bundle) in un unico pacchetto condivisibile. Esiste un intero ecosistema di estensioni nella Galleria delle estensioni Gemini CLI.
👉💻 Inserisci di nuovo Gemini CLI e verifica che l'estensione sia attiva:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Verifica che l'estensione sia sintonizzata:
/extensions list
Ora dovresti vedere nanobanana elencato con i relativi strumenti e comandi.
👉✨ Con un unico e potente comando, chiedi all'estensione Nano Banana di creare il tuo sigillo. 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à direttamente nel tuo workspace locale. Ora, ordina alla lama di usare questo sigillo appena forgiato. (GEMINI POTREBBE AVERLO GIÀ FATTO PER TE! Controlla la risposta precedente, potrebbe essere abbastanza intelligente da farlo prima che tu glielo chieda. )
Modify the index.html file to add my profile picture. Use the image I just generated.
👉💻 In un nuovo terminale, avvia il server HTTP.
cd ~/agentverse-developer/tabletop/
python -m http.server
👀 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. 
👉✨ Nel terminale in cui è in esecuzione Gemini CLI, esegui il commit della correzione, annota il completamento dell'attività e chiudi il problema che hai segnalato nei record 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"
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI.
👀 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. 
👉💻 Nel terminale che esegue il server HTTP, premi Ctrl+C per uscire dal server HTTP.
PER CHI NON GIOCA
6. Assemblaggio dell'agente Shadowblade: vibe coding con i sistemi di protezione
Il tempo per gli esercizi di allenamento è finito. 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 dovrai affrontare la vera prova di uno Shadowblade: assemblare l'operativo 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 nel tuo arsenale che può 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 prima 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 in modo efficace con le tue competenze.
Gemini CLI, il tuo scout 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 obiettivi, ruoli e 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
👉✨ Ora, ordina al tuo esploratore di perlustrare il campo di battaglia e di fare rapporto.
Analyze the entire project and provide a high-level summary.
Ora che il rilievo 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 rilavorazioni 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. Nella mia esperienza, gli LLM sono eccellenti nella 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 in formato non corretto 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 all'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, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet.
👉✨ Il rotolo è 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 partecipare 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 Gemini CLI, questa cerca automaticamente il file e carica i suoi contenuti nella memoria di lavoro dell'AI. Diventa un'istruzione persistente a livello di progetto. Funge da 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 Gemini CLI dalla directory shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Ora, chiedi a Gemini di mostrarti a cosa sta pensando. Le rune sono state lette.
/memory show
Dotare di competenze specializzate: competenze dell'agente
Le rune GEMINI.md che hai inciso sono come un incantesimo permanente: sempre attivo, sempre a guidare la tua lama. Ma un vero maestro non porta ogni pergamena in ogni battaglia. Alcune competenze sono troppo specializzate e pesanti per essere caricate in modo permanente. È qui che entrano in gioco le abilità dell'agente.
Pensa a un'abilità dell'agente come a un rotolo sigillato nel tuo zaino. Contiene competenze specializzate, istruzioni dettagliate, script e persino dati di riferimento, ma rimane inattivo fino al momento in cui ne hai bisogno. Solo quando affronti una sfida che corrisponde al dominio della pergamena, la tua lama la estrae e ne assorbe la conoscenza. Questa tecnica è chiamata disclosure progressiva: mantiene il tuo blade veloce e leggero, attivando poteri speciali solo su richiesta.
👀 Nota per gli sviluppatori:le competenze dell'agente sono il terzo livello della gerarchia di ingegneria del contesto di Gemini CLI:
- Impostazioni utente (
~/.gemini/settings.json) - Configurazione globale - GEMINI.md: contesto persistente a livello di progetto (sempre caricato)
- Agent Skills (
.gemini/skills/): competenze on demand (caricate quando necessario)
Questo modello di divulgazione progressiva è fondamentale per l'utilizzo aziendale: un repository potrebbe contenere decine di competenze specializzate (controllo della sicurezza, migrazione del database, controlli di conformità), ma l'AI attiva solo quelle pertinenti all'attività corrente, conservando i preziosi token di contesto.
Creiamo la tua prima competenza, un elenco di competenze ADK a cui la tua lama può attingere quando crea agenti.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI. Poi, crea la directory delle competenze e iscrivi lo scorrimento:
mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---
# ADK Agent Design Expertise
When designing an ADK agent, follow these principles:
## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.
## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.
## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF
👉💻 Inserisci di nuovo Gemini CLI per visualizzare la nuova competenza creata:
cd ~/agentverse-developer/shadowblade
gemini
👉✨ Verifica che la skill sia nel tuo pacchetto:
/skills list
Dovresti vedere adk-agent-design elencato, un rotolo sigillato, inattivo e in attesa.
👉✨ Ora chiedi a Gemini qualcosa che dovrebbe attivare la skill:
What are the best practices for designing tools in an ADK agent?
Nota come la risposta ora sia basata sulle conoscenze specializzate che hai inserito nella skill. La lama non aveva questa competenza nella sua memoria di base: ha scoperto lo scorrimento pertinente e lo ha estratto solo quando la domanda corrispondeva. Questo è un esempio di divulgazione progressiva in azione.
Le competenze possono essere create per qualsiasi dominio (controllo della sicurezza, migrazione del database, controlli di conformità) e condivise con il tuo team eseguendo il commit nel controllo della versione. Ogni lama del membro del team acquisisce la stessa competenza, applicata in modo coerente.
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 a ~/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 in Gemini CLI:
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, è il momento del suo risveglio.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI
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.
PER CHI NON GIOCA
7. Guardiani della purezza: valutazione degli agenti
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.
Valutare gli 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:
- Innanzitutto, definisci un "set di dati di riferimento": un insieme di scorrimenti contenenti input di esempio e i relativi output o comportamenti previsti. Possono essere incluse risposte finali, l'utilizzo corretto degli strumenti o persino intere traiettorie passo passo.
- Successivamente, definisci la logica dell'applicazione dell'agente, il nucleo della sua esistenza.
- 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.
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 da riga di comando (
adk eval) per eseguire un agente tramite un gauntlet predefinito. - Integrazione programmatica tramite
pytestper l'iscrizione di incantesimi permanenti
L'ADK supporta due approcci principali: semplici "file di test" per interazioni singole e discrete tra agente e modello (un singolo duello) e "evalset" completi per sessioni multi-turn multiple, 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. Questi non sono semplici test, ma 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 Gemini CLI e l'altro per l'esecuzione dei 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 gauntlet.
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 unica 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. È il prompt che dai 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 cosa dice l'agente, ma cosa fa. Registra il nome dello strumento (enchant_soulshard_dagger) che prevedi che l'agente utilizzi. In questo modo, l'agente non è solo un abile conversatore, ma un attore decisivo che intraprende l'azione corretta.
Ora che hai compreso il progetto, chiederai a Gemini di scrivere una nuova versione più complessa di questo rotolo.
👉💻 Nel terminale, inserisci la directory shadowblade e richiama Gemini CLI:
clear
cd ~/agentverse-developer/shadowblade/
gemini
👉✨ Chiedi a Gemini CLI 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 preparato, 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 della tua istruzione, il progetto della sfida.
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 scalare notevolmente i tuoi sforzi di test, creando un gauntlet molto più solido e completo di quanto sarebbe fattibile manualmente. Hai utilizzato 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 il partner AI.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI.
The Rules of Judgment
Un guanto è privo di significato 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 profetizzata nel rotolo della sfida. Un punteggio di1.0indica una corrispondenza perfetta.response_match_score: questa è la misura di eloquenza. Utilizza un LLM per valutare la corrispondenza semantica tra il report finale dell'agente e il risultato previsto. Un punteggio di1.0indica una corrispondenza perfetta.
Per questa prima sessione di addestramento, abbiamo stabilito condizioni di vittoria flessibili. Le soglie sono impostate su valori estremamente bassi (0.0 e 0.1). Lo scopo non è quello di richiedere la perfezione, ma di introdurre i meccanismi del giudizio. Ci assicuriamo che, anche se la formulazione dell'agente è leggermente diversa, il pupillo 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 flessibili 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 ampia. Il secondo reparto, lo Scudo della Chiarezza, mette alla prova la disciplina e comportamenti specifici. È tutta una questione di automazione. 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 attivate automaticamente ogni volta che viene apportata una modifica, deviando bug e regressioni prima che possano compromettere l'ambiente di produzione.
👉💻 Nel terminale,richiama di nuovo Gemini dalla directory shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini
👉✨ 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 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 reparto incise, esci da 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 le sue argomentazioni. Si tratta degli 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 intorno alla stessa libreria AgentEvaluator di base 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 ward è pronto per essere integrato nelle tue difese automatizzate.
====== 1 passed, 4 warning in 37.37s ======
Nota: se il test non va a buon fine 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 Guanto ampia che dello Scudo preciso, il tuo agente non è solo funzionale, ma è puro, testato e pronto per il deployment.
PER CHI NON GIOCA
Wards of Vigilance: Gemini CLI Hooks
Il test dei Guardiani della Purezza viene eseguito dopo la battaglia. Ma cosa succede durante la battaglia? Un'Ombra Disciplinata non si limita a eseguire test a posteriori, ma posiziona sentinelle vigili che osservano ogni colpo mentre viene sferrato, intercettando azioni pericolose o sconsiderate prima che possano causare danni.
Questi sentinelle sono Gemini CLI Hooks, ovvero script che vengono eseguiti in punti specifici del loop agentico. Ti consentono di intercettare, convalidare e personalizzare il comportamento dell'agente senza modificarne il codice.
👀 Nota per gli sviluppatori: gli hook vengono attivati da eventi nel ciclo di vita dell'agente:
BeforeTool: viene attivato prima dell'esecuzione di uno strumento, ideale per la convalida della sicurezza ("Questo comando della shell è sicuro?")AfterTool: viene attivato dopo l'esecuzione di uno strumento. È utile per controllare i risultati e il logging.BeforeAgent: viene attivato prima che l'agente inizi il ragionamento. Può inserire un contesto aggiuntivo o bloccare prompt pericolosi.AfterAgent: viene attivato al termine dell'agente. Può rifiutare le risposte di scarsa qualità e forzare i nuovi tentativi.
Gli hook vengono configurati in settings.json e vengono eseguiti in modo sincrono: l'agente attende il loro completamento prima di procedere. Ciò li rende ideali per l'applicazione di criteri di sicurezza, controlli di conformità e controlli di qualità negli ambienti aziendali.
Creiamo una semplice protezione che monitori l'utilizzo degli strumenti dell'agente.
👉💻 Nel terminale, crea uno script hook:
mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh
👉💻 Ora registra questo hook in un file di impostazioni a livello di progetto:
mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
"hooks": {
"BeforeTool": [
{
"matcher": "*",
"hooks": [
{
"name": "tool-logger",
"type": "command",
"command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
"timeout": 5000
}
]
}
]
}
}
EOF
Questa protezione è semplice ma efficace. Ogni volta che l'agente prende uno strumento, qualsiasi strumento, viene attivato prima l'hook, che registra il nome dello strumento in un audit log, e poi consente di procedere con l'azione. In un ambiente di produzione, potresti sostituire "allow" con "deny" per bloccare operazioni pericolose (come impedire all'agente di eliminare file), applicare criteri di revisione del codice o indirizzare chiamate di strumenti sensibili tramite un flusso di lavoro di approvazione.
👉💻 Inserisci di nuovo Gemini CLI per verificare che l'hook sia attivo:
cd ~/agentverse-developer
gemini
👉✨ Verifica che l'hook sia registrato:
/hooks
Dovresti visualizzare l'hook tool-logger elencato e attivato. Premi Esc per chiudere il menu di completamento automatico, se viene visualizzato.
👉✨ Ora attiva una chiamata allo strumento per testare la protezione:
What files are in the current directory?
L'agente chiamerà uno strumento per leggere la directory. Il reparto ha intercettato silenziosamente questa comunicazione. Vediamo le prove.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI, quindi esamina il log di controllo del reparto:
cat /tmp/tool_ward.log
Dovresti vedere una voce simile a questa:
15:42:07 ⚔️ [WARD] Tool invoked: list_directory
Ogni chiamata allo strumento effettuata dall'agente è stata intercettata, registrata e autorizzata dal tuo tutelato. In un ambiente aziendale reale, questo log potrebbe essere inviato a un sistema SIEM (Security Information and Event Management), attivando avvisi per l'utilizzo sospetto di strumenti o applicando audit trail di conformità.
8. Scatena Blade nell'Agentverse: integrazione continua 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 costante è solo un ricordo dimenticato. Per garantire che ogni versione futura del tuo agente rimanga pura, devi creare la prima fase del 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, impedendogli di corrompere l'armeria. Il tuo dominio è la fucina; la tua pipeline CI garantisce che solo artefatti perfetti e pronti all'uso escano dal tuo laboratorio.
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 la potenza e garantendone la stabilità contro il caos di Static.
In questo codice, imparerai a padroneggiare il tuo ruolo. Costruirai la parte CI del guanto di sfida. Costruirai la fucina automatizzata che testa il tuo agente e sigilla il risultato puro in un contenitore, preparandolo per la benedizione finale del Guardiano.
👀 Nota per gli sviluppatori: nella realtà, la gestione di workflow CI/CD complessi può essere semplificata con estensioni specializzate come Conductor (gemini extensions install https://github.com/gemini-cli-extensions/conductor). Conductor trasforma la Gemini CLI in un project manager che segue un protocollo rigoroso: Contesto → Specifica e piano → Implementazione. Include comandi personalizzati (/conductor:setup, /conductor:newTrack, /conductor:implement), modelli di flusso di lavoro per gestire l'intero ciclo di vita delle tue attività. Garantisce un ciclo coerente di contesto -> specifiche e piano -> implementazione. Questo è un esempio reale di come le estensioni e i comandi si combinano per fungere da project manager proattivo e standardizzare un intero ciclo di vita di sviluppo.
Ora utilizzerai Google Cloud Build per scrivere lo scorrimento 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 Gemini CLI.
cd ~/agentverse-developer/
clear
gemini
👉✨ Ora, invia il seguente comando a Gemini. Questo prompt funge da documento di progettazione, che descrive in dettaglio i passaggi del gauntlet che vuoi creare.
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.
👉💻 Premi Ctrl+C due volte per uscire da Gemini CLI.
👉💻 Nel terminale, esegui la pipeline dalla directory root 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="dev-tutorial-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.
PER CHI NON GIOCA
9. The Boss Fight
Le pergamene sono state lette, i rituali eseguiti, la sfida superata. L'agente non è un semplice 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 entrerai in 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 dello Spettro (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 che conduce al 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, devi raggiungere il Cerchio di Traslazione e lanciare l'incantesimo per andare in battaglia.
👉 Apri l'URL del Cerchio di Traslocazione nel browser per trovarti di fronte al portale scintillante della Fortezza Cremisi.
Per violare la fortezza, devi sintonizzare l'essenza della tua Lama Ombra con il portale.
- Nella pagina, trova il campo di immissione runico etichettato A2A Endpoint URL.
- 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. Davanti a te si materializza lo Spettro, un vortice di scariche sibilanti 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 logorante 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, frantumando 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 DANNO. Peggio ancora, lo Spettro si nutrirà della tua incertezza e il suo potere corrotto crescerà a ogni passo falso.
Ci siamo, campione. Il tuo codice è il tuo libro degli 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 costruito 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 che ti propone 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 tuoi 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 cui è stato eseguito il deployment del tuo Agentverse.
Elimina l'agente Shadowblade su Cloud Run e nel repository Artifact Registry
Questo comando rimuove l'agente Shadowblade di cui hai 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
Pulire file e directory locali (Cloud Shell)
Infine, cancella dall'ambiente Cloud Shell i repository clonati, le estensioni installate 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 -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.
Ora hai eliminato correttamente tutte le tracce del tuo percorso in Agentverse. Il tuo progetto è pulito e pronto per la prossima avventura.