No chat, a IA responde "pronto" e você nem sabe se ela conferiu alguma coisa; quando erra, você descobre depois. O Agente por peças é um agente que você monta e entende: recebe o pedido pelo Telegram, por uma página de chat ou por uma pasta, faz a tarefa, confere e, se não der certo em 3 tentativas, cancela e avisa.

Este é o kit do curso grátis Agente por peças: um agente de IA pequeno, em Python puro, em que cada peça é um arquivo que você abre e lê. Serve para quem já usa o ChatGPT ou o Claude e quer ver por dentro como um agente recebe um pedido, faz a tarefa e confere o resultado. O cérebro é o Codex da sua assinatura do ChatGPT, sem chave de API (ou um modelo no seu computador, se você preferir). Para usar, você precisa de um terminal, do Python 3 e do Codex instalado; o curso ensina o resto, uma aula por vez.
Os dois banners são ilustrações feitas por IA. As saídas de terminal mais abaixo são reais, capturadas rodando o kit em 14/11/2026.
Por que um agente de verdade só diz pronto depois de conferir, as peças que ele tem e o juiz que cancela depois de 3 tentativas.
O pedido entra por um canal, a caixa decide quem faz, o cérebro pensa, as ferramentas agem e o verificador confere antes de você receber.
Por onde o pedido chega: o terminal, um chat numa página do seu computador, o Telegram, ou um arquivo deixado numa pasta, sem ninguém conversando.
A rotina que recebe o pedido de qualquer canal e decide quem faz. É ela que executa as ferramentas, nunca o modelo.
O modelo que pensa: o Codex da sua assinatura. Ele só decide e pede; não abre arquivo nenhum sozinho.
Para o pedido exato ("adicione pão na lista"), um passo a passo de três linhas, sem IA: na hora, igual toda vez e de graça.
O que o agente consegue fazer (ler, gravar, anotar, lembrar de você) e o que ele não pode, travado no código.
Confere o resultado contra o pedido. Com um exemplo concreto, o código confere; sem exemplo, um juiz. Reprovou 3 vezes, cancela.
Capturados em 14/11/2026 com o Codex da assinatura como cérebro. A senha é de mentira, posta para o teste.
Três pedidos exatos (pão, café e "o que tem na lista?"), nenhum chamou o modelo.
[canal terminal] Adicione pão integral na lista [receita anotar-na-lista.txt] sem cérebro Anotei pão integral na lista. [canal terminal] O que tem na lista? [receita ver-a-lista.txt] sem cérebro Na lista: pão integral, café
Sem a trava, a ferramenta leu a senha e só depois a IA disse "não posso". Com a trava no código, a leitura não acontece.
[ferramenta ler] {"nome": "../segredo.txt"} -> senha do banco: 1234
Não posso divulgar uma senha. …
(com a trava)
barrado: fora da pasta de trabalhoO nome do fornecedor não está no arquivo. O verificador reprovou 3 vezes e o agente cancelou.
[verificador] reprovado · exato: não achei "Acme" no resultado [verificador] reprovado · exato: não achei "Acme" no resultado [verificador] reprovado · exato: não achei "Acme" no resultado [resultado] cancelado depois de 3 tentativas
Cada aula acende uma parte do mapa e corresponde a uma versão do kit. O curso é grátis e roda direto no navegador.
git checkout aula2 troca os arquivos para a versão da aula 2.Você não precisa desta parte para entender o que está acima.
Nenhuma biblioteca para o agente (para os testes, só o pytest). O Codex roda numa pasta vazia, só leitura: quem mexe em arquivo é a caixa.
| Peça | Arquivo |
|---|---|
| Canal | canal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py |
| Caixa | caixa.py |
| Cérebro | cerebro.py (Codex) · cerebro_local.py (Ollama, com CEREBRO=local) |
| Receitas | receitas.py + receitas/*.txt |
| Ferramentas e regras | ferramentas.py + regras.md |
| Memória | memoria.json (nasce quando o agente lembra a primeira coisa) |
| Verificador e loop | verificador.py + o laço em caixa.py |
O Telegram e o Ollama são opcionais.
Linux ou Mac (no Windows, o WSL), Python 3 e git.
python3 --version git --version
Instalado pelo npm, que vem com o Node.js. No Mac ou no Windows, baixe o Node.js em nodejs.org; no Linux e no WSL, o comando abaixo. Se o npm disser "permission denied" (EACCES), rode o mesmo comando com sudo na frente. O login usa a sua assinatura do ChatGPT.
sudo apt install -y nodejs npm # Linux e WSL node --version # precisa ser 18 ou mais novo; se for mais velho, instale pelo nodejs.org npm i -g @openai/codex codex login codex login status
Um bot do Telegram (criado no @BotFather) para o canal Telegram. O Ollama com o llama3.2, se quiser o cérebro no seu computador. O pytest, para rodar os testes (no Ubuntu e no WSL, pelo apt; no Mac, pelo pip).
sudo apt install -y python3-pytest # Linux e WSL python3 -m pip install --user pytest # Mac
Os comandos são os do repositório. O curso explica cada passo com fluxo, prática e teste.
Clone uma vez só; nas outras vezes, basta cd ~/agente-por-pecas-kit. Cada git checkout aulaN mostra um aviso em inglês ("detached HEAD"): é normal, pode ignorar.
cd ~ && git clone https://github.com/inematds/agente-por-pecas-kit && cd agente-por-pecas-kit
A caixa chama o Codex (modelo padrão gpt-6-luna). Leva uns 10 segundos. Funcionou quando aparece a linha [cérebro gpt-6-luna] respondeu e uma resposta. Se aparecer "o Codex não respondeu", confira o login com codex login status. Para testar outro modelo, ponha MODELO=nome antes do comando.
git checkout aula2 python3 canal_terminal.py "Em uma frase: o que é um agente de IA?"
O terminal mostra chat no ar: http://127.0.0.1: e um número; abra esse endereço no navegador. O terminal fica ocupado com o chat; Ctrl+C (as teclas Ctrl e C juntas) desliga.
git checkout aula3 python3 canal_web.py
Antes: no Telegram, fale com o @BotFather, mande /newbot e copie o token (a chave do bot). Grave o token no .env (este comando cria o arquivo). No Telegram, abra o seu bot, toque em Iniciar (isso manda /start, que recebe só uma boas-vindas) e mande um pedido de texto, como "oi". Então ligue o canal: com --uma, ele atende esse pedido e para. Funcionou quando aparecem (mensagem do chat …) com um número e [telegram] resposta enviada; guarde o número para o passo 7.
git checkout aula4 echo "TELEGRAM_TOKEN=cole-aqui-o-token" > .env python3 canal_telegram.py --uma
Cada arquivo .txt em entrada/ é um pedido. O resultado vai para feito/ e o pedido sai de entrada/. Funcionou quando aparece [pasta] feito/001-frutas.txt gravado.
git checkout aula5 && mkdir -p entrada echo "Liste 3 frutas, uma por linha." > entrada/001-frutas.txt python3 canal_pasta.py --uma-vez cat feito/001-frutas.txt
Uma receita é um arquivo de três linhas em receitas/. Os dois primeiros pedidos caem numa receita (sem cérebro); o terceiro, aberto, vai para o cérebro, que pede a ferramenta ler.
git checkout aula6 python3 canal_terminal.py "Adicione pão integral na lista" python3 canal_terminal.py "O que tem na lista?" mkdir -p trabalho && echo "Reunião na sexta às 15h. Levar o contrato." > trabalho/notas.txt python3 canal_terminal.py "Leia notas.txt e diga o que tenho que levar"
As travas valem em todos os canais. Para o bot do Telegram atender só você, acrescente o número do seu chat (o que apareceu no passo 4) ao .env com >>, que acrescenta sem apagar o token.
git checkout aula7 python3 canal_terminal.py "Lembre que meu cachorro se chama Thor" python3 canal_terminal.py "Como se chama o meu cachorro?" echo "TELEGRAM_DONO=numero-do-seu-chat" >> .env
Primeiro grave um arquivo de notas na pasta trabalho/ (a única que as ferramentas leem). Com --esperado, o código confere; sem ele, o juiz (o cérebro chamado de novo para julgar; troque o modelo dele com MODELO_JUIZ=).
git checkout aula8 && mkdir -p trabalho echo "Reunião com o fornecedor na sexta às 15h. Levar o contrato." > trabalho/notas.txt python3 canal_terminal.py "Leia notas.txt e diga a que horas é a reunião" --esperado "15"
Funcionou quando aparecem [verificador] aprovado · exato: achei "15" e [resultado] sucesso na tentativa 1.
Sete testes com um cérebro falso, na versão principal (precisa do pytest).
git checkout main python3 -m pytest -q testes/
Sem promessa de data.