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 generativo 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 trivial.
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 Lâmina de Sombra (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 caminho escolhido, aprendendo 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 chefe 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 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 do caos estático, 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 principal arma: 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 do 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 conhecer o manuseio e os recursos básicos 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). Ele 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 --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 as 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 sabe qual é 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 comandando 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 seu 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 --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. Make sure you have a place holder spot for profile picture.
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 a 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.
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.
Observação: talvez seja necessário tentar algumas vezes para que a lâmina execute essa ação corretamente. Se o problema persistir após 3 ou 4 tentativas, saia da CLI Gemini digitando /quit ou pressionando Ctrl+C duas vezes e 👉💻 execute o seguinte comando no terminal.
python3 -m http.server
👀 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
👉💻 Observação: se você estiver executando isso fora da CLI Gemini, pressione Ctrl+C para sair do servidor HTTP.
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 seu campo de treinamento.
É por isso que os artesãos mais experientes praticam as 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 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 avançadas, 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
- Se aparecer a mensagem
Do you want to connect Cloud Shell editor to Gemini CLI?, escolha NÃO. - Siga as instruções para fazer login, se solicitado, e faça login com Fazer login com o Google.
Agora você está operando na dimensão isolada. Para a CLI do 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 a proteçã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 uma prova do poder da caixa de areia. 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 plataforma de 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 transforma a CLI do Gemini de um simples interlocutor em 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ê se conecta 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 o 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 com a CLI do Gemini. Você precisa fazer uma sintonia crítica, inscrevendo o local da armaria nas runas de configuração da CLI Gemini (settings.json). No terminal, execute:
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 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 --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 "Marca do criador" é uma técnica bem elaborada, mas precisa de um lugar adequado no arsenal, uma bainha para mantê-lo seguro. Comande a CLI do Gemini para 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 mcp-imagen-go (geralmente 4, mas às vezes os números mudam), 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 atua como uma ponte, permitindo que a CLI do 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 do 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 --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. O GEMINI JÁ PODE TER FEITO ISSO PARA VOCÊ! Confira a resposta anterior. Ela pode ser inteligente o suficiente para fazer isso antes de você perguntar.
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.
PARA QUEM NÃO JOGA
6. Como montar o agente Shadowblade: programar com o Guardrails
O tempo para exercícios práticos 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 da finalidade e dos componentes principais.
- Ajuda com a configuração do ambiente:pode orientar você pelos rituais arcanos de instalação de ferramentas e configuração da máquina.
- Navegar por bases de código:ele pode servir como 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 --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 custos técnicos e expansão 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 tem a ver com 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 criado 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 seguinte comando 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 --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 emitir o grande feitiço da criação.
👉✨ Este é o único comando poderoso que vai construir 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 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 momento 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.
PARA QUEM NÃO JOGA
7. Sentinelas da Pureza: avaliando 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, mas 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 resposta 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 rolagem com 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 etapa por etapa.
- Em seguida, você define a lógica de aplicativo do 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 Kit de Desenvolvimento de Agente (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 adivinhação 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 proteção é 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. 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 para todo o gauntlet.
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 com essa runa para julgar a eloquência dele.
- 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 --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 seu 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 o desempenho 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 a vitória:
tool_trajectory_avg_score: é a medida de ação. Ele 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 em escolher a ferramenta certa e conceda 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, evitando bugs e regressões antes que eles possam prejudicar 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 --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 vai revelar uma verdade profunda: o comando adk eval usado antes é 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 do resultado 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 a Manopla ampla e o Escudo preciso inscritos e verificados, seu agente não é apenas funcional, mas também puro, testado e pronto para implantação.
PARA QUEM NÃO JOGA
8. Liberando o 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 o 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 Gemini CLI.
cd ~/agentverse-developer/
clear
gemini --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 automática de cada etapa do ritual. 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="dev-tutorial-codelab=agentverse" \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Parabéns, Shadowblade. Os rituais do códice estão completos. Chegou a hora de provar seu valor. Um Spectre, nascido do próprio caos que você aprendeu a domar, aguarda seu desafio. Prepare-se para o teste final.
PARA QUEM NÃO JOGA
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 ativo 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 (Agent 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, marque 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 protegidas, 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 agêntico de stack completo 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 seus campos de treinamento sejam limpos, 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.