1. Introduzione
In questo codelab creerai CloudCrush, un gioco arcade match 3, utilizzando Gemini 3 e Gemini CLI, il nostro agente di programmazione da riga di comando. Il gioco verrà scritto in Go e verrà eseguito il deployment su Google Cloud utilizzando Cloud Run.
L'obiettivo principale di questo codelab è sviluppare le competenze per orchestrare l'agente in modo che crei applicazioni per te anziché scrivere codice manualmente. Delegare tutte le attività di sviluppo a Gemini CLI, anche se non hai mai utilizzato queste tecnologie.
Questo codelab è rivolto a sviluppatori di livello intermedio che vogliono imparare i flussi di lavoro di programmazione agentica. La durata totale stimata per questo lab è di 60 minuti. Le risorse create in questo codelab utilizzano prezzi basati sul consumo.
In questo lab proverai a:
- Crea la logica di base del gioco abbinamento a tre utilizzando Go e il framework Ebitengine.
- Adattare il gioco per l'esecuzione su un browser web utilizzando WebAssembly (WASM)
- Esegui il deployment del gioco e della relativa API per i punteggi migliori in Cloud Run.
- Orchestrare estensioni e sub-agenti specializzati per test e revisione del codice
Prerequisiti
- Conoscenza di base dei linguaggi di programmazione
- Conoscenza di base dell'infrastruttura cloud
- Conoscenza di base della console Google Cloud
Obiettivi didattici
- Come lavorare con un agente di programmazione per creare applicazioni complesse
- Come lavorare con Gemini in un contesto multimodale
- Come eseguire il deployment di applicazioni nel cloud utilizzando Cloud Run
Che cosa ti serve
Questo workshop può essere svolto interamente sul cloud utilizzando Cloud Shell, ma se preferisci utilizzare la tua macchina locale, avrai bisogno di quanto segue:
- Gemini CLI. Scaricalo e installalo seguendo le istruzioni riportate in geminicli.com.
- La toolchain Go (versione 1.26 o successive). Scaricalo e installalo seguendo le istruzioni riportate in go.dev.
- L'interfaccia a riga di comando gcloud per interagire con Google Cloud. Scaricalo e installalo seguendo le istruzioni riportate nella documentazione di Google Cloud.
- Un account di fatturazione Google Cloud (per il deployment del gioco sul cloud)
Tecnologie chiave
Qui puoi trovare maggiori informazioni sulle tecnologie che utilizzeremo:
- Gemini CLI: l'agente di sviluppo
- Gemini 3: l'ultima versione del nostro modello linguistico di grandi dimensioni all'avanguardia
2. Configurazione dell'ambiente
Configurazione del progetto
Crea un progetto Google Cloud
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.
Avvia Cloud Shell
Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari.
- Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- Una volta connesso a Cloud Shell, verifica l'autenticazione:
gcloud auth list - Verifica che il progetto sia configurato:
gcloud config get project - Se il progetto non è impostato come previsto, impostalo:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Configurazione del progetto
Crea la directory del progetto
Innanzitutto, dobbiamo creare una nuova directory per il tuo progetto. Nel terminale, esegui questi comandi:
mkdir -p codelab-match3 && cd codelab-match3
Avvia Gemini CLI
Innanzitutto, verifichiamo che la CLI Gemini sia stata installata correttamente. Esegui questo comando nel terminale:
gemini --version
Il risultato dovrebbe essere simile a questo:
$ gemini --version 0.37.1
Ora avvia Gemini CLI con il comando gemini:
gemini
Dovresti visualizzare il prompt di Gemini CLI:
Se vedi il prompt di Gemini CLI, puoi procedere. In caso contrario, controlla di non aver saltato nessuno dei passaggi di configurazione precedenti.
Abilita Model Steering
La guida del modello è una funzionalità che ti consente di aggiungere un contesto aggiuntivo all'agente mentre sta ancora lavorando a una determinata attività. Puoi utilizzarlo per correggere la rotta dell'agente quando vedi che sta andando nella direzione sbagliata, per aggiungere informazioni chiarificatrici per migliorare la risposta dell'agente o per includere funzionalità minori che non sono state incluse nel prompt originale.
Per attivare la guida del modello, apri il menu delle impostazioni utilizzando il comando /settings e digita "steering" nella casella di ricerca. Quindi, imposta l'opzione Enable Model Steering su true.
Potrebbe essere necessario riavviare l'interfaccia a riga di comando per applicare la modifica (premendo il tasto "r").
Scaricare gli asset
Dobbiamo scaricare le immagini che verranno utilizzate nel gioco. I file sono archiviati su GitHub nel repository qui. Puoi scaricarli manualmente o chiedere a Gemini di farlo per te utilizzando il seguente prompt:
Create a folder named "assets" and download the images
background.png, gcp_sprites.png, gemini.png and logo.png,
from this GitHub repository to the "assets" folder:
https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/codelabs/gemini-cli/gemini-cli-match3-golang
4. Crea la partita con la modalità Piano e la guida del modello
Inizia creando la logica di base del gioco abbinamento a tre. Poiché si tratta di un'attività complessa, è consigliabile utilizzare Gemini CLI in modalità di pianificazione per coordinare lo sviluppo.
Attiva/disattiva la modalità di pianificazione con il comando slash /plan nel prompt di Gemini CLI:
/plan
Con la modalità di pianificazione attivata, copia e incolla il seguente prompt in Gemini CLI:
Build a Match-3 game called 'Cloud Crush' in Go using Ebitengine v2.
The entire game screen should have background.png as background.
The play area should be an 8x8 grid with white background.
On the right side of the play area include a side panel with UI elements
like player score and how to play instructions.
The side panel should have a solid background colour to help with readability of the UI.
Use standard GCP product logos (e.g. Compute Engine, Cloud Storage, BigQuery, etc.)
as icons. These icons are provided in the gcp_sprites.png file.
The icons are saved as 64x64 sprites but scale them as necessary
based on the screen resolution. Implement swapping, clearing 3+ gems, and gravity.
Use ebitengine native font rendering (size 48 for titles and size
24 for normal text) for all text and not the debug print.
The font should be monospaced (golang.org/x/image/font/gofont/gomono).
Keep the UI tidy and harmonic, e.g. centered text should always be
adjusted based on text length, not just guess based on estimates.
Gemini CLI potrebbe farti alcune domande di chiarimento prima di generare il piano.
Ad esempio, qui ti viene chiesto se preferisci un'applicazione con un solo file o più file:
Ecco una domanda sulle nostre preferenze per le animazioni:
L'ultima domanda riguarda l'incorporamento degli asset nel binario stesso con go:embed:
Dopo aver risposto a tutte le domande, hai la possibilità di rivederle un'ultima volta prima di premere Invio per inviarle.
Una volta completato il piano, ti verrà chiesto di esaminarlo:
Nella parte inferiore della casella di revisione puoi accettare il piano così com'è o aggiungere il nostro feedback.
Utilizza questa opportunità per aggiungere un nuovo requisito che non era stato incluso nel prompt originale:
Add a 60-seconds countdown timer and an in-memory high-score tracker
to enhance the arcade game experience.
Combos should give a score bonus of 10% per combo number.
Ti verrà chiesto un'ultima volta di confermare il piano di implementazione:
Premi Invio per far iniziare il lavoro all'agente. L'agente uscirà dalla modalità di pianificazione e inizierà a scrivere il codice.
A questo punto, normalmente dovremmo attendere il completamento o interrompere l'operazione con il tasto ESC se volessimo apportare modifiche all'implementazione, ma poiché abbiamo attivato la guida del modello, possiamo mettere in coda le istruzioni per correggere la rotta del modello.
Mentre l'agente è al lavoro, incolla quanto segue nella finestra di chat dell'agente per dimostrare la funzionalità di "orientamento del modello", che mostra come puoi mettere in coda i comandi per modificare l'implementazione:
Update the implementation to include: 'Q' to quit, 'F' for full-screen
and 'A' for Accessibility Mode: swap GCP logos for high-contrast coloured blocks.
Also enable Arrow Keys to move the selection cursor and Space to select the gem to
swap (space is pressed once to select, then arrow key immediately makes
the move - no need to press space again).
Use a golden square (4 px border, transparent fill) with a simple animation
to highlight where the cursor is at the moment.
Vedrai che il prompt è in coda come "suggerimento di orientamento":
Accetta il piano e guarda l'agente implementare tutti i tuoi requisiti.
Quando l'agente ha terminato l'implementazione, esegui go run main.go nella cartella del progetto per visualizzare la demo della versione desktop. Non devi uscire dalla CLI Gemini per eseguire questo comando. Digita ! (punto esclamativo) per accedere alla modalità shell ed eseguire il comando da lì:
Il vantaggio dell'esecuzione dalla modalità shell è che eventuali problemi che potrebbero verificarsi vengono acquisiti immediatamente nel contesto dell'agente. Ad esempio, in questo caso l'agente ha dimenticato di scaricare alcune dipendenze:
Puoi uscire dalla modalità shell premendo il tasto Esc e poi chiedere all'agente di esaminare e correggere l'errore:
Il risultato positivo dovrebbe essere simile a questo:
Prova a giocare e a perfezionare i parametri del gioco finché non sei soddisfatto dell'esperienza (ad esempio, rendendo l'animazione più veloce o più lenta, regolando la risposta ai comandi e così via).
5. Adattare il gioco per l'esecuzione su un browser web
Il gioco Ebitengine che hai appena creato è un'applicazione desktop. Per consentirne l'esecuzione sul web, possiamo convertirlo in WebAssembly.
Utilizza il seguente prompt per guidare l'agente:
We need to enable this game to run on a web browser. Compile the game to WASM
and create a Go web server to serve the compiled WASM and the assets.
Una volta completata l'attività, puoi chiedere all'agente di eseguire il server di gioco in background.
Puoi gestire i processi in background utilizzando la combinazione di tasti Ctrl+B:
Premi di nuovo Ctrl+B per chiudere questa finestra.
Ora apri http://localhost:8080 nel browser per vedere il gioco in esecuzione sul web:
Ora che è in esecuzione sul web, è il momento di dargli una rifinitura finale prima di eseguirne il deployment nel cloud.
6. Creare la schermata del titolo e la classifica
Il gioco funziona, ma mancano alcune funzionalità chiave per un'esperienza arcade adeguata. Per prima cosa, aggiungiamo una schermata del titolo e poi una classifica per poter competere con i tuoi amici.
Risolvi entrambi i problemi con il seguente prompt:
Create a title screen that displays the game logo (logo.png) over the cloud background.
The logo should be centered and occupy no more than 75% of the screen area.
The title screen should display "Press ENTER to play" (black/bold) right below the logo,
with every letter animated in a slow wavy (cosine) pattern.
Once the player presses ENTER, it should be prompted to add their name, which
will then be recorded to populate the leaderboard at the end of the round.
Once the game is over, play the animated leaderboard with the top 10 highest scores.
The animated leaderboard should render entries one by one up to 10 entries,
using a fade in effect just like old school arcade games. The leaderboard
should fade out to the title screen after 15 seconds.
Please note that name entry should be processed independently of the play state
key handlers (e.g. pressing A during name entry should not toggle accessibility mode).
Ecco un esempio della schermata del titolo:
Inizia ad avere un aspetto un po' più professionale. 🙂
7. Esegui il deployment del gioco in Cloud Run
È finalmente arrivato il momento di condividere la nostra creazione con il mondo. Esegui il deployment del gioco in Google Cloud Run per potervi accedere da qualsiasi luogo.
Use the gcloud CLI to provision and deploy the Go web server and its assets to
Google Cloud Run. Provide the live URL when complete.
Poiché il gioco è ora disponibile nel cloud, sarebbe un'occasione mancata non consentirne l'esecuzione sui dispositivi mobili. Puoi farlo con il seguente prompt:
Now enable this game to run on mobile devices. You need to update the input
system to handle "taps" as well as key presses and clicks. Since mobile devices
most likely won't have a keyboard, add a button to generate a random name and
a confirmation button to the name entry.
Also generate a QR code for the CloudRun link and display it on the screen so
that people can scan it to access the mobile version and compete against their
friends for the high score.
Esegui di nuovo il gioco sul browser. Prova ad accedere al gioco anche da un dispositivo mobile utilizzando il codice QR.
8. Utilizzare l'agente del browser per testare il gioco
In Gemini CLI, un sub-agente è una persona isolata con un contesto nuovo, perfetto per attività di lunga durata e/o di alta precisione in cui non vuoi che il contesto attuale influenzi i risultati.
I giochi sono naturalmente difficili da testare con strumenti di test convenzionali (ad es. test delle unità e di integrazione), ma possiamo utilizzare l'agente del browser per eseguire alcuni test per nostro conto. L'agente del browser è in grado di avviare il proprio browser Chrome e navigare nelle schermate del gioco emettendo comandi DOM. Ha anche la funzionalità di fare screenshot, che possiamo utilizzare per documentare il test e restituirli all'agente per apportare piccole modifiche all'interfaccia utente in un secondo momento.
L'agente browser è attualmente sperimentale, quindi dobbiamo prima abilitarlo. Fornisci questo prompt a Gemini CLI per abilitare l'agente a livello di progetto.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Per applicare questa modifica, devi riavviare l'agente. Salva la conversazione corrente con il comando /chat save:
Esci da Gemini CLI premendo Ctrl+D due volte e riavviala. Ripristina la conversazione con /chat resume cloud-crush.
Ora dovresti avere accesso all'agente del browser. Quando vuoi delegare un'attività all'agente del browser, puoi menzionarlo con @browser_agent:
Ora utilizza l'agente del browser per eseguire una valutazione del gioco di cui è stato eseguito il deployment:
@browser_agent perform an end-to-end test of the Cloud Run deployment URL.
Navigate the homepage, start a game, submit a score, and verify the new score
appears correctly on the leaderboard. Take screenshots to show each step of the
investigation and save to ./screenshots.
Dovresti visualizzare la schermata di conferma:
Dopo aver dato il consenso all'agente e agli strumenti richiesti, dovrebbe aprirsi una nuova finestra del browser Chrome. Questo è il browser controllato dall'agente. Il suggerimento visivo sarà il bordo blu sullo schermo e il messaggio in basso "Gemini CLI controlla questo browser":
Al termine, verrà visualizzato un messaggio simile a questo:
Ecco alcuni screenshot acquisiti dall'agente del browser:
title_screen.png:
game_board.png:
Ora è un buon momento per utilizzare una delle immagini scattate dall'agente per ottimizzare la UI del gioco. Ad esempio, puoi dire:
Analyse the screenshot @screenshots/game_board.png and adjust the side panel to
have better contrast and be more harmonic with the rest of UI elements. Focus
on readability and color theory to achieve the best possible visuals.
9. Crea un agente personalizzato per proteggere la partita
Un problema comune con le applicazioni "vibe-coded" è come mantenere alta qualità e best practice sia dal punto di vista della codifica che della sicurezza. Anche se puoi provare a migliorare i prompt per renderli molto rigorosi su entrambi gli aspetti, più aggiungi a un prompt, meno l'agente sarà concentrato, il che spesso si traduce in risultati non ottimali. Per questo tipo di scenario, l'utilizzo di subagenti è ideale, in quanto operano in un contesto separato dall'agente principale e possono concentrarsi con precisione sull'attività che gli viene assegnata. Creiamo un agente personalizzato per eseguire un audit di sicurezza su questo codice e assicurarci di non divulgare credenziali o esporci a rischi inutili durante il deployment di questo gioco su Cloud Run.
Create a new custom agent in .gemini/agents/security_auditor.md using the following content:
---
name: security_auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
- read_file
- grep_search
model: gemini-3-flash-preview
temperature: 0.2
max_turns: 10
---
You are a ruthless Security Auditor. Your job is to analyze code for potential
vulnerabilities.
Focus on:
1. SQL Injection
2. XSS (Cross-Site Scripting)
3. Hardcoded credentials
4. Unsafe file operations
When you find a vulnerability, explain it clearly and suggest a fix. Do not fix
it yourself; just report it.
Per applicare la modifica, dovrai riavviare la CLI. Salva la sessione di chat con /chat save e riprendila con /chat resume come abbiamo fatto in precedenza.
Quando la CLI riprende, rileva automaticamente il nuovo agente all'avvio:
Fai clic su Acknowledge and Enable e poi chiedi all'agente di eseguire un controllo di sicurezza sul codice del gioco con il seguente prompt:
@security-auditor please run a security audit on this code and cloud run
deployment to make sure it is safe against common attack patterns and that it is
not leaking any credentials
Il risultato dovrebbe essere simile a questo:
Al termine dell'audit, fornirà dei consigli. In questo esempio, ha trovato alcuni aspetti importanti da correggere:
Se hai riscontrato problemi, chiedi a Gemini CLI di risolverli per te. 🙂
10. Conclusione
Complimenti! Hai utilizzato correttamente Gemini CLI per creare, eseguire il deployment, testare e controllare un gioco arcade, dimostrando flussi di lavoro avanzati basati su agenti, dall'impalcatura iniziale al deployment.
Elimina
Se non prevedi di tornare a questo codelab in un secondo momento, è consigliabile eliminare le risorse create durante il codelab.
- Elimina il servizio Cloud Run:
Chiedi a Gemini CLI di eliminarlo per te:
I'm finished with this project. Delete the cloud run deployment.
- Elimina la directory del progetto:
cd .. && rm -rf codelab-match3
In alternativa, puoi eliminare l'intero progetto Google Cloud se è stato creato esclusivamente per questo codelab.
Passaggi successivi
Puoi continuare il tuo percorso di apprendimento esplorando altri codelab in questa piattaforma o migliorando Cloud Crush in autonomia.
Ecco alcuni suggerimenti per migliorare il gioco:
- Aggiungi una gemma speciale "Gemini" (utilizzando gemini.png) che viene visualizzata quando vengono abbinate 4 o più gemme. Se abbini tre o più gemme Gemini, il giocatore riceve tempo extra.
- Aggiungi musica. Puoi generare musica utilizzando Lyria 3 nella home page di Gemini.
- Aggiungere effetti sonori
- Aggiungere altre modalità di gioco
Buona programmazione!