# aws-builder-workshops

Labs offline de agentes de IA e arquitetura AWS: teste, confira a IA, mostre a evidência

- URL: https://fernando.moretes.com/open-source/aws-builder-workshops

- Markdown: https://fernando.moretes.com/open-source/aws-builder-workshops/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/aws-builder-workshops

- Homepage: https://fernando-moretes.github.io/aws-builder-workshops/

- Language: JavaScript

- Topics: agent-skills, agentcore, ai-agents, amazon-bedrock, aws, evaluation, kiro, mcp, portuguese, solution-architecture, strands-agents, workshop

- Stars: 0

- Forks: 0

- Updated: 2026-11-06T15:46:41Z

---

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

- **Lab de triagem:** avalia um agente em 5 casos adversos, no console do navegador ou em Python em `labs/triage-agent`.
- **Capacidade de fila:** uma calculadora para prever quando mais consumidores realmente ajudam e quando só mudam o gargalo de lugar.
- **Servidor MCP:** 10 ferramentas só de leitura, sem dependências, para usar no Kiro, Claude Code, Cursor ou VS Code.
- **Skill para agentes:** `skills/builder-workshops/SKILL.md`, no formato aberto Agent Skills.
- **Três workshops de 120 minutos:** roteiro, caderno e modelos para conduzir um encontro, que funcionam até no papel.
- **Primeiro experimento:** da dúvida real ao artigo técnico, com o comando `experiment` gerando o esqueleto.

_Quatro formas de rodar o caso A2: escolha a que cabe no seu ambiente_

```bash
# 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 A2
```

## Do 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=A2` ou rode `python3 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 -v` prova 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-experimento` cria 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.

### Your machine

- Learner (user)
- IDE agent Kiro, Claude Code, Cursor (frontend)
- CLI npx or Docker (compute)
- Python lab labs/triage-agent (compute)

### Lab content

- Lab console GitHub Pages (frontend)
- MCP server 10 read-only tools (ai)
- Five adverse cases A2 and others (data)

### Optional cloud

- Amazon Bedrock may incur cost (external)

### Fluxos

- learner -> console: abre
- learner -> cli: executa
- learner -> python: clona e testa
- learner -> ide: pergunta
- ide -> mcp: chama via MCP
- mcp -> cases: lê
- console -> cases: avalia
- cli -> cases: executa
- python -> cases: executa
- cases -> bedrock: comparado em

## 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=A2` nos 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.

## Referências

- [GitHub: fernando-moretes/aws-builder-workshops](https://github.com/fernando-moretes/aws-builder-workshops)
- [Documentação / Documentation](https://fernando-moretes.github.io/aws-builder-workshops/)
- [Console do lab / Lab console](https://fernando-moretes.github.io/aws-builder-workshops/console/)
- [Hugging Face Space: triage-console](https://huggingface.co/spaces/fernandofa42/triage-console)

## Links

- [GitHub repository](https://github.com/fernando-moretes/aws-builder-workshops)
- [Homepage](https://fernando-moretes.github.io/aws-builder-workshops/)
