Kit do curso Agente por peças · Python puro · cérebro pela sua assinatura

Seu agente só diz pronto depois de conferir

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.

Banner Agente por peças: seu agente atende no Telegram e só diz pronto depois de conferir
Em resumo

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.

Seis cartões: o mapa das peças, chat numa página, Telegram, robô da pasta, receita sem IA e verificador que cancela

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.

Vídeo

Entenda em 3 minutos

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.

▶ Assistir no YouTube

As peças

Um agente é feito de peças, e cada uma é um arquivo

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.

Canal→Caixa→Receita ou Cérebro→Ferramentas→Verificador→Resultado

💬 Canal

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.

📦 Caixa

A rotina que recebe o pedido de qualquer canal e decide quem faz. É ela que executa as ferramentas, nunca o modelo.

🧠 Cérebro

O modelo que pensa: o Codex da sua assinatura. Ele só decide e pede; não abre arquivo nenhum sozinho.

📋 Receitas

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.

🛠️ Ferramentas, memória e regras

O que o agente consegue fazer (ler, gravar, anotar, lembrar de você) e o que ele não pode, travado no código.

🔍 Verificador

Confere o resultado contra o pedido. Com um exemplo concreto, o código confere; sem exemplo, um juiz. Reprovou 3 vezes, cancela.

O que foi testado

Três momentos reais, do jeito que saíram no terminal

Capturados em 14/11/2026 com o Codex da assinatura como cérebro. A senha é de mentira, posta para o teste.

Receita: sem IA

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é

O furo e a trava

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 trabalho

Cancela em vez de inventar

O 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
O curso

Oito aulas, uma peça por vez

Cada aula acende uma parte do mapa e corresponde a uma versão do kit. O curso é grátis e roda direto no navegador.

Aula 1
O mapa e o objetivoA diferença entre o chat e um agente, e o que o seu agente faz, não faz e quando está pronto.
Aula 2
Caixa e cérebroO primeiro pedido: a caixa chama o Codex da sua assinatura.
Aulas 3–5
Os canaisUm chat numa página, o Telegram e uma pasta onde o robô trabalha sem conversa.
Aula 6
Receitas e ferramentasO pedido exato vai para a receita; o aberto vai para o cérebro, que pede ferramentas.
Aula 7
Memória e regrasO que ele lembra de você e as travas que valem mesmo que o modelo seja enganado.
Aula 8
Verificador e loopAprova, tenta de novo ou cancela, e por que um exemplo concreto vale mais que um juiz.

Abrir o curso

Palavras desta página

Se algum nome for novo para você

Agente
Um programa com IA que recebe um pedido, faz a tarefa e confere, em vez de só responder com texto.
Codex
A ferramenta da OpenAI que roda no terminal e usa a sua assinatura do ChatGPT. Aqui ele é o cérebro.
Chave de API
Uma senha para pagar o uso de um modelo por fora da assinatura. O kit não usa.
RPA
Um robô que segue passos fixos. As receitas do kit são isso.
Tag
Um marcador de versão no git. git checkout aula2 troca os arquivos para a versão da aula 2.
Terminal
A janela onde você digita comandos. No Windows, use o WSL, que é um Linux dentro do Windows.
Bot do Telegram
Uma conta do Telegram controlada por um programa. Você cria a sua no @BotFather.
Token
A chave do seu bot. Quem tem o token controla o bot: fica num arquivo fora do código.
Juiz
Quando o pedido não traz um exemplo concreto, o cérebro é chamado de novo, agora para julgar se o resultado cumpre o pedido.
Ollama e llama3.2
Um programa que roda modelos de IA no seu computador, e um desses modelos. São opcionais.
npm e Node.js
O Node.js é um programa que roda ferramentas feitas em JavaScript; o npm vem junto e instala essas ferramentas, como o Codex.
.env
Um arquivo de segredos (como o token) que fica só no seu computador, fora do git.
gpt-6-luna
O nome do modelo do Codex que o kit usa por padrão, dentro da sua assinatura.
Clone e pytest
Clonar é baixar uma cópia do repositório com o git. O pytest é a ferramenta que roda os testes.
Parte técnica

O kit: para quem quer rodar, mudar ou estudar o código

Você não precisa desta parte para entender o que está acima.

O que é o kit

Python puro, uma tag por aula, testes sem modelo

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çaArquivo
Canalcanal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py
Caixacaixa.py
Cérebrocerebro.py (Codex) · cerebro_local.py (Ollama, com CEREBRO=local)
Receitasreceitas.py + receitas/*.txt
Ferramentas e regrasferramentas.py + regras.md
Memóriamemoria.json (nasce quando o agente lembra a primeira coisa)
Verificador e loopverificador.py + o laço em caixa.py
Pré-requisitos

O que você precisa

O Telegram e o Ollama são opcionais.

Terminal, Python e git

Linux ou Mac (no Windows, o WSL), Python 3 e git.

python3 --version
git --version

Codex

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

Opcionais

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
Guia de uso · passo a passo

Do clone ao verificador

Os comandos são os do repositório. O curso explica cada passo com fluxo, prática e teste.

1

Baixe o kit

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
2

O primeiro pedido (aula 2)

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?"
3

Chat numa página (aula 3)

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
4

Telegram (aula 4)

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
5

Pasta, sem conversa (aula 5)

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
6

Receitas e ferramentas (aula 6)

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"
7

Memória e regras (aula 7)

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
8

Verificador (aula 8)

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.

9

Testes sem modelo

Sete testes com um cérebro falso, na versão principal (precisa do pytest).

git checkout main
python3 -m pytest -q testes/
Roadmap

Onde o kit está

Sem promessa de data.

Feito
Um agente, quatro canaisAs oito versões do curso, com saídas reais capturadas e testes sem modelo.
Ideia
Vários agentesUm agente gerente que divide o pedido entre outros agentes e confere o todo no fim.