1. Introducción
En este codelab, compilarás CloudCrush, un juego de arcade de combinar 3, con Gemini 3 y Gemini CLI, nuestro agente de programación de línea de comandos. El juego se escribirá en Go y se implementará en Google Cloud con Cloud Run.
El objetivo principal de este codelab es desarrollar las habilidades para orquestar el agente y que cree aplicaciones por ti en lugar de escribir código de forma manual. Delegarás todas las tareas de desarrollo a Gemini CLI, incluso si no usaste estas tecnologías antes.
Este codelab es para desarrolladores intermedios que desean aprender flujos de trabajo de programación con agentes. La duración total estimada de este lab es de 60 minutos. Los recursos creados en este codelab usan precios basados en el consumo.
Actividades
- Compila la lógica principal del juego de Match-3 con Go y el framework de Ebitengine.
- Adapta el juego para que se ejecute en un navegador web con WebAssembly (WASM)
- Implementa el juego y su API de puntuación alta en Cloud Run.
- Orquesta subagentes y extensiones especializados para pruebas y revisión de código
Requisitos previos
- Conocimientos básicos de lenguajes de programación
- Conocimientos básicos de la infraestructura de nube
- Conocimientos básicos de la consola de Google Cloud
Qué aprenderás
- Cómo trabajar con un agente de programación para compilar aplicaciones complejas
- Cómo trabajar con Gemini en un contexto multimodal
- Cómo implementar aplicaciones en la nube con Cloud Run
Requisitos
Este taller se puede realizar por completo en la nube con Cloud Shell, pero, si prefieres usar tu máquina local, necesitarás lo siguiente:
- Gemini CLI. Descarga e instala siguiendo las instrucciones en geminicli.com
- La cadena de herramientas de Go (versión 1.26 o posterior) Descárgalo e instálalo siguiendo las instrucciones en go.dev.
- La CLI de gcloud para interactuar con Google Cloud Descarga e instala el SDK siguiendo las instrucciones de la documentación de Google Cloud.
- Una cuenta de facturación de Google Cloud (para implementar el juego en la nube)
Tecnologías clave
Aquí puedes encontrar más información sobre las tecnologías que utilizaremos:
- Gemini CLI: El agente de desarrollo
- Gemini 3: La versión más reciente de nuestro modelo de lenguaje grande de vanguardia
2. Configuración del entorno
Configura el proyecto
Crea un proyecto de Google Cloud
- En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
- Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.
Inicie Cloud Shell
Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias.
- Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
- Una vez que te conectes a Cloud Shell, verifica tu autenticación:
gcloud auth list - Confirma que tu proyecto esté configurado:
gcloud config get project - Si tu proyecto no está configurado como se esperaba, configúralo:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Configuración del proyecto
Crea el directorio del proyecto
Primero, debemos crear un directorio nuevo para tu proyecto. En tu terminal, ejecuta los siguientes comandos:
mkdir -p codelab-match3 && cd codelab-match3
Iniciar Gemini CLI
Primero, verifiquemos que Gemini CLI se haya instalado correctamente. Ejecuta el siguiente comando en tu terminal:
gemini --version
Deberías ver algo como esto:
$ gemini --version 0.37.1
Ahora, inicia Gemini CLI con el comando gemini:
gemini
Deberías ver la instrucción de Gemini CLI:
Si ves el mensaje de Gemini CLI, todo está listo. De lo contrario, verifica si te salteaste alguno de los pasos de configuración anteriores.
Habilita la dirección del modelo
La dirección del modelo es una función que te permite agregar contexto adicional al agente mientras sigue trabajando en una tarea determinada. Puedes usarlo para corregir el rumbo del agente cuando veas que va en la dirección incorrecta, agregar información aclaratoria para mejorar la respuesta del agente o incluir funciones secundarias que se omitieron en la instrucción original.
Para habilitar la dirección del modelo, abre el menú de configuración con el comando /settings y escribe "dirección" en el cuadro de búsqueda. Luego, establece la opción Enable Model Steering como verdadera.
Es posible que debas reiniciar la CLI para que el cambio se aplique (presiona la tecla "r").
Descarga los recursos
Necesitamos descargar las imágenes que se usarán en el juego. Los archivos se almacenan en GitHub en el repositorio aquí. Puedes descargarlos manualmente o pedirle a Gemini que lo haga por ti con la siguiente instrucción:
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 el juego con el modo de planificación y la dirección del modelo
Comienza por crear la lógica principal del juego de Match-3. Dado que esta es una tarea compleja, lo mejor es usar Gemini CLI en modo de planificación para coordinar el desarrollo.
Activa o desactiva el modo de planificación con el comando de barra /plan en la instrucción de Gemini CLI:
/plan
Con el modo de planificación habilitado, copia y pega la siguiente instrucción en 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.
Es posible que Gemini CLI te haga algunas preguntas para aclarar tus dudas antes de generar el plan.
Por ejemplo, aquí se te pregunta si prefieres una aplicación de un solo archivo o de varios archivos:
Y aquí pregunta sobre nuestras preferencias de animaciones:
La última pregunta es sobre la incorporación de los recursos en el propio objeto binario con go:embed:
Después de responder todas las preguntas, tienes la opción de revisarlas por última vez antes de presionar Intro para enviar el examen.
Una vez que el plan esté listo, se te pedirá que lo revises:
En la parte inferior del cuadro de revisión, tienes la opción de aceptar el plan tal como está o agregar nuestros comentarios.
Aprovecha esta oportunidad para agregar un requisito nuevo que se omitió en la instrucción original:
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.
Se te pedirá una última vez que confirmes el plan de implementación:
Presiona Intro para que el agente comience el trabajo. El agente saldrá del modo de planificación y comenzará a escribir el código.
En este punto, normalmente tendríamos que esperar a que termine o interrumpirlo con la tecla ESC si quisiéramos hacer cambios en la implementación, pero, como tenemos habilitada la dirección del modelo, podemos poner en cola instrucciones para corregir el rumbo del modelo.
Mientras el agente trabaja, pega lo siguiente en la ventana de chat del agente para demostrar la capacidad de "dirección del modelo" y mostrar cómo puedes poner en cola comandos para cambiar la implementación:
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.
Verás que esta instrucción se pone en cola como una "pista de dirección":
Acepta el plan y mira cómo el agente implementa todos tus requisitos.
Cuando el agente termine con la implementación, ejecuta go run main.go en la carpeta del proyecto para mostrar la versión para computadoras. No es necesario que salgas de Gemini CLI para ejecutar este comando. Escribe ! (signo de exclamación) para ingresar al modo de shell y ejecutar el comando desde allí:
La ventaja de ejecutar desde el modo de shell es que cualquier problema que pueda ocurrir se captura de inmediato en el contexto del agente. Por ejemplo, en este caso, el agente olvidó descargar algunas dependencias:
Para salir del modo de shell, presiona la tecla Escape y, luego, pídele al agente que inspeccione y corrija el error:
El resultado correcto debería ser similar al siguiente:
Intenta jugar y ajustar los parámetros del juego hasta que estés conforme con la experiencia (p.ej., acelerar o ralentizar la animación, ajustar la forma en que responde a los comandos, etcétera).
5. Adaptar el juego para que se ejecute en un navegador web
El juego de Ebitengine que acabas de crear es una aplicación para computadoras. Para que se ejecute en la Web, podemos convertirlo a WebAssembly.
Usa la siguiente instrucción para guiar al 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 vez que el agente complete la tarea, puedes indicarle que ejecute el servidor del juego en segundo plano.
Puedes administrar los procesos en segundo plano con la combinación de teclas Ctrl + B:
Presiona Ctrl + B de nuevo para cerrar esta ventana.
Ahora, abre http://localhost:8080 en tu navegador para ver el juego en la Web:
Ahora que lo tienes en la Web, es hora de darle un toque final antes de implementarlo en la nube.
6. Crea la pantalla de título y la tabla de clasificación
El juego funciona, pero le faltan algunas funciones clave para brindar una experiencia de arcade adecuada. Primero, agreguemos una pantalla de título y, luego, un ranking para que puedas competir con tus amigos.
Corrige ambos problemas con la siguiente instrucción:
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).
Este es un ejemplo de la pantalla de título:
¡Ya se ve un poco más profesional! 🙂
7. Implementa el juego en Cloud Run
Por fin llegó el momento de compartir nuestra creación con el mundo. Implementa el juego en Google Cloud Run para poder acceder a él desde cualquier lugar.
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.
Dado que el juego ahora está disponible en la nube, sería una oportunidad perdida no permitir que se ejecute en dispositivos móviles. Puedes hacerlo con la siguiente instrucción:
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.
Vuelve a ejecutar el juego en tu navegador. Intenta acceder al juego desde un dispositivo móvil también con el código QR.
8. Usa el agente del navegador para probar el juego
En Gemini CLI, un subagente es un arquetipo aislado con un contexto nuevo, ideal para tareas de larga duración o de alta precisión en las que no quieres que el contexto actual influya en los resultados.
Los juegos son difíciles de probar con herramientas de prueba convencionales (p.ej., pruebas de unidades y de integración), pero podemos usar el agente del navegador para que realice algunas pruebas por nosotros. El agente del navegador puede iniciar su propio navegador Chrome y navegar por las pantallas del juego con comandos del DOM. También tiene la capacidad de tomar capturas de pantalla, que podemos usar para documentar la prueba y también devolvérselas al agente para que realice ajustes menores en la IU más adelante.
El agente del navegador es experimental en este momento, por lo que primero debemos habilitarlo. Dale esta instrucción a Gemini CLI para habilitar el agente a nivel del proyecto.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Debes reiniciar el agente para que se aplique este cambio. Guarda la conversación actual con el comando /chat save:
Sal de Gemini CLI presionando Ctrl+D dos veces y vuelve a iniciarla. Restablece la conversación con /chat resume cloud-crush.
Ahora deberías tener acceso al agente del navegador. Cuando quieras delegar una tarea al agente del navegador, puedes mencionarlo con @browser_agent:
Ahora usa el agente del navegador para evaluar el juego implementado:
@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.
Deberías ver la pantalla de confirmación:
Una vez que le des tu consentimiento al agente y a las herramientas necesarias, se abrirá una nueva ventana del navegador Chrome. Este es el navegador que controla el agente. La sugerencia visual será el borde azul en la pantalla y el mensaje en la parte inferior que dice "Gemini CLI is controlling this browser":
Cuando termine, se mostrará un mensaje como este:
Estas son algunas de las capturas de pantalla que tomó el agente del navegador:
title_screen.png:
game_board.png:
Ahora es un buen momento para usar una de las imágenes que tomó el agente para optimizar la IU del juego. Por ejemplo, puedes decir:
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 personalizado para proteger el juego
Una preocupación común con las aplicaciones "vibe-coded" es cómo mantener la alta calidad y las prácticas recomendadas desde las perspectivas de codificación y seguridad. Si bien puedes intentar mejorar tus instrucciones para que sean muy rigurosas en ambos aspectos, cuanto más agregues a una instrucción, menos enfocado estará el agente, lo que a menudo genera resultados subóptimos. Para este tipo de situaciones, lo ideal es usar subagentes, ya que operan en un contexto independiente del agente principal y pueden enfocarse con precisión en la tarea que les asignes. Creemos un agente personalizado para realizar una auditoría de seguridad en este código y asegurarnos de que no se filtre ninguna credencial ni nos expongamos a riesgos innecesarios mientras implementamos este juego en 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.
Deberás reiniciar la CLI para que se aplique el cambio. Guarda la sesión de chat con /chat save y reanúdala con /chat resume, como lo hicimos antes.
Cuando se reanude la CLI, detectará automáticamente el nuevo agente en el inicio:
Haz clic en Acknowledge and Enable y, luego, pídele al agente que realice una verificación de seguridad en el código del juego con la siguiente instrucción:
@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
Deberías ver algo como esto:
Una vez que complete la auditoría, te hará recomendaciones. En este ejemplo, en realidad, se encontraron algunos aspectos importantes que se debían corregir:
Si encuentras algún problema, pídele a Gemini CLI que lo solucione. 🙂
10. Conclusión
¡Felicitaciones! Usaste correctamente Gemini CLI para compilar, implementar, probar y auditar un juego de arcade, lo que demuestra flujos de trabajo avanzados basados en agentes, desde el andamiaje inicial hasta la implementación.
Limpieza
Si no planeas volver a este codelab más adelante, lo mejor es que borres los recursos que creaste durante este codelab.
- Borra el servicio de Cloud Run:
Pídele a Gemini CLI que lo borre por ti:
I'm finished with this project. Delete the cloud run deployment.
- Borra el directorio del proyecto:
cd .. && rm -rf codelab-match3
Como alternativa, puedes borrar todo el proyecto de Google Cloud si se creó solo para este codelab.
Próximos pasos
Puedes continuar tu recorrido de aprendizaje explorando otros codelabs en esta plataforma o mejorando Cloud Crush por tu cuenta.
Estas son algunas sugerencias para mejorar el juego:
- Agrega una Gem especial de "Gemini" (con gemini.png) que aparezca cuando se junten 4 o más Gems. Si juntas 3 o más gemas de Gemini, obtendrás tiempo adicional.
- Agregar música Puedes generar música con Lyria 3 en la página principal de Gemini.
- Cómo agregar efectos de sonido
- Agregar otros modos de juego
¡Suerte con la programación!