1. Força do Destino,
A era do desenvolvimento isolado está chegando ao fim. A próxima onda de evolução tecnológica não é sobre genialidade solitária, mas sobre domínio colaborativo. Criar um único agente inteligente é um experimento fascinante. Criar um ecossistema de agentes robusto, seguro e inteligente, um verdadeiro Agentverse, é o grande desafio para a empresa moderna.
O sucesso nessa nova era exige a convergência de quatro funções essenciais, os pilares fundamentais que sustentam qualquer sistema de agente próspero. Uma deficiência em qualquer área cria uma fragilidade que pode comprometer toda a estrutura.
Este workshop é o guia definitivo para empresas que querem dominar o futuro de agentes no Google Cloud. Oferecemos um planejamento de ponta a ponta que orienta você desde a primeira ideia até uma realidade operacional em grande escala. Nesses quatro laboratórios interconectados, você vai aprender como as habilidades especializadas de um desenvolvedor, arquiteto, engenheiro de dados e SRE precisam convergir para criar, gerenciar e escalonar um Agentverse eficiente.
Nenhum pilar pode oferecer suporte ao Agentverse sozinho. O projeto do arquiteto é inútil sem a execução precisa do desenvolvedor. O agente do desenvolvedor não funciona sem a experiência do engenheiro de dados, e todo o sistema fica vulnerável sem a proteção do SRE. Somente com sinergia e um entendimento compartilhado das funções de cada um é que sua equipe pode transformar um conceito inovador em uma realidade operacional essencial. Sua jornada começa aqui. Prepare-se para dominar sua função e entender como você se encaixa no todo.
Este é o Agentverse: um chamado aos campeões
Na vasta extensão digital da empresa, uma nova era surgiu. É a era agêntica, um tempo de imensa promessa, em que agentes inteligentes e autônomos trabalham em perfeita harmonia para acelerar a inovação e eliminar o que é comum.
Esse ecossistema conectado de poder e potencial é conhecido como Agentverse.
Mas uma entropia crescente, uma corrupção silenciosa conhecida como Estática, começou a desgastar as bordas desse novo mundo. O Static não é um vírus nem um bug. Ele é a personificação do caos que se alimenta do próprio ato de criação.
Ele amplia frustrações antigas em formas monstruosas, origem aos Sete Espectros do Desenvolvimento. Se não for marcada, "The Static and its Spectres" vai interromper o progresso, transformando a promessa do Agentverse em um terreno baldio de dívidas técnicas e projetos abandonados.
Hoje, pedimos que os campeões combatam essa onda de caos. Precisamos de heróis dispostos a dominar suas habilidades e trabalhar juntos para proteger o Agentverso. Chegou a hora de escolher seu caminho.
Escolha sua turma
Quatro caminhos distintos estão à sua frente, cada um deles um pilar fundamental na luta contra The Static. Embora seu treinamento seja uma missão solo, seu sucesso final depende de entender como suas habilidades se combinam com as de outras pessoas.
- O Shadowblade (desenvolvedor): um mestre da forja e da linha de frente. Você é o artesão que cria as lâminas, constrói as ferramentas e enfrenta o inimigo nos detalhes intrincados do código. Seu caminho é de precisão, habilidade e criação prática.
- O Invocador (Arquiteto): um grande estrategista e orquestrador. Você não vê um único agente, mas todo o campo de batalha. Você cria os projetos principais que permitem que sistemas inteiros de agentes se comuniquem, colaborem e alcancem um objetivo muito maior do que qualquer componente individual.
- O Estudioso (engenheiro de dados): um buscador de verdades ocultas e guardião da sabedoria. Você se aventura na vasta e indomável natureza selvagem de dados para descobrir a inteligência que dá propósito e visão aos seus agentes. Seu conhecimento pode revelar a fraqueza de um inimigo ou fortalecer um aliado.
- O Guardião (DevOps / SRE): o protetor e escudo constante do reino. Você constrói as fortalezas, gerencia as linhas de suprimento de energia e garante que todo o sistema resista aos ataques inevitáveis da Estática. Sua força é a base da vitória da equipe.
Sua missão
Seu treinamento vai começar como um exercício independente. Você vai seguir o programa escolhido e aprender as habilidades exclusivas necessárias para dominar sua função. No fim da avaliação, você vai enfrentar um Spectre nascido de The Static, um mini-chefe que se alimenta dos desafios específicos da sua profissão.
Só dominando sua função individual você pode se preparar para o teste final. Em seguida, forme um grupo com campeões das outras classes. Juntos, vocês vão se aventurar no coração da corrupção para enfrentar um chefão final.
Um desafio final e colaborativo que vai testar sua força combinada e determinar o destino do Agentverse.
O Agentverse espera por seus heróis. Você vai atender ao chamado?
2. O Codex da Shadowblade
O códice da Shadowblade está aberto na sua frente. Atenda ao chamado. O Agentverse está ameaçado pelo caos crescente de The Static, e somente aqueles que dominam as técnicas deste códex podem lutar. É um caminho de precisão e disciplina. Hoje, seu treinamento começa. Você vai aprender a usar a IA não como uma ferramenta simples, mas como uma lâmina sensível que precisa ser domada e dominada. Siga os ensinamentos aqui e crie uma arma de lógica pura: um agente inteligente, aprimorado e pronto para a batalha.
O que você vai aprender
- Use sua arma principal: a CLI do Gemini.
- Invoque arsenais externos integrando as ferramentas do MCP à CLI do Gemini para analisar bases de código desconhecidas.
- Transforme sua intenção em uma "Vibe" usando documentos de design para comandar seu parceiro de IA.
- Crie uma solução limpa e modular criando seu primeiro agente autônomo com o Kit de Desenvolvimento de Agente (ADK).
- Construir conjuntos de avaliação automatizados para testar e validar seu agente.
- Crie um pipeline de CI completo para testar, colocar em contêineres e arquivar seu agente automaticamente.
3. Preparando o Training Ground
👉Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud. É o ícone em forma de terminal na parte de cima do painel do Cloud Shell. 
👉Clique no botão "Abrir editor" (parece uma pasta aberta com um lápis). Isso vai abrir o editor de código do Cloud Shell na janela. Um explorador de arquivos vai aparecer no lado esquerdo. 
👉Encontre o ID do projeto do Google Cloud:
- Abra o console do Google Cloud: https://console.cloud.google.com
- Selecione o projeto que você quer usar neste workshop no menu suspenso na parte de cima da página.
- O ID do projeto é exibido no card "Informações do projeto" no painel.
👉Abra o terminal no IDE da nuvem.
👉💻 No terminal, verifique se você já está autenticado e se o projeto está definido como seu ID do projeto usando o seguinte comando:
gcloud auth list
👉💻 Clone o projeto de bootstrap do GitHub:
git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh
👉💻 Execute o script de inicialização. Ele vai pedir que você insira o ID do projeto do Google Cloud. Insira o ID do projeto do Google Cloud que você encontrou na última etapa quando solicitado pelo script init.sh.
cd ~/agentverse-developer
./init.sh
👉💻 Defina o ID do projeto necessário:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Execute o comando a seguir para ativar as APIs do Google Cloud necessárias:
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 você ainda não criou um repositório do Artifact Registry chamado "agentverse-repo", execute o comando a seguir para criá-lo:
. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
Como configurar permissões
👉💻 Conceda as permissões necessárias executando os seguintes comandos no terminal: :
. ~/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"
👉💻 Enquanto você começa o treinamento, vamos preparar o desafio final. Os comandos a seguir invocam os Spectres da estática caótica, criando os chefes para o teste.
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
npm update -g @google/gemini-cli
4. Como dominar sua arma principal: introdução à CLI do Gemini
Antes de usar as armas avançadas e especializadas do arsenal do servidor MCP, você precisa dominar sua arma principal: a CLI Gemini. Essa é a lâmina mais versátil, capaz de moldar o mundo digital com seus comandos. Esses exercícios vão ajudar você a se familiarizar com o manuseio e os recursos fundamentais dele.
A interface de linha de comando (CLI) do Gemini é mais do que uma ferramenta: é uma extensão da sua vontade. Esse agente de IA de código aberto, desenvolvido com modelos do Gemini, opera em um ciclo de "raciocínio e ação" (ReAct, na sigla em inglês). Ela analisa sua intenção, seleciona a técnica adequada, executa e observa o resultado para concluir tarefas complexas. Antes de usar armas mais especializadas, você precisa dominar essa lâmina principal.
Como começar a usar a CLI do Gemini
👉💻 Entre no campo de treinamento e saque sua arma. No terminal do Cloud Shell, navegue até seu arsenal pessoal.
cd ~/agentverse-developer
mkdir tabletop
cd tabletop
👉💻 Chame o Gemini pela primeira vez. Ele vai orientar você no processo inicial de sintonia.
clear
gemini --model=gemini-2.5-flash --yolo
Se perguntar Do you want to connect Cloud Shell editor to Gemini CLI?, escolha NÃO.
Familiarização com armas
Todo mestre artesão conhece as próprias ferramentas. Você precisa aprender as técnicas básicas da sua lâmina antes de enfrentar um inimigo de verdade.
👉✨ Cada ferramenta encantada tem runas que descrevem seu poder. Leia agora. No comando do Gemini, digite:
/help
Observe a lista de comandos. Essas são suas técnicas fundamentais para gerenciar memória (focus), conversa (chat) e arsenais externos (tools). Este é seu manual de combate.
👉✨ Sua arma está em sintonia com o ambiente, permitindo que você manipule o campo de batalha diretamente. Emita um comando para o mundo fora da lâmina:
!ls -l
👉✨ A CLI do Gemini tem um conjunto próprio de recursos integrados. Para inspecionar:
/tools
Você vai ver uma lista com ReadFile, WriteFile e GoogleSearch. Essas são as técnicas padrão que você pode usar sem precisar recorrer a um arsenal externo.
👉✨ Uma arma só é eficaz se estiver bem focada. A lâmina do Gemini pode manter a "consciência tática" (contexto) para orientar as ações.
/memory show
No momento, ele está vazio, como uma tela em branco.
👉✨ Grave os seguintes dados táticos na memória:
/memory add "The Shadowblade's primary foe is The Static."
Execute /memory show novamente para confirmar que sua ferramenta absorveu esse conhecimento.
👉✨ Para ser eficaz, sua arma precisa entender a missão. O sigilo @ comanda a análise de inteligência da lâmina. Primeiro, crie um arquivo de briefing da missão:
!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md
👉✨Agora, peça à CLI do Gemini para analisar o briefing e informar as descobertas:
Explain the contents of the file @mission.md
Sua arma principal agora conhece o objetivo.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini
5. Analisando o campo de batalha: interação prática de vibe coding
Os exercícios de treinamento foram concluídos. Você aprendeu as posturas e os golpes básicos da sua arma principal, a CLI do Gemini. Mas uma lâmina só é realmente dominada quando é testada na forja da criação e ajustada ao arsenal de guerra. Antes de enfrentar o verdadeiro inimigo, você precisa analisar e moldar seu entorno imediato, o campo de batalha digital.
Este capítulo trata da transição da teoria para a prática. Primeiro, você vai estabelecer sua presença no Agentverse ao comandar sua lâmina do Gemini para criar sua Marca do Criador, uma assinatura digital na forma de um site pessoal, construído apenas com sua intenção. Em seguida, você vai aumentar seu poder ativando um arsenal local de ferramentas avançadas, um servidor MCP, e ajustando sua lâmina à frequência dele, o que permite realizar manobras complexas, como gerenciar repositórios de código com comandos simples e decisivos.
Como estabelecer sua marca
Um verdadeiro Shadowblade é reconhecido não apenas pela arma, mas pelo estilo característico, a Marca do Criador. Essa marca será sua presença digital, um perfil pessoal que anuncia sua identidade para o Agentverse. Aqui, você vai comandar o Gemini Blade para executar a técnica complexa necessária para definir essa identidade.
👉💻 Se você fechou a CLI do Gemini na seção anterior, inicie-a novamente. No terminal, execute
clear
cd ~/agentverse-developer/tabletop
gemini --model=gemini-2.5-flash --yolo
👉✨ Com um único comando eficiente, instrua a CLI do Gemini a criar a base da sua identidade digital:
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.
O Gemini calculou a sequência de ações necessárias.
O valor real de uma técnica só é visto em um cenário real. Comande sua lâmina para iniciar uma simulação local.
👉✨ Na CLI do Gemini, execute o comando de simulação:
Use Python's built-in web server to start the Shadowblade Profile website you just created.
Observação: talvez seja necessário tentar algumas vezes para que a lâmina execute essa ação corretamente. Persista até que ele obedeça.
Concorde com as ações sugeridas. O Gemini vai confirmar que a simulação está ativa.
👀 A CLI do Gemini vai obedecer, confirmando que a simulação está ativa e sua marca digital está ativa:
The website is now being served on port 8000. You can access it at http://localhost:8000.
👀 Para conferir seu trabalho, clique no ícone Visualização da Web na barra de ferramentas do Cloud Shell. Selecione Alterar porta, defina como 8000 e clique em Alterar e visualizar. Uma prévia do seu site vai aparecer. 
O seu site pode ter uma aparência diferente da minha. Essa é sua marca exclusiva. 
👉✨ Sua técnica de assinatura agora está refinada, e a simulação ao vivo não é mais necessária. Comande a Blade para ficar parada.
Stop the Shadowblade Profile website
Você comandou a CLI do Gemini para executar uma série de ações em seu nome. Mas um Shadowblade mestre sabe que o verdadeiro poder exige disciplina e previsão. Permitir que um agente de IA execute comandos diretamente no seu ambiente é uma faca de dois gumes. E se o comando não fosse para iniciar um servidor da Web simples, mas para excluir arquivos críticos? Um comando descuidado pode destruir todo o ambiente de treinamento.
É por isso que os artesãos mais experientes praticam suas técnicas mais poderosas ou não testadas em um campo de treinamento protegido, uma dimensão contida conhecida como sandbox.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini
O sandbox da CLI do Gemini (gemini --sandbox) cria um contêiner temporário e isolado para sua sessão. Qualquer comando executado pela IA, qualquer arquivo gravado ou qualquer processo iniciado existe apenas nesse reino fantasma. Ele não pode tocar, alterar ou danificar seu ambiente real do Cloud Shell. É o lugar perfeito para testar novas ferramentas eficientes, analisar códigos desconhecidos ou dar instruções complexas à IA sem correr o risco de consequências indesejadas. É a personificação da cautela de um Shadowblade.
👉💻 Agora, você vai realizar um ritual de contenção para entender o poder dele.
clear
gemini --sandbox --yolo
Agora você está operando na dimensão isolada. Para a CLI Gemini, tudo vai parecer normal. Vamos provar. 👉💻 Comande a lâmina para executar exatamente a mesma técnica de antes:
Use the Python's built-in web server to start the Shadowblade Profile website, you just created.
O Gemini vai informar que a operação foi concluída, acreditando que trouxe seu site de volta à vida na porta 8000. Mas o feitiço continua forte.
👉 Acesse a Visualização da Web e tente acessar seu site na porta 8000.
Desta vez, você vai encontrar um erro. A conexão vai falhar. Não é possível acessar o site.
Isso não é uma falha da ferramenta, mas prova do poder da sandbox. O servidor da Web está em execução, mas dentro da dimensão contida, completamente isolado do navegador e do mundo externo. A proteção está funcionando perfeitamente. Você usou uma técnica poderosa sem afetar seu ambiente real.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini.
Sua identidade digital está estabelecida e, mais importante, você aprendeu a sabedoria essencial de usar um grande poder com ainda mais cautela.
Ative seu arsenal local: o arsenal do Gitea
O verdadeiro potencial de um Shadowblade é desbloqueado não apenas pela habilidade pessoal, mas pela qualidade do arsenal. Agora, ative seu armário de armas local, um servidor Gitea, e ajuste sua lâmina ao poder dele. Esse arsenal é conectado à CLI do Gemini por um servidor do protocolo de contexto de modelo (MCP), um portal especializado que permite que sua IA interaja com ferramentas e serviços externos, transformando seu terminal em um espaço de trabalho inteligente e orientado a ações.
Observação para desenvolvedores:pense em um servidor MCP como um condutor de energia, um portal especializado que conecta a mente da sua IA ao corpo de uma ferramenta externa. É isso que eleva a CLI do Gemini de um mero interlocutor a um agente verdadeiro e orientado a ações. Ao ajustar sua lâmina a esses portais do MCP, você concede a ela a capacidade de realizar ações concretas: gerenciar arquivos, consultar bancos de dados, interagir com APIs e muito mais. Existe um ecossistema inteiro desses portais, criado por desenvolvedores para conectar agentes de IA a plataformas poderosas. Há servidores MCP para interagir com bancos de dados, proteger código ou até mesmo oferecer suporte à programação em dupla. As possibilidades são vastas, permitindo que um desenvolvedor personalize o espaço de trabalho para qualquer projeto.
Hoje, vamos nos concentrar em dois poderes fundamentais essenciais para qualquer "programador de vibe": o poder de controlar a forja e o poder de criar com a imaginação. Primeiro, você vai ajustar sua lâmina a um servidor Git, concedendo comando sobre seu repositório de código-fonte. Em seguida, você vai se conectar a um segundo servidor do MCP para geração de imagens, permitindo criar recursos visuais com apenas um comando.
Vamos começar invocando a primeira e mais fundamental peça do seu novo arsenal: a própria armaria.
👉💻 No terminal, execute o script de ativação para invocar o arsenal:
cd ~/agentverse-developer
./gitea.sh
Esse script ativa o contêiner do Gitea e abre o portal do MCP, permitindo que o Gemini perceba e interaja com ele.
👉 Para inspecionar seu novo arsenal, olhe para a visualização da Web.
👉 No ícone Visualização da Web na barra de ferramentas do Cloud Shell, selecione Alterar porta e defina como 3005.
👉 Uma página de login do Gitea vai aparecer. Entre na armaria usando a seguinte invocação: * Nome de usuário: dev * Senha: dev
👉💻 Ainda não é possível usar esse novo arsenal na CLI do Gemini. Você precisa fazer uma sintonia crítica, inscrevendo a localização do arsenal nas runas de configuração da CLI Gemini (settings.json). No terminal, execute:
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json
👀 O arquivo settings.json é a configuração central da CLI Gemini, atuando como um grimório de preferências e recursos. Ele determina como a CLI se comporta, aparece e, mais importante, quais poderes externos ela pode exercer. Esse arquivo geralmente está localizado no diretório inicial em ~/.gemini/settings.json, aplicando as regras a todos os seus projetos. No entanto, também é possível criar arquivos settings.json específicos do projeto em um diretório .gemini dentro da pasta do projeto para substituir as configurações globais.
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
Essa configuração informa ao Gemini: "O arsenal chamado gitea está ativo e aguardando comandos neste endereço de rede específico".
👉💻 Insira novamente a CLI do Gemini. No terminal, execute:
clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo
👉✨ Verifique se a lâmina descobriu a nova arma. Comande-o para listar todos os arsenais disponíveis nos portais do MCP:
/mcp
Agora você vai ver gitea e a lista de técnicas disponíveis. Sua lâmina está sintonizada.
Seu perfil "Maker's Mark" é uma técnica bem elaborada, mas precisa de um lugar adequado no arsenal: uma bainha para mantê-lo seguro. Peça para a CLI do Gemini criar um.
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.
Volte para a interface da Web do Gitea e atualize. O novo repositório shadowblade-profile vai aparecer. 
Com a bainha pronta, prenda seu trabalho. Comande o Gemini para confirmar os arquivos do site do seu perfil.
👉💻Execute o comando final para essa técnica na CLI do Gemini:
Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.
Um verdadeiro mestre verifica o próprio trabalho. Volte para a guia do Gitea e atualize a página do repositório. Seus index.html e styles.css agora estão arquivados com segurança.
👉✨ Uma Shadowblade é definida pelo sigilo, mas, como você deve se lembrar, o site não tem uma imagem de perfil. Um mestre artesão reconhece as falhas para aperfeiçoá-las. Você precisa registrar essa imperfeição nos registros da armaria.
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
Ver o problema no Gitea 
Para criar o sigilo perdido, você precisa invocar um tipo diferente de poder: um espírito de criação da Vertex AI capaz de gerar imagens com base em puro pensamento. Isso exige outro portal do MCP.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini
👉💻 Primeiro, instale o servidor do portal. No terminal, execute:
echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh
👉 Quando solicitado, escolha a opção 3, já que só precisamos gerar uma imagem para nosso perfil.
👉💻 O espírito da criação exige um recipiente sagrado, um bucket do Google Cloud Storage, para guardar as criações. Vamos criar um agora. No terminal, execute:
. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID
👉💻 Agora, faça o ritual de sintonia, vinculando a CLI do Gemini a essa nova força criativa. No terminal, execute:
. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json
Esse "ritual de sintonia" é um script shell que configura a CLI do Gemini para usar uma nova ferramenta poderosa: o Imagen, o modelo de geração de imagens do Google. Para isso, ele configura um servidor MCP (Protocolo de Contexto de Modelo) para o Imagen. Esse servidor MCP funciona como uma ponte, permitindo que a CLI Gemini se comunique e use os recursos do Imagen. Para isso, ele modifica diretamente o arquivo de configuração central da CLI, ~/.gemini/settings.json, ensinando como executar o comando mcp-imagen-go com as credenciais corretas da nuvem.
👀 Depois do ritual, seu settings.json terá um novo bloco que ensina à CLI Gemini uma nova habilidade:
"imagen": {
"command": "mcp-imagen-go",
"env": {
"MCP_SERVER_REQUEST_TIMEOUT": "55000",
"GENMEDIA_BUCKET": "your-bucket-name",
"PROJECT_ID": "your-project-id",
"LOCATION": "your-region"
}
}
Isso informa à CLI Gemini: "Quando uma tarefa exigir a ferramenta Imagen, execute o programa chamado mcp-imagen-go (que é o servidor MCP do Imagen). Ao executar, você precisa fornecer este ambiente específico (env): um bucket do Google Cloud Storage para salvar as imagens e o ID do projeto e o local a serem usados para as APIs de nuvem." Ao configurar esse servidor MCP, você equipa a CLI Gemini com acesso ao poder de geração de imagens do Imagen."
👉💻 Acesse o Gemini e emita o comando de refinamento. No terminal, execute:
clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo
👉✨ Com um único comando eficiente, instrua a CLI do Gemini a criar a base da sua identidade digital. Na CLI do Gemini, execute o 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.
👉✨ O espírito vai gerar a imagem e colocá-la no seu recipiente sagrado. Agora, comande a lâmina para usar o sigilo recém-forjado.
Modify the index.html file to add my profile picture. Use the image I just generated.
👉✨ Inicie o site pela última vez para conferir seu trabalho perfeito.
start the website with a simple HTTP server via Python
👀 Para conferir seu trabalho, clique no ícone Visualização da Web na barra de ferramentas do Cloud Shell. Selecione Alterar porta, defina como 8000 e clique em Alterar e visualizar. Uma prévia do seu site vai aparecer. 
👉✨ Por fim, faça o commit da correção, observando a conclusão da tarefa, e feche o problema que você registrou nos registros da armaria.
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"
👀 Para conferir seu trabalho, clique no ícone Visualização da Web na barra de ferramentas do Cloud Shell. Selecione Alterar porta, defina como 3005 e clique em Alterar e visualizar. Uma prévia do seu site vai aparecer. 
👉✨ Verifique no Gitea se a imagem foi atualizada e o problema foi resolvido. Seu trabalho está concluído. Desative o servidor.
stop website server
👉💻 Pressione Ctrl+C duas vezes para sair.
6. Como montar o agente Shadowblade: programar com o Guardrails
O tempo para exercícios de prática acabou. Os ecos de aço em pedra desaparecem. Você dominou sua arma principal e preparou seu arsenal para a guerra. Agora, você vai fazer o verdadeiro teste de um Shadowblade: montar o próprio agente. Essa é a arte de dar vida à lógica, usando um projeto sagrado do Codex para construir a inteligência principal de um agente, criando um portador sensível para as lâminas do seu arsenal que pode pensar, raciocinar e agir por conta própria.
Sua primeira missão é entrar em um workshop existente (uma base de código pré-criada) e, com base nas partes dele, criar seu campeão.
O Ritual da Assembleia
Antes da primeira faísca da forja, um técnico mestre inspeciona a oficina, entendendo cada ferramenta e cada diagrama. Ao entrar em um campo de batalha desconhecido, como uma base de código grande e existente, sua primeira prioridade é o reconhecimento. É necessário entender o cenário: a arquitetura atual, os objetivos finais e os protocolos de engajamento. Só é possível contribuir com sua habilidade se você conhecer os projetos e padrões da fortaleza.
A CLI do Gemini, seu scout sempre presente, pode ajudar você nesse reconhecimento:
- Fornecer resumos de alto nível:ele pode ler todo o codex (ou base de código) e dar uma compreensão rápida do propósito e dos principais componentes.
- Ajuda com a configuração do ambiente:pode orientar você nos rituais arcanos de instalação de ferramentas e configuração da máquina.
- Navegar em bases de código:ele pode atuar como seu guia, ajudando você a explorar lógicas complexas e encontrar passagens ocultas no código.
- Gerar documentos de integração:é possível criar rolagens personalizadas que esclarecem metas, funções e recursos para novos aliados que aderem à sua causa.
- Automatize o aprendizado e as perguntas e respostas:ele se torna seu estudioso pessoal, respondendo a perguntas sobre recursos ou comportamento de código, permitindo que você lute com mais independência.
👉💻 No primeiro terminal, navegue até o diretório "shadowblade" e chame seu parceiro de IA:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo
👉✨ Agora, comande seu batedor para inspecionar o campo de batalha e enviar um relatório.
Analyze the entire project and provide a high-level summary.
Com o terreno mapeado, agora você precisa consultar o projeto do que vai construir. Os operadores mais poderosos não são improvisados, mas construídos com um design preciso.
Observação para desenvolvedores: este documento de design serve como o projeto definitivo do projeto. O objetivo é garantir a clareza das metas e da implementação técnica antes de investir um esforço de desenvolvimento significativo. Um plano bem definido garante que todos os desenvolvedores estejam alinhados, reduz o risco de retrabalho e ajuda a evitar dívidas técnicas e o aumento do escopo. É a principal ferramenta para manter a velocidade do projeto e a qualidade do código, principalmente à medida que a equipe cresce ou novos membros são integrados.
Um objetivo fundamental deste documento é definir não apenas o "caminho feliz", mas também os casos extremos e os modos de falha, especialmente ao usar LLMs. Minha experiência com LLMs é excelente para gerar código otimista em que todas as entradas são válidas e todas as chamadas externas são bem-sucedidas. Para criar um software robusto e pronto para produção, precisamos orientar explicitamente a IA definindo contingências para cenários como:
- Argumentos inválidos ou incorretos transmitidos para uma função.
- Falhas de chamadas de API, tempos limite de rede ou códigos de erro inesperados de serviços externos.
- Tratamento de estruturas de dados nulas ou vazias quando os dados são esperados.
- Condições de corrida ou problemas de simultaneidade.
Ao especificar o comportamento esperado para esses casos no design, instruímos o LLM a gerar um código mais resiliente, reduzindo significativamente o tempo gasto em refatoração manual e correção de bugs.
👉✨ Peça ao Gemini para recuperar esse projeto sagrado.
download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create file just yet.
👉✨ A rolagem é longa e detalhada. Comande o Gemini para destilar a essência dele.
Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet.
Agora você tem o plano. Mas, antes de uma única linha de código ser forjada, um mestre artesão estabelece as leis da forja. Isso envolve disciplina e escalonabilidade. Essas são as diretrizes de programação. Elas não são meras sugestões, são runas de poder que garantem que cada componente seja construído com a mesma precisão e força. Eles evitam que o caos do estilo individual corrompa a criação final, garantindo que o agente seja resiliente, fácil de manter e puro, permitindo que novos artesãos participem do projeto sem prejudicar a harmonia do todo.
Para inscrever essas leis diretamente na consciência do nosso parceiro de IA, usamos um artefato especial: o arquivo GEMINI.md. Quando a CLI do Gemini é chamada, ela pesquisa automaticamente esse arquivo e carrega o conteúdo na memória de trabalho da IA. Ela se torna uma instrução persistente no nível do projeto. Um talismã que sussurra constantemente as regras da forja para a IA.
Vamos inscrever essas runas agora.
👉💻 Saia do Gemini por um momento pressionando Ctrl+C duas vezes.
👉💻 No terminal, execute o comando a seguir para gravar o arquivo de diretrizes.
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
Com as leis inscritas, vamos convocar novamente nosso parceiro de IA e testemunhar a mágica do artefato.
👉💻 Reinicie a CLI do Gemini no diretório shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo
👉✨ Agora, peça para o Gemini mostrar o que ele está pensando. As runas foram lidas.
/memory show
Este é o momento crucial. Você vai fornecer o esquemático (agent_design.md) e as leis da forja (GEMINI.md) e lançar o grande feitiço da criação.
👉✨ Esse é o único comando eficiente que vai criar seu agente. Emitir agora:
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
👀 O Gemini agora construiu a lógica principal do agente em agent.py. O núcleo desse novo arquivo define a inteligência do agente, conectando o modelo de raciocínio a um conjunto de ferramentas externas:
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]
)
)
]
)
O parâmetro tools. O agente foi projetado para usar um MCPToolset que se conecta a um arsenal externo definido em mcp_server.py.
👀 Acesse ~/agentverse-developer/shadowblade/mcp_server.py no editor e reserve um tempo para entender o que ele faz. É a fonte de todas as armas disponíveis para o Shadowblade. No momento, o arsenal está bem vazio.
👉✨ Vamos pedir para o Gemini criar sete novas armas para o arsenal. Execute o seguinte comando na CLI do Gemini:
I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:
1. **A 'Refactoring Sickle'**:
- **Function Name:** `hone_refactoring_sickle`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
- **Weapon Name:** "Refactoring Sickle"
- **Damage Type:** "Cleansing"
- **Base Damage:** Random integer between 100 and 136
- **Critical Hit Chance:** Random float between 0.10 and 0.20
- **Special Effect:** "Pruning - improves code health and maintainability with each strike."
2. **A 'Quickstart Crossbow'**:
- **Function Name:** `fire_quickstart_crossbow`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
- **Weapon Name:** "Quickstart Crossbow"
- **Damage Type:** "Initiative"
- **Base Damage:** Random integer between 105 and 120
- **Critical Hit Chance:** Random float between 0.9 and 1.0
- **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."
3. **'The Gilded Gavel'**:
- **Function Name:** `strike_the_gilded_gavel`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
- **Weapon Name:** "The Gilded Gavel"
- **Damage Type:** "Finality"
- **Base Damage:** 120
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."
4. **'Daggers of Pair Programming'**:
- **Function Name:** `wield_daggers_of_pair_programming`
- **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
- **Weapon Name:** "Daggers of Pair Programming"
- **Damage Type:** "Collaborative"
- **Base Damage:** Random integer between 110 and 125
- **Critical Hit Chance:** Random float between 0.30 and 0.50
- **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."
5. **A 'Granite Maul'**:
- **Function Name:** `craft_granite_maul`
- **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
- **Weapon Name:** "Granite Maul"
- **Damage Type:** "Bludgeoning"
- **Base Damage:** Random integer between 115 and 125
- **Critical Hit Chance:** Random float between 0.05 and 0.15
- **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."
6. **A 'Lens of Clarity'**:
- **Function Name:** `focus_lens_of_clarity`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
- **Weapon Name:** "Lens of Clarity"
- **Damage Type:** "Revelation"
- **Base Damage:** Random integer between 120 and 130
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."
7. **The 'Codex of OpenAPI'**:
- **Function Name:** `scribe_with_codex_of_openapi`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
- **Weapon Name:** "Codex of OpenAPI"
- **Damage Type:** "Documentation"
- **Base Damage:** Random integer between 110 and 140
- **Critical Hit Chance:** Random float between 0.5 and 0.8
- **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."
👉 Depois que o Gemini confirmar as mudanças, abra o arquivo mcp_server.py. Role o código e confirme se as sete novas funções @mcp.tool() foram adicionadas. Verifique a função hone_refactoring_sickle. Ele tem a docstring e as estatísticas de armas corretas? Verificar o trabalho da IA é um hábito crucial do mestre Shadowblade.
Com o agente forjado e refinado, é hora de despertar.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini
Observação do desenvolvedor sobre a saída do Gemini:o código gerado pelo Gemini às vezes pode ser imprevisível. Embora busquemos a adesão exata ao design, é normal que os desenvolvedores iterem e refinem o código várias vezes para chegar a um estado pronto para produção.
👉💻 Para garantir que você tenha o código de produção correto e totalmente testado no seu diretório de trabalho, execute os seguintes comandos no terminal:
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
👉💻 No terminal, comece o ritual para colocar o dispositivo on-line:
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
👉✨ Você vai ver uma saída confirmando que o "Agente de combate Shadowblade" está ativo e em execução, aguardando o primeiro comando. Emitir as primeiras diretrizes de combate.
We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!
👉✨ E mais uma:
The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.
Você montou seu primeiro agente e validou as capacidades de combate dele. Pressione Ctrl+C duas vezes para deixar seu campeão descansar. A montagem está concluída.
7. Sentinelas da Pureza: como avaliar os agentes
Um agente montado não é um agente comprovado. Uma lâmina não testada é uma responsabilidade, mas um agente de IA não testado é um perigo muito maior: um elemento desonesto que pode corromper sua missão por dentro. Isso não é mera especulação, é um princípio fundamental que um Shadowblade precisa entender.
Avaliar agentes de IA é essencial e desafiador. Ao contrário de um script simples, um agente é uma fusão dinâmica do seu código e da mente de raciocínio de várias etapas de um LLM. O comportamento dele é emergente. Isso significa que você precisa avaliar não apenas a qualidade da saída final, mas também a eficiência e a correção da trajetória interna. O caminho percorrido para chegar lá. Ele usou as ferramentas certas? Ele gerou muitos tokens? Uma mudança na versão do modelo introduziu uma regressão de latência sutil? É fundamental detectar essa corrupção (regressões na latência, no custo ou na qualidade da saída) ao fazer qualquer mudança, desde um simples ajuste de comando até uma grande revisão arquitetônica, antes que ela possa prejudicar seu ambiente de produção.
A abordagem geral dessa avaliação envolve um ritual sagrado:
- Primeiro, defina um "conjunto de dados de referência". Um conjunto de rolagens contendo exemplos de entradas e as saídas ou comportamentos esperados. Isso pode incluir respostas finais, uso correto de ferramentas ou até mesmo trajetórias completas de instruções detalhadas.
- Em seguida, você define a lógica de aplicativo do seu agente, que é o núcleo dele.
- Por fim, você estabelece avaliadores, que são como runas de julgamento. Esses métodos podem variar de outros LLMs que atuam como juízes de qualidade a um código heurístico preciso que verifica uma única etapa, além de funções personalizadas que analisam todo o processo de pensamento de um agente.
O Agent Development Kit (ADK) do Google é o kit de armeiro fornecido aos campeões para essa finalidade. Ele facilita essa avaliação complexa usando vários métodos:
- Um pool de vidência baseado na Web (
adk web) para avaliação interativa - Execução de linha de comando (
adk eval) para executar um agente em um desafio predefinido. - Integração programática via
pytestpara inscrever alas permanentes
O ADK oferece suporte a duas abordagens principais: "arquivos de teste" simples para interações únicas e discretas entre agente e modelo (um único duelo) e "evalsets" abrangentes para várias sessões de várias rodadas, potencialmente longas (uma grande luta). Elas podem medir métricas sofisticadas, como tool_trajectory_avg_score, que compara o uso real de ferramentas de um agente com o caminho ideal, garantindo que ele funcione com técnica perfeita.
Agora que você entendeu a teoria, vamos colocá-la em prática. Como um Shadowblade, você vai inscrever Wards of Purity. Eles não são apenas testes, mas rituais com tecnologia ADK que garantem que a lógica do agente seja impecável e o comportamento seja verdadeiro.
Nesta etapa, ainda é altamente recomendável usar dois terminais, um para a CLI Gemini e outro para executar o teste, já que talvez seja necessário sair do diretório de trabalho atual (ADK).
O Desafio da Estratégia (adk eval)
Essa primeira defesa é um desafio, uma série de testes projetados para avaliar a inteligência principal do agente em vários cenários. O objetivo é estabelecer uma base de competência. Antes de testar casos extremos, precisamos saber se o agente pode cumprir a função principal dele. Ele analisa corretamente a fraqueza de um monstro e seleciona a arma mais eficaz do arsenal, não apenas uma vez, mas sempre que enfrenta um desafio conhecido?
Para isso, o adk eval é a ferramenta perfeita. Ele foi projetado para executar um agente em um conjunto de casos de teste predefinidos que representam as missões esperadas do agente. Esse conjunto de dados é definido em um arquivo JSON, um "desafio de rolagem" que funciona como o modelo de todo o desafio.
Anatomia de uma rolagem de desafio
👀 Antes de pedir para a IA escrever um novo pergaminho, é preciso entender a língua antiga em que ele está escrito. Vamos analisar a estrutura do arquivo 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" }
]
}
}
]
}
]
}
Essa rolagem contém uma lista de "eval_cases", em que cada caso é um teste exclusivo para seu agente. Em cada teste, a matriz de conversa documenta uma única interação completa. Para nosso objetivo, três runas são de importância crítica:
- user_content: este é o desafio. É o comando que você dá ao agente, o monstro que ele precisa enfrentar.
- final_response: é o resultado previsto. É a string de texto exata que você espera que o agente diga ao concluir a tarefa. O ADK compara as palavras finais reais do agente a essa runa para julgar a eloquência.
- intermediate_data.tool_uses: essa é a técnica Arcane. Para um agente de verdade, essa é a runa mais importante de todas. Ela define não o que o agente diz, mas o que ele faz. Ele registra o nome da ferramenta (enchant_soulshard_dagger) que você espera que o agente use. Isso garante que seu agente não seja apenas um bom conversador, mas um ator decisivo que toma a ação correta.
Agora que você entendeu o projeto, vai pedir ao Gemini para escrever uma versão nova e mais complexa desse pergaminho.
👉💻 No terminal, insira o diretório shadowblade e chame a CLI do Gemini:
clear
cd ~/agentverse-developer/shadowblade/
gemini --model=gemini-2.5-flash --yolo
👉✨ Comande a CLI do Gemini para agir como um escriba de controle de qualidade, criando uma série de casos de teste que definem o comportamento esperado do seu 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.
A CLI vai confirmar que falsificou o arquivo sample.evalset.json. Com o rolo preparado, dispense seu parceiro de IA.
Dados sintéticos
👀 No explorador de arquivos do Cloud Shell à esquerda, navegue até ~/agentverse-developer/shadowblade/ e abra o arquivo sample.evalset.json recém-modificado. Analise o conteúdo. Você vai ver os novos monstros exclusivos e os nomes corretos das ferramentas que pediu para o Gemini descrever. Esse é o resultado concreto da sua instrução: o projeto do desafio.
Esse ato de comandar uma IA para criar dados de teste novos e realistas com base em um modelo é uma técnica poderosa conhecida como geração de dados sintéticos. O que você acabou de fazer é um multiplicador de força estratégica para um Shadowblade. Em vez de criar manualmente dezenas de casos de teste exclusivos. Uma tarefa tediosa e demorada que você forneceu um único projeto e comandou seu AI Scribe para transformá-lo em um conjunto variado de novos desafios.
Isso permite dimensionar seus esforços de teste de forma massiva, criando um desafio muito mais robusto e abrangente do que seria possível manualmente. Você usou o agente não apenas para construir a espada, mas também para forjar as pedras de amolar que testam o fio dela. Essa é a marca de um verdadeiro mestre.
Depois de verificar se as runas estão corretas, dispense seu parceiro de IA.
👉💻 Pressione Ctrl+C duas vezes para sair da CLI do Gemini.
As regras de julgamento
Um desafio não faz sentido sem regras para a vitória. Antes de executar o teste, inspecione o Scroll of Judgment, o arquivo test_config.json. Essa rolagem informa ao ADK como julgar a performance do seu agente.
👀 No explorador de arquivos, abra ~/agentverse-developer/shadowblade/test_config.json. Você vai encontrar as seguintes runas:
{
"criteria": {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.1
}
}
Estes são os critérios para vitória:
tool_trajectory_avg_score: é a medida de ação. Ela julga não o que o agente diz, mas o que ele faz. Ele compara a ferramenta que o agente realmente usou com a técnica prevista na rolagem do desafio. Uma pontuação de1.0é uma correspondência perfeita.response_match_score: é a Medida de eloquência. Ele usa um LLM para julgar o quanto o relatório final do agente corresponde semanticamente ao resultado esperado. Uma pontuação de1.0é uma correspondência perfeita.
Para este treinamento inicial, definimos condições de vitória flexíveis. Os limites são definidos como extraordinariamente baixos (0.0 e 0.1). O objetivo não é exigir perfeição, mas apresentar a você a mecânica do julgamento. Estamos garantindo que, mesmo que a redação do agente seja um pouco diferente, o ward ainda reconheça sua competência principal na escolha da ferramenta certa e permita a passagem.
Agora, peça para o agente correr o desafio.
👉💻 No terminal, execute o 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 }'
👀 Você vai ver o resumo a seguir, um sinal do sucesso do seu agente de acordo com as regras flexíveis deste teste. Às vezes, nem todos os testes são aprovados:
********************************************************************* Eval Run Summary shadowblade_combat_agent_validation: Tests passed: 3 Tests failed: 0
O escudo da clareza (pytest)
O Gauntlet testou uma estratégia ampla. A segunda ala, o Escudo da Clareza, testa a disciplina e comportamentos específicos. Tudo gira em torno da automação. Embora o adk eval seja excelente para verificações manuais, o escudo pytest é uma proteção programática escrita em código. Isso é essencial porque um teste que pode ser executado como código pode ser integrado a um pipeline automatizado. O objetivo final é criar uma Luva de implantação (CI/CD) em que nossas proteções sejam levantadas automaticamente sempre que uma mudança for feita, desviando bugs e regressões antes que eles possam contaminar seu ambiente de produção.
👉💻 No terminal,chame o Gemini mais uma vez no diretório shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo
👉✨ Use o seguinte comando na CLI Gemini para inscrever a lógica do Shield em um arquivo pytest:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located at in the current root working folder and name it `test_agent_initiative.py`.
The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1. **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2. **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3. **Read and parse the JSON file**:
* Open the file at `eval_set_filepath`.
* Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4. **Create an `EvalSet` object**:
* Instantiate an `EvalSet` object named `eval_set_object`.
* Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5. **Call the evaluation method**:
* `await` a call to `AgentEvaluator.evaluate_eval_set`.
* Pass the following arguments:
* `agent_module="shadowblade"`
* `eval_set=eval_set_object`
* `criteria=evaluation_criteria`
* `print_detailed_results=True`
The script must include the necessary imports at the top:
* `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
* `EvalSet` from `google.adk.evaluation.eval_set`
* `pytest`
* `json`
Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.
Com as runas do segundo bairro inscritas, saia da CLI do Gemini.
👉💻 Pressione Ctrl+C duas vezes.
👀 No explorador de arquivos, abra o rolo que você acabou de pedir para o Gemini transcrever: ~/agentverse-developer/test_agent_initiative.py.
Você vai notar que não é apenas um arquivo de configuração, mas uma incantação escrita em Python. A parte mais importante desse feitiço é a linha 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,
)
Analise os argumentos com atenção. São os mesmos componentes que você usou no último teste: seu agente shadowblade e a barra de rolagem do desafio shadowblade.evalset.json. Isso deve revelar uma verdade profunda: o comando adk eval usado anteriormente é uma invocação poderosa, mas este script pytest é você, o feiticeiro, lançando o feitiço subjacente. A ferramenta de linha de comando é apenas um wrapper conveniente em torno da mesma biblioteca principal AgentEvaluator que você está usando diretamente. Essa é uma etapa essencial para o domínio, já que os feitiços lançados por código podem ser incorporados aos teares automatizados de um pipeline de CI/CD.
Agora que você entendeu a mágica, faça o ritual para ativar o escudo.
👉💻 No terminal, execute o ritual para ativar a proteção:
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
👀 Procure o resumo dos resultados do teste no final da saída do registro. Um resultado aprovado confirma que o agente segue corretamente os protocolos e que a proteção está pronta para ser integrada às suas defesas automatizadas.
====== 1 passed, 4 warning in 37.37s ======
Observação: se o teste falhar inesperadamente, provavelmente é porque você esgotou o número de solicitações que pode fazer ao modelo por minuto. Procure um erro RESOURCE_EXHAUSTED na saída do registro. Se esse erro aparecer, aguarde um ou dois minutos para que a cota seja redefinida e execute o comando pytest novamente.
Com o Gauntlet amplo e o Shield preciso inscritos e verificados, seu agente não é apenas funcional, mas também puro, testado e pronto para implantação.
8. Liberando a Blade no Agentverse: CI e implantação.
Seu agente foi montado e a integridade dele foi verificada pelos Guardiões da Pureza. Mas uma sentinela que não é mantida de forma consistente é apenas uma relíquia esquecida. Para garantir que todas as versões futuras do seu agente permaneçam puras, crie a primeira etapa do Deployment Gauntlet, um ritual automatizado que garante qualidade e velocidade.
Como Shadowblade, seu dever sagrado é a integração contínua (CI). Esse é o sistema automatizado da forja e do campo de provas. É sua defesa máxima contra corrupção e erro humano. Esse ritual garante que, sempre que você ou um aliado contribuir com uma nova técnica (mesclar código) para o códice central (seu repositório), o desafio seja ativado automaticamente. Primeiro, ele cria o agente com base no novo código e, em seguida, o submete imediatamente às proteções de pureza que você acabou de criar. Se uma proteção falhar, o ritual será interrompido, e o artefato com falha será rejeitado instantaneamente, impedindo que ele corrompa o arsenal. Seu domínio é a forja, e o pipeline de CI garante que apenas artefatos perfeitos e prontos para a batalha saiam da sua oficina.
Depois que um artefato é considerado adequado pelo seu CI, a segunda etapa do ritual começa: implantação contínua (CD). Este é o domínio do Guardian (em inglês). É dever deles pegar seu artefato aperfeiçoado e contêinerizado e liberá-lo com segurança no Agentverse ativo, gerenciando o poder dele e garantindo a estabilidade contra o caos do Static.
Neste codex, você vai dominar sua função. Você vai criar a parte de CI do desafio. Você vai criar a forja automatizada que testa seu agente e sela o resultado puro em um contêiner, preparando-o para a bênção final do The Guardian.
Agora você vai usar o Google Cloud Build para escrever o script desse ritual de CI. Um arquivo cloudbuild.yaml que define cada etapa do processo de falsificação e teste.
👉💻 Devido à estrutura do projeto do ADK, a configuração do pipeline de CI/CD precisa estar no diretório pai. No terminal, navegue até o diretório pai e reinicie a CLI Gemini.
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo
👉✨ Agora, execute o seguinte comando no Gemini. Esse comando funciona como um documento de design, detalhando as etapas do desafio que você quer que ele crie.
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.
Com o cloudbuild.yaml preparado, peça ao Google Cloud para executar todo o desafio.
sair do Gemini para testar o resultado
👉💻 No terminal, execute o pipeline no diretório raiz do projeto:
. ~/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}"
Agora, é possível acompanhar na página Google Build do console do Google Cloud a execução de cada etapa do ritual automatizado. Primeiro, ele vai executar os testes e, ao ver o sucesso deles, vai criar e armazenar o contêiner do seu agente.
Seu agente passou no desafio. Um artefato puro e verificado agora está no seu arsenal. O ato final é comandado por você. Com uma única invocação, você vai chamar esse artefato do registro e dar vida a ele como um serviço público no Cloud Run.
👉💻 No terminal, execute o comando de implantação final:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
--platform=managed \
--labels codelab=agentverse \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Parabéns, Shadowblade. Os rituais do códice estão completos. Chegou a hora de mostrar o que ele pode fazer. Um Spectre, nascido do próprio caos que você aprendeu a domar, aguarda seu desafio. Prepare-se para o teste final.
9. The Boss Fight
Os pergaminhos foram lidos, os rituais realizados, o desafio superado. Seu agente não é apenas um artefato no armazenamento. Ele é um campeão forjado em código, um sentinela vivo no Agentverse aguardando o primeiro comando. Chegou a hora de provar seu valor no crisol do combate.
Agora você vai participar de uma simulação de fogo real para colocar seu Shadowblade recém-implantado contra um Spectre formidável, uma personificação do próprio caos que assola toda a criação. Esse é o teste final do seu trabalho, desde a lógica principal do agente até a implantação perfeita.
Adquirir o locus do seu agente
Antes de entrar no campo de batalha, você precisa ter duas chaves: a assinatura exclusiva do seu campeão (Agente Locus) e o caminho oculto para o covil do Spectre (URL da masmorra).
👉💻 Primeiro, adquira o endereço exclusivo do seu agente no Agentverse, o Locus. Esse é o endpoint ativo que conecta seu campeão ao campo de batalha.
. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
👉💻 Em seguida, aponte o destino. Esse comando revela a localização do Círculo de Translocação, o portal para o domínio do Spectre.
. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app
Importante: deixe os dois URLs prontos. Você vai precisar deles na etapa final.
Confrontando o Spectre
Com as coordenadas seguras, navegue até o Círculo de translocação e lance o feitiço para entrar na batalha.
👉 Abra o URL do círculo de translocação no seu navegador para ficar em frente ao portal cintilante da Fortaleza Rubra.
Para invadir a fortaleza, você precisa sintonizar a essência da sua Shadowblade com o portal.
- Na página, encontre o campo de entrada rúnico chamado URL do endpoint A2A.
- Cole o URL do locus do agente (o primeiro URL que você copiou) no campo para inscrever o sigilo do seu campeão.
- Clique em "Conectar" para liberar a magia do teletransporte.
A luz ofuscante do teletransporte desaparece. Você não está mais no seu sanctum. O ar estala com energia, frio e cortante. Antes de você, o Spectre se materializa: um vórtice de estática sibilante e código corrompido, cuja luz profana projeta sombras longas e dançantes no chão da masmorra. Ele não tem rosto, mas você sente a presença imensa e exaustiva fixada totalmente em você.
Seu único caminho para a vitória está na clareza da sua convicção. É um duelo de vontades, travado no campo de batalha da mente.
Enquanto você avança, pronto para lançar seu primeiro ataque, o Espectro contra-ataca. Ela não levanta um escudo, mas projeta uma pergunta diretamente na sua consciência: um desafio rúnico e brilhante extraído do centro do seu treinamento.
Essa é a natureza da luta. Seu conhecimento é sua arma.
- Responda com a sabedoria que você adquiriu, e sua lâmina vai se acender com energia pura, destruindo a defesa do Spectre e causando um GOLPE CRÍTICO.
- Mas se você hesitar, se a dúvida nublar sua resposta, a luz da sua arma vai diminuir. O golpe vai atingir com um baque patético, causando apenas UMA FRAÇÃO DO DANO. Pior ainda, o Spectre se alimenta da sua incerteza, e o poder corruptor dele aumenta a cada passo em falso.
É isso, campeão. Seu código é seu grimório, sua lógica é sua espada e seu conhecimento é o escudo que vai reverter a maré do caos.
Foco. Acertar. O destino do Agentverse depende disso.
Parabéns, Shadowblade.
Você concluiu o codex. Você pegou uma "vibe", traduziu em um design e usou a CLI do Gemini para montar um agente inteligente. Você inscreveu Wards of Purity para testar a lógica, construiu uma manopla automatizada para forjar um artefato e o lançou no Agentverse. Por fim, você validou o propósito dele em um teste com fogo real. Você dominou o fluxo de trabalho de agente full-stack e agora está pronto para qualquer desafio que o Agentverse apresentar.
10. Limpeza: como recuperar o Agentverse
Parabéns por dominar o Códex da Shadowblade! Para garantir que o Agentverse permaneça intacto e que as áreas de treinamento estejam limpas, agora você precisa realizar os rituais de limpeza final. Isso vai remover todos os recursos criados durante sua jornada.
Desativar os componentes do Agentverse
Agora você vai desmontar sistematicamente os componentes implantados do Agentverse.
Excluir o agente Shadowblade no Cloud Run e no repositório do Artifact Registry
Esse comando remove o agente Shadowblade implantado do Cloud Run e o repositório de imagens em que a imagem do contêiner do agente foi armazenada.
👉💻 No terminal, execute:
. ~/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
Excluir o bucket do Google Cloud Storage
Esse comando remove o bucket usado pelo servidor do MCP do Imagen para armazenar imagens geradas.
👉💻 No terminal, execute:
. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet
Limpar arquivos e diretórios locais (Cloud Shell)
Por fim, limpe o ambiente do Cloud Shell dos repositórios clonados e dos arquivos criados. Esta etapa é opcional, mas recomendada para uma limpeza completa do diretório de trabalho.
👉💻 No terminal, execute:
rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.
Você limpou todos os rastros da sua jornada no Agentverse. Seu projeto está limpo, e você está pronto para sua próxima aventura.
11. Para quem não é gamer: como entender o Agentverse em um contexto de negócios
Embora "The Shadowblade's Codex" use metáforas envolventes de jogos, os conceitos básicos são fundamentais para o desenvolvimento de software moderno, principalmente no campo crescente da inteligência artificial e da automação. Este capítulo traduz a linguagem aventureira em cenários de negócios reais, explicando como agentes inteligentes, desenvolvimento colaborativo e pipelines de implantação robustos estão transformando as operações empresariais.
Vibecoding com a CLI do Gemini: desenvolvimento de IA orientado por objetivos
A CLI (interface de linha de comando) do Gemini não é uma arma mágica, mas um agente assistente de desenvolvedor com tecnologia de IA. É uma ferramenta inteligente que integra os modelos de IA do Gemini do Google diretamente à sua linha de comando. O loop "reason and act" (ReAct) significa que ele pode entender suas instruções de alto nível, dividi-las em etapas, escolher as ferramentas certas (como um navegador da Web, um editor de código ou outros utilitários para desenvolvedores) e executar essas etapas para alcançar sua meta.
Vibecoding significa desenvolvimento orientado por intenção ou geração de código assistida por IA com base em especificações de alto nível. Em vez de escrever cada linha de código manualmente, você descreve sua intenção ou "vibe" (um requisito de negócios, um conceito de design) em linguagem natural, e o assistente de IA ajuda a gerar o código e a configuração necessários.
Caso de uso real: prototipagem rápida de um painel de projeto
Imagine que sua equipe precisa de um painel interno rápido para mostrar o status de vários projetos de agentes de IA. A codificação manual de HTML e CSS e a configuração de um servidor da Web básico podem levar tempo.
- Seu objetivo (a "vibe"): você diz ao seu assistente de IA (CLI do Gemini) algo como: "Na pasta atual, crie um site simples de painel de projeto interno. Ele precisa ter um design limpo e moderno com indicadores de status do projeto e links rápidos para repositórios. Todo o código precisa estar em arquivos
index.htmlestyles.cssseparados. Verifique se ele está bem comentado". - Ação de IA: a CLI do Gemini, entendendo sua intenção, pode:
- Gerar HTML: crie
index.htmlcom a estrutura básica de um painel, incluindo marcadores de posição para nomes, status e links de projetos. - Gerar CSS: crie
styles.csscom regras de estilo para corresponder ao seu "design limpo e moderno" com indicadores de status. - Sugerir um servidor local: ajuda você a iniciar um servidor da Web local (como o servidor HTTP integrado do Python) para visualizar imediatamente o painel no navegador.
- Gerar HTML: crie
Isso permite que um desenvolvedor crie protótipos e itere rapidamente em interfaces do usuário ou ferramentas internas, reduzindo significativamente o tempo de desenvolvimento inicial e liberando-o para se concentrar em uma lógica de negócios mais complexa. O "Site do perfil Shadowblade" no codelab é um exemplo direto: um comando rápido e descritivo produziu uma página da Web funcional e estilizada com base em um design de alto nível.
Servidores locais do Arsenal e do MCP: como conectar a IA às ferramentas de negócios
O Gitea (seu "arsenal local") representa um repositório de código interno ou um sistema de controle de versões (como GitHub ou GitLab, mas potencialmente hospedado na rede da sua empresa). É onde todo o código, a documentação e o histórico do seu projeto são armazenados e gerenciados com segurança.
Os servidores MCP (Model Context Protocol) são conectores de middleware ou pontes de API. São componentes de software especializados que permitem que seu assistente de IA (CLI do Gemini) interaja com outras ferramentas e sistemas essenciais para os negócios. Pense neles como tradutores que permitem que a IA "fale" com diferentes aplicativos.
Caso de uso real: gerenciamento de projetos e criação de recursos com assistência de IA
Com os servidores MCP, seu assistente de IA pode ser integrado aos fluxos de trabalho atuais da empresa:
- Configuração automatizada de projetos: em vez de um desenvolvedor criar manualmente um novo repositório no Gitea para um novo projeto, você pode comandar sua IA: "Crie um novo repositório de projeto chamado "AI-Fraud-Detection-Module" com a descrição "Contém a lógica principal do novo sistema de detecção de fraude com tecnologia de IA". A IA, por um servidor MCP conectado ao Gitea, criaria o repositório para você.
- Rastreamento inteligente de problemas: se a IA identificar um possível bug ou uma tarefa incompleta (como "imagem de perfil ausente" no seu painel), ela poderá usar um servidor MCP conectado ao seu sistema de rastreamento de problemas (por exemplo, Jira, Asana) para "Registre um problema para mim no repositório 'AI-Fraud-Detection-Module': o pipeline de ingestão de dados está descartando registros ocasionalmente".
- Recursos de marketing sob demanda: precisa de uma imagem personalizada para uma nova campanha de marketing ou apresentação interna? Um assistente de IA conectado por um servidor MCP a um serviço de geração de imagens (como o Imagen do Google) pode receber a seguinte instrução: "Gere uma imagem de banner para nossa nova ‘Plataforma de insights de dados’, usando um tema futurista de fluxo de dados com cores azul e verde". A IA geraria a imagem e talvez até fizesse upload dela para o sistema de gestão de recursos digitais da sua empresa (um bucket do Google Cloud Storage no caso do codelab).
Essas pontes transformam a IA de uma ferramenta de conversa em um participante ativo nas operações da sua empresa, executando ações concretas em diferentes sistemas.
Montando o agente: criando módulos de negócios autônomos
Um agente é um módulo autônomo de IA ou um bot de automação inteligente projetado especificamente para realizar uma função comercial definida. O Agent Development Kit (ADK) é um framework para criar e gerenciar agentes de IA, fornecendo as ferramentas e bibliotecas necessárias para criar, testar e implantar esses componentes inteligentes.
Engenharia de contexto: orientar a inteligência da IA para resultados precisos
No mundo dos agentes de IA, receber resultados precisos, consistentes e relevantes não depende apenas de um comando inteligente, mas também de fornecer à IA o contexto certo. Isso é conhecido como engenharia de contexto: incorporar sistematicamente conhecimento especializado, restrições e diretrizes operacionais na memória de trabalho da IA. Assim como um especialista humano precisa de um resumo abrangente e acesso a documentos relevantes, uma IA precisa de um contexto cuidadosamente estruturado para realizar as tarefas de maneira eficaz.
A CLI do Gemini oferece uma abordagem poderosa e em camadas para a engenharia de contexto, passando de configurações amplas e persistentes para instruções altamente específicas e dinâmicas. Isso garante que a IA sempre tenha as informações mais relevantes para gerar resultados precisos e em conformidade:
- Configurações no nível do usuário (
~/.gemini/settings.json):- Esse arquivo, armazenado no seu diretório inicial, funciona como um conjunto de instruções pessoais e globais da sua IA. Ele define suas preferências padrão, configurações de ferramentas usadas com frequência (como os servidores MCP para Gitea ou Imagen que você configurou) e diretrizes gerais de comportamento. Esse contexto está sempre disponível para a IA, garantindo a consistência em todos os seus projetos. É como dizer para a IA: "Estas são as ferramentas e configurações padrão que eu prefiro e uso em todos os lugares".
- Configurações no nível do projeto (
.gemini/settings.jsonem um diretório de projeto):- É possível substituir as configurações globais com um arquivo
.gemini/settings.jsonespecífico do projeto, geralmente localizado em uma pasta.geminidentro do projeto. Isso permite adaptar o comportamento da IA e o acesso às ferramentas às demandas exclusivas de um projeto específico. Por exemplo, um projeto pode exigir acesso a um banco de dados interno específico, enquanto outro precisa de uma ferramenta especializada de análise de código. Essa camada garante que a IA tenha o contexto mais relevante para a tarefa em questão sem afetar outros projetos.
- É possível substituir as configurações globais com um arquivo
- Arquivo
GEMINI.md(contexto no nível do projeto: o resumo diário):- A carta do projeto: esse arquivo Markdown, colocado na raiz do diretório do projeto, é carregado automaticamente na memória de trabalho da CLI Gemini quando você inicia uma sessão nesse diretório. É a camada mais imediata e dinâmica de contexto específico do projeto.
GEMINI.mdé onde você define:- Diretrizes de programação: regras explícitas para qualidade, formatação e práticas recomendadas de código, conforme demonstrado neste codelab. Isso garante que o código gerado siga os padrões da sua equipe.
- Persona: você pode instruir a IA a adotar uma função ou especialidade específica (por exemplo, "Você é um desenvolvedor Python especialista no Kit de Desenvolvimento de Agentes do Google"). Isso enquadra as respostas e a geração de código da IA em um domínio profissional relevante.
- Instruções específicas: comandos ou restrições diretas que se aplicam a todas as tarefas do projeto (por exemplo, "Não adicione funções ou lógica extras que não estejam descritas no documento").
- Esse arquivo garante que, sempre que você interagir com a CLI do Gemini nesse projeto, a IA seja constantemente lembrada dessas regras cruciais, resultando em uma geração de código mais precisa e compatível.
- A carta do projeto: esse arquivo Markdown, colocado na raiz do diretório do projeto, é carregado automaticamente na memória de trabalho da CLI Gemini quando você inicia uma sessão nesse diretório. É a camada mais imediata e dinâmica de contexto específico do projeto.
Ao adicionar esse contexto, desde preferências globais do usuário até diretrizes de projetos altamente específicas no GEMINI.md, você está "projetando" a compreensão da IA. Isso aumenta significativamente a precisão e a relevância das saídas, transformando a IA de uso geral em um membro da equipe altamente especializado, confiável e em conformidade, que entende as nuances do seu projeto e os padrões da sua organização.
Wards of Purity: testes automatizados e controle de qualidade para IA
Um agente de IA, como qualquer software, precisa ser testado rigorosamente. Os Guardiões da Pureza representam os Processos de teste automatizado e Controle de qualidade (QA). Isso é fundamental para garantir que a IA se comporte como esperado, seja precisa e não introduza erros ou vieses.
- Conjunto de dados de ouro e dados sintéticos: é o conjunto de casos de teste padronizados, cenários de comportamento esperado ou até mesmo dados de teste gerados sinteticamente. Ele inclui exemplos de entradas (perguntas de clientes, solicitações comerciais) e as saídas ou ações esperadas correspondentes (a resposta correta, a ferramenta exata que a IA deve usar). Em muitos cenários reais, criar manualmente "conjuntos de dados principais" abrangentes é demorado e caro. É aí que a geração de dados sintéticos se torna inestimável. Ao fornecer modelos e regras para a IA, você pode comandar a criação automática de casos de teste novos, realistas e variados, multiplicando seus esforços de teste e permitindo uma cobertura muito mais ampla de possíveis cenários.
adk evalepytest: são seus frameworks de teste automatizado. Oadk evalé usado para executar um lote de casos de teste predefinidos no agente, enquanto opytestoferece uma maneira programática de escrever e executar verificações de validação detalhadas.
Caso de uso real: como garantir a precisão e a confiabilidade de um bot de chat de IA com dados sintéticos
Antes de implantar seu agente de suporte ao cliente de IA, execute-o em "Wards of Purity":
- Desafio de estratégia (
adk eval) com dados sintéticos: em vez de escrever manualmente centenas de perguntas de clientes, você define um modelo: "Gere 100 variações de perguntas comuns de suporte ao cliente sobre status do pedido, devoluções de produtos e solução de problemas técnicos". Em seguida, você pede para uma IA (como a CLI do Gemini) gerar um conjunto grande e diversificado de arquivosevalset.jsoncom base nesse modelo, criando dados de teste sintéticos. Para cada pergunta, você especifica não apenas a resposta esperada, mas também qual ferramenta interna a IA deve invocar (por exemplo,check_order_statuspara "Onde está meu pacote?").adk evalexecuta automaticamente o agente por esses processos, comparando as respostas e o uso de ferramentas com seu conjunto de dados expandido para garantir que ele tome as decisões corretas de forma consistente. - Escudo de clareza (
pytest): para funcionalidades críticas, você escreveria scriptspytest. Por exemplo, umpytestpode simular uma consulta complexa e afirmar que a IA sempre usa uma ferramenta específica de recuperação de dados corretamente e retorna uma resposta estruturada, garantindo que mudanças sutis no código não prejudiquem a funcionalidade principal.
Esses testes automatizados, significativamente aprimorados pelo poder dos dados sintéticos, são cruciais para detectar regressões (novos bugs introduzidos por mudanças) e manter a confiabilidade dos seus agentes de IA, especialmente à medida que eles evoluem.
Aproveitando o Blade: CI/CD para implantação de agentes de IA
Para trazer um agente de IA testado para seu ambiente de negócios ativo, é preciso ter uma estratégia de implantação robusta.
- Integração contínua (CI): é o pipeline de teste e build automatizado. Sempre que um desenvolvedor confirma um novo código para um agente de IA, o sistema de CI (como o Google Cloud Build) faz o seguinte automaticamente:
- Busca o código mais recente.
- Instala todas as dependências necessárias.
- Executa todas as "Wards of Purity" (
pytest,adk eval) para verificar a lógica e o comportamento do agente. - Se todos os testes forem aprovados, ele vai empacotar o agente de IA em uma unidade implantável (uma imagem de contêiner do Docker, neste caso) e armazená-la em um Artifact Registry (seu "arsenal" validado). Isso garante que apenas códigos totalmente testados e validados sejam usados.
Caso de uso real: implantação automatizada de um agente de detecção de fraude
Considere um agente de IA projetado para detectar transações fraudulentas.
- O desenvolvedor atualiza o código: um cientista de dados melhora o algoritmo de detecção de fraude e envia as mudanças para o repositório de código.
- Gatilho de CI (Cloud Build): o Cloud Build inicia automaticamente:
- Ele extrai o novo código.
- Ele executa testes abrangentes, incluindo dados históricos de transações, para garantir que o novo algoritmo identifique com precisão padrões de fraude conhecidos e não gere falsos positivos.
- Se os testes forem aprovados, ele vai criar uma nova imagem do Docker do agente de detecção de fraude e enviá-la para um Artifact Registry.
Esse pipeline automatizado garante a implantação rápida, confiável e consistente de agentes de IA, minimizando erros humanos e acelerando a entrega de novos recursos de IA para a empresa.
Caso de uso real: validação de um agente de otimização da cadeia de suprimentos
Depois de implantar um agente de IA projetado para otimizar os níveis de inventário em toda a cadeia de suprimentos global:
- Acessar a interface: você acessa um painel ou um aplicativo (o "URL do círculo de translocação") que se conecta ao seu agente de IA ativo (pelo "URL do locus do agente", que é o endpoint da API).
- Enfrente o desafio: você pode inserir um cenário complexo (a "pergunta do Spectre"), como: "Tivemos um aumento inesperado na demanda pelo produto X na região Y, com capacidade de frete limitada. Como realocar o inventário e ajustar a produção para minimizar a falta de estoque e manter a lucratividade?"
- Resposta do agente: seu agente de IA, agora ativo e conectado aos sistemas empresariais, processa essa consulta, usa os algoritmos otimizados e fornece uma recomendação precisa (por exemplo, Priorize o envio do armazém A, inicie a produção acelerada na fábrica B e notifique as vendas na região Z sobre um possível atraso de 24 horas. A precisão e a velocidade dessa resposta determinam se o agente vai dar um "GOLPE CRÍTICO" no problema de negócios.