aws-builder-workshops
Labs offline de agentes de IA e arquitetura AWS: teste, confira a IA, mostre a evidência
git clone https://github.com/fernando-moretes/aws-builder-workshops.gitcerca de 4 min · áudio gerado ao tocar
O aws-builder-workshops é um conjunto aberto de missões de cerca de 1 hora, um lab de triagem com cinco casos adversos, uma CLI, um servidor MCP só de leitura e uma skill para agentes, feito para quem quer aprender agentes de IA e arquitetura AWS testando, sem precisar de conta na nuvem.
Por que este repositório existe
A pergunta que eu mais ouço de quem está começando não é "qual serviço eu estudo?", é "como eu sei se o que a IA me respondeu está certo?". Tutorial que manda criar dez recursos na conta resolve a primeira pergunta e ignora a segunda. E ainda deixa uma fatura para trás quando alguém esquece de limpar.
Por isso o repositório parte de três restrições deliberadas:
- Sem conta na AWS para começar: o lab, a calculadora de fila e a CLI rodam offline. A trilha com Amazon Bedrock existe, mas é opcional e está marcada como "pode ter custo".
- Missões curtas: cerca de 1 hora cada. Você testa algo pequeno, confere o que a IA disse e sai com um artefato para mostrar.
- Evidência no lugar de opinião: toda trilha termina num registro do que foi testado, com fonte, custo e limpeza anotados.
As três missões de entrada são Conta sem susto, Portfólio no ar e Lambda quebrada. Os nomes dizem o modo de falha que cada uma ensina a evitar, não o serviço que ela apresenta.
O que tem dentro
labs/triage-agent.skills/builder-workshops/SKILL.md, no formato aberto Agent Skills.experiment gerando o esqueleto.# Navegador, sem instalar nada / Browser, nothing to install
# https://fernando-moretes.github.io/aws-builder-workshops/console/?case=A2
# Terminal (Node.js 20+)
npx -y moretes-builder-workshops menu
# Python, a partir do código / from source
git clone https://github.com/fernando-moretes/aws-builder-workshops.git
cd aws-builder-workshops/labs/triage-agent
python3 cli.py --case A2
python3 -m unittest discover -s tests -p test_core.py -v
# Docker
docker run --rm ghcr.io/fernando-moretes/builder-workshops run A2Do zero ao primeiro artefato
- 1
Escolha a trilha pelo que você quer, não pelo serviço
A página "escolha sua missão" mapeia objetivo para ponto de partida: publicar um artigo pede terminal, avaliar um agente pede só navegador, comparar com um modelo real pede conta AWS.
- 2
Rode um caso do lab
Abra o console em
?case=A2ou rodepython3 cli.py --case A2. No caso A2 a consulta falha e o valor continua ausente: o exercício é perceber isso antes de aceitar a resposta. - 3
Confirme com os testes
python3 -m unittest discover -s tests -p test_core.py -vprova que o comportamento do lab é o mesmo na sua máquina e na minha. - 4
Abra seu experimento
npx -y moretes-builder-workshops experiment meu-experimentocria a proposta, o registro de evidências, o esqueleto do artigo e o checklist de fontes, custo e limpeza. - 5
Ligue no seu IDE, se fizer sentido
A referência do MCP e a skill mostram como usar o mesmo conteúdo dentro do Kiro, Claude Code, Cursor ou VS Code, com Node.js ou Docker.
Várias portas de entrada, os mesmos cinco casos
O diagrama responde a uma pergunta: por onde você chega aos casos do lab. Console, CLI, Docker e Python executam os mesmos casos (A2 aparece nos quatro); o agente do IDE consulta pelo MCP, só de leitura. A linha tracejada é a trilha opcional com Bedrock, a única que pode gerar custo. Simplifiquei: Docker está junto da CLI e a calculadora de fila ficou de fora.
- Learner
- IDE agent · Kiro, Claude Code, Cursor
- CLI · npx or Docker
- Python lab · labs/triage-agent
- Lab console · GitHub Pages
- MCP server · 10 read-only tools
- Five adverse cases · A2 and others
- Amazon Bedrock · may incur cost
Como funciona por dentro
O desenho tem uma ideia central: o conteúdo é um só, as superfícies são várias. Os cinco casos do lab de triagem são a mesma coisa no console do navegador, na CLI publicada no npm como moretes-builder-workshops, na imagem ghcr.io/fernando-moretes/builder-workshops e no código Python. Isso não é detalhe de implementação, é o que deixa um workshop funcionar numa sala onde metade das pessoas tem Docker, um terço tem Node.js e alguém só tem o celular.
O lab não avalia se o agente "acertou". Ele avalia o comportamento do agente quando algo dá errado: no caso A2 a consulta falha e o valor continua ausente, e a resposta certa é dizer isso, não preencher o buraco com um número plausível. Esse é o modo de falha que mais vejo em agente de produção, e é o mais barato de treinar offline.
O servidor MCP expõe 10 ferramentas só de leitura e sem dependências. As duas propriedades são intencionais: ferramenta de leitura não altera nada no seu ambiente, e zero dependência significa zero pacote para auditar antes de ligar no IDE.
A documentação é PT/EN no GitHub Pages, e existe um Space no Hugging Face (fernandofa42/triage-console) com o console.
A única trilha que pode custar dinheiro
A trilha "Bedrock opcional" roda os mesmos casos contra um modelo real e pede conta AWS. Antes de começar, faça a missão Conta sem susto: o custo que machuca não é o da chamada ao modelo, é o do recurso que ficou ligado depois do workshop.
Para quem conduz um encontro
O kit em docs/community/workshops/2026-11-builder-series/ tem três workshops de 120 minutos com roteiro, caderno e modelos. O README diz que papel já funciona, e eu mantenho isso como requisito: se o Wi-Fi do auditório cair, o encontro continua.
O que eu recomendo a quem for facilitar:
- Comece pelo caso, não pelo slide: abra o console em
?case=A2nos primeiros 10 minutos. A discussão sobre por que o valor ausente importa rende mais que qualquer explicação teórica sobre alucinação. - Peça evidência no fim: o checklist do
experiment(fontes, custo, limpeza) vira o critério de "terminei". Sem ele, cada participante sai com uma impressão diferente do que aprendeu. - Deixe o Bedrock para quem já tem conta configurada: misturar quem tem e quem não tem conta no mesmo grupo trava a sala na etapa de credenciais.
O material é MIT. Pode adaptar para a sua comunidade sem pedir licença.
Perguntas frequentes
Preciso de conta na AWS?
Não para começar. Missões, lab, calculadora, CLI e MCP rodam sem nuvem. Só a trilha Bedrock pede conta e pode ter custo.
O MCP pode alterar algo no meu projeto?
As 10 ferramentas são só de leitura. O servidor não tem dependências, então não há pacote de terceiros rodando no seu IDE.
Qual versão do Node.js?
Node.js 20 ou mais novo para npx -y moretes-builder-workshops. Sem Node, use a imagem Docker ou o caminho Python.
O conteúdo está em inglês também?
Sim. README, documentação e imagens têm versão PT e EN.
Quando usar
Use este repositório quando você está começando em AWS ou em agentes de IA e quer um artefato verificável em vez de mais um tutorial assistido; quando vai conduzir um encontro e precisa de material que funcione sem conta, sem rede e até no papel; ou quando quer dar ao agente do seu IDE contexto de arquitetura por um MCP que não escreve nada. Não é o lugar certo se você precisa de infraestrutura de referência para produção: os casos são pequenos de propósito, e a trilha Bedrock é comparação, não implantação.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser