1. Introdução
Neste codelab, você vai criar o CloudCrush, um jogo de arcade de combinar 3, usando o Gemini 3 e a CLI do Gemini, nosso agente de programação de linha de comando. O jogo será escrito em Go e implantado no Google Cloud usando o Cloud Run.
O principal objetivo deste codelab é desenvolver as habilidades para orquestrar o agente e criar aplicativos para você em vez de escrever código manualmente. Você vai delegar todas as tarefas de desenvolvimento à CLI do Gemini, mesmo que nunca tenha usado essas tecnologias antes.
Este codelab é para desenvolvedores de nível intermediário que querem aprender fluxos de trabalho de programação com agentes. A duração total estimada deste laboratório é de 60 minutos. Os recursos criados neste codelab usam preços baseados no consumo.
Atividades deste laboratório
- Crie a lógica principal do jogo de combinar 3 usando Go e o framework Ebitengine.
- Adaptar o jogo para ser executado em um navegador da Web usando o WebAssembly (WASM)
- Implante o jogo e a API de pontuação máxima no Cloud Run.
- Orquestrar subagentes e extensões especializados para testes e revisão de código
Pré-requisitos
- Conhecimento básico de linguagens de programação
- Conhecimento básico de infraestrutura em nuvem
- Conhecimento básico do console do Google Cloud
O que você vai aprender
- Como trabalhar com um agente de programação para criar aplicativos complexos
- Como trabalhar com o Gemini em um contexto multimodal
- Como implantar aplicativos na nuvem usando o Cloud Run
O que é necessário
Este workshop pode ser feito totalmente na nuvem usando o Cloud Shell, mas, se preferir usar sua máquina local, você vai precisar do seguinte:
- CLI do Gemini. Faça o download e instale seguindo as instruções em geminicli.com
- A cadeia de ferramentas Go (versão 1.26 ou mais recente). Faça o download e a instalação seguindo as instruções em go.dev.
- A CLI gcloud para interagir com o Google Cloud. Faça o download e a instalação seguindo as instruções na documentação do Google Cloud.
- Uma conta de faturamento do Google Cloud (para implantar o jogo na nuvem)
Principais tecnologias
Confira mais informações sobre as tecnologias que vamos usar:
- CLI do Gemini: o agente de desenvolvimento
- Gemini 3: a versão mais recente do nosso modelo de linguagem grande de ponta
2. Configuração do ambiente
Configurar o projeto
Criar um projeto do Google Cloud
- No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
Iniciar o Cloud Shell
O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.
- Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique sua autenticação:
gcloud auth list - Confirme se o projeto está configurado:
gcloud config get project - Se o projeto não estiver definido como esperado, faça o seguinte:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Configuração do projeto
Criar o diretório do projeto
Primeiro, precisamos criar um novo diretório para seu projeto. No terminal, execute os seguintes comandos:
mkdir -p codelab-match3 && cd codelab-match3
Iniciar a CLI do Gemini
Primeiro, vamos verificar se a CLI do Gemini foi instalada corretamente. Execute no terminal:
gemini --version
Você verá algo como:
$ gemini --version 0.37.1
Agora inicie a CLI do Gemini com o comando gemini:
gemini
O comando da CLI do Gemini vai aparecer:
Se você estiver vendo o prompt da CLI do Gemini, tudo está certo. Caso contrário, verifique se você perdeu alguma das etapas de configuração anteriores.
Ativar o Model Steering
O direcionamento de modelo é um recurso que permite adicionar mais contexto ao agente enquanto ele ainda está trabalhando em uma determinada tarefa. Você pode usar esse recurso para corrigir o curso do agente quando ele estiver indo na direção errada, adicionar informações esclarecedoras para melhorar a resposta do agente ou incluir recursos secundários que não foram incluídos no comando original.
Para ativar o direcionamento de modelo, abra o menu de configurações usando o comando /settings e digite "direcionamento" na caixa de pesquisa. Em seguida, defina a opção "Ativar direcionamento de modelo" como "true".
Talvez seja necessário reiniciar a CLI para que a mudança entre em vigor (pressionando a tecla "r").
Baixar os recursos
Precisamos baixar as imagens que serão usadas no jogo. Os arquivos estão armazenados no GitHub no repositório aqui. Você pode fazer o download manualmente ou pedir ao Gemini para fazer isso usando o seguinte comando:
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. Criar o jogo com o modo de planejamento e o direcionamento de modelo
Comece criando a lógica principal do jogo de combinar três. Como essa é uma tarefa complexa, é melhor usar a CLI do Gemini no modo de planejamento para orquestrar o desenvolvimento.
Ative o modo de planejamento com o comando de barra /plan no comando da CLI do Gemini:
/plan
Com o modo de planejamento ativado, copie e cole o seguinte comando na CLI do Gemini:
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.
A CLI do Gemini pode fazer algumas perguntas de esclarecimento antes de gerar o plano.
Por exemplo, aqui ele pergunta se você prefere um único arquivo ou um aplicativo com vários arquivos:
E aqui ele pergunta sobre nossas preferências de animações:
A última pergunta é sobre a incorporação dos recursos no próprio binário com go:embed:
Depois de responder a todas as perguntas, você tem a opção de revisar pela última vez antes de pressionar "Enter" para enviar.
Quando o plano estiver pronto, você vai precisar revisá-lo:
Na parte de baixo da caixa de revisão, você tem as opções de aceitar o plano como está ou adicionar seu feedback.
Use essa oportunidade para adicionar um novo requisito que não foi incluído no comando 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.
Será necessário confirmar o plano de implementação mais uma vez:
Pressione "Enter" para que o agente comece o trabalho. O agente vai sair do modo de planejamento e começar a escrever o código.
Neste ponto, normalmente precisaríamos esperar a conclusão ou interromper com a tecla ESC se quiséssemos fazer mudanças na implementação. No entanto, como temos o direcionamento de modelo ativado, podemos enfileirar instruções para corrigir o curso do modelo.
Enquanto o agente está trabalhando, cole o seguinte na janela de chat dele para demonstrar a capacidade de "direcionamento do modelo", mostrando como você pode enfileirar comandos para mudar a implementação:
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.
Você vai ver que essa solicitação está na fila como uma "dica de direcionamento":
Aceite o plano e assista o agente implementar todos os seus requisitos.
Quando o agente terminar a implementação, execute go run main.go na pasta do projeto para demonstrar a versão para computador. Não é necessário sair da CLI do Gemini para executar esse comando. Digite ! (ponto de exclamação) para entrar no modo shell e executar o comando de lá:
A vantagem de executar no modo shell é que todos os problemas que podem ocorrer são capturados imediatamente no contexto do agente. Por exemplo, neste caso, o agente esqueceu de baixar algumas dependências:
Para sair do modo shell, pressione a tecla "Esc" e peça ao agente para inspecionar e corrigir o erro:
O resultado bem-sucedido será semelhante a este:
Teste o jogo e ajuste os parâmetros até ficar satisfeito com a experiência (por exemplo, acelerando ou diminuindo a animação, ajustando a resposta aos comandos etc.).
5. Adaptar o jogo para ser executado em um navegador da Web
O jogo Ebitengine que você acabou de criar é um aplicativo para computador. Para que ele possa ser executado na Web, podemos convertê-lo em WebAssembly.
Use o comando a seguir para orientar o 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.
Depois que o agente concluir a tarefa, você poderá instruí-lo a executar o servidor de jogos em segundo plano.
É possível gerenciar processos em segundo plano usando a combinação de teclas Ctrl+B:
Pressione Ctrl+B novamente para fechar esta janela.
Agora abra http://localhost:8080 no navegador para ver o jogo em execução na Web:
Agora que ele está em execução na Web, é hora de dar um toque final antes de implantá-lo na nuvem.
6. Criar a tela de título e o placar
O jogo funciona, mas faltam alguns recursos importantes para uma experiência de arcade adequada. Primeiro, vamos adicionar uma tela de título e depois um placar para que você possa competir com seus amigos.
Corrija os dois problemas com o seguinte comando:
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).
Confira um exemplo da tela de título:
Ele está começando a ficar um pouco mais profissional. 🙂
7. Implantar o jogo no Cloud Run
Chegou a hora de compartilhar nossa criação com o mundo! Implante o jogo no Google Cloud Run para poder acessá-lo de qualquer 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.
Como o jogo agora está disponível na nuvem, seria uma oportunidade perdida não permitir que ele fosse executado em dispositivos móveis. Você pode fazer isso com o seguinte comando:
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.
Execute o jogo novamente no navegador. Tente acessar o jogo também em um dispositivo móvel usando o QR code.
8. Usar o agente do navegador para testar o jogo
Na CLI do Gemini, um subagente é uma persona isolada com um contexto novo, perfeita para tarefas de longa duração e/ou de alta precisão em que você não quer que o contexto atual influencie os resultados.
É difícil testar jogos com ferramentas convencionais (por exemplo, testes de unidade e integração), mas podemos usar o agente do navegador para fazer alguns testes. O agente do navegador é capaz de iniciar o próprio navegador Chrome e navegar pelas telas do jogo emitindo comandos DOM. Ele também pode fazer capturas de tela, que podem ser usadas para documentar o teste e enviadas de volta ao agente para fazer pequenos ajustes na interface depois.
O agente do navegador ainda está em fase experimental. Por isso, precisamos ativá-lo primeiro. Dê esse comando à CLI do Gemini para ativar o agente no nível do projeto.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
É necessário reiniciar o agente para que essa mudança entre em vigor. Salve a conversa atual com o comando /chat save:
Saia da CLI do Gemini pressionando Ctrl+D duas vezes e inicie de novo. Restaure a conversa com /chat resume cloud-crush.
Agora você tem acesso ao agente do navegador. Sempre que quiser delegar uma tarefa ao agente do navegador, mencione-o com @browser_agent:
Agora use o agente do navegador para fazer uma avaliação do nosso jogo implantado:
@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.
A tela de confirmação vai aparecer:
Depois que você der consentimento ao agente e às ferramentas necessárias, uma nova janela do navegador Chrome será aberta. Este é o navegador controlado pelo agente. A dica visual será a borda azul na tela e a mensagem na parte de baixo dizendo "A CLI do Gemini está controlando este navegador":
Quando terminar, uma mensagem como esta será exibida:
Confira algumas capturas de tela feitas pelo agente do navegador:
title_screen.png:
game_board.png:
Agora é uma boa hora para usar uma das imagens tiradas pelo agente e otimizar a interface do jogo. Por exemplo, você pode dizer:
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. Criar um agente personalizado para proteger o jogo
Uma preocupação comum com aplicativos "vibe-coded" é como manter a alta qualidade e as práticas recomendadas do ponto de vista de programação e segurança. Embora você possa tentar melhorar seus comandos para serem muito rigorosos nesses dois aspectos, quanto mais você adiciona a um comando, menos focado o agente fica, o que geralmente resulta em resultados abaixo do ideal. Para esse tipo de cenário, o uso de subagentes é ideal, já que eles operam em um contexto separado do agente principal e podem se concentrar na tarefa que você atribui a eles. Vamos criar um agente personalizado para fazer uma auditoria de segurança nesse código e garantir que não estamos vazando credenciais nem nos expondo a riscos desnecessários ao implantar esse jogo no 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.
É necessário reiniciar a CLI para que a mudança entre em vigor. Salve a sessão de chat com /chat save e retome com /chat resume, como fizemos antes.
Quando a CLI for retomada, ela vai detectar automaticamente o novo agente na inicialização:
Clique em Acknowledge and Enable e peça ao agente para fazer uma verificação de segurança no código do jogo com o seguinte comando:
@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
Você verá algo como:
Depois de concluir a auditoria, ele vai fazer recomendações. Neste exemplo, ele encontrou algumas coisas importantes para corrigir:
Se você tiver alguma descoberta, peça ao Gemini CLI para corrigi-la para você! 🙂
10. Conclusão
Parabéns! Você usou a CLI do Gemini para criar, implantar, testar e auditar um jogo de arcade, demonstrando fluxos de trabalho avançados com agentes, desde o scaffolding inicial até a implantação.
Limpeza
Se você não planeja voltar a este codelab mais tarde, é melhor excluir os recursos criados durante ele.
- Exclua o serviço do Cloud Run:
Peça ao Gemini CLI para excluir para você:
I'm finished with this project. Delete the cloud run deployment.
- Exclua o diretório do projeto:
cd .. && rm -rf codelab-match3
Como alternativa, é possível excluir todo o projeto do Google Cloud se ele foi criado apenas para este codelab.
Próximas etapas
Você pode continuar sua jornada de aprendizado explorando outros codelabs nesta plataforma ou melhorando o Cloud Crush por conta própria.
Algumas sugestões para melhorar o jogo:
- Adicione um Gem especial do Gemini (usando gemini.png) que aparece quando quatro ou mais Gems são combinados. Combinar três ou mais gemas do Gemini dá tempo extra ao jogador.
- Adicione músicas. Você pode gerar músicas usando o Lyria 3 na página inicial do Gemini.
- Adicionar efeitos sonoros
- Adicionar outros modos de jogo
Divirta-se com os códigos!