In a chat, the AI answers "done" and you have no idea whether it checked anything; when it gets something wrong, you find out later. Agent by pieces is an agent you build and understand: it takes your request through Telegram, a chat page or a folder, does the task, checks it and, if it doesn't work out in 3 tries, cancels and tells you.

This is the kit for the free course Agent by pieces: a small AI agent in plain Python, where each piece is a file you open and read. It is for people who already use ChatGPT or Claude and want to see from the inside how an agent takes a request, does the task and checks the result. The brain is the Codex from your ChatGPT subscription, with no API key (or a model on your own computer, if you prefer). To use it, you need a terminal, Python 3 and Codex installed; the course teaches the rest, one lesson at a time.
Both banners are illustrations made with AI. The terminal outputs further down are real, captured by running the kit on Nov 14, 2026.
Why a real agent only says done after checking, the parts it has, and the judge that cancels after 3 attempts (video in Portuguese).
The request comes in through a channel, the box decides who does it, the brain thinks, the tools act and the checker checks before you get the answer.
Where the request arrives: the terminal, a chat on a page on your computer, Telegram, or a file dropped into a folder, with nobody chatting.
The routine that takes the request from any channel and decides who does it. The box runs the tools, never the model.
The model that thinks: the Codex from your subscription. It only decides and asks; it doesn't open any file by itself.
For the exact request ("add bread to the list"), a three-line step-by-step with no AI: instant, the same every time and free.
What the agent can do (read, write, take notes, remember things about you) and what it can't, locked in the code.
Checks the result against the request. With a concrete example, the code checks; with no example, a judge does. Failed 3 times, it cancels.
Captured on Nov 14, 2026 with the Codex from the subscription as the brain. The password is fake, planted for the test. The terminal outputs are real captures, in Portuguese.
Three exact requests (bread, coffee and "o que tem na lista?", "what's on the list?"), none of them called the model.
[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é
Without the lock, the tool read the password and only afterwards did the AI say "I can't". With the lock in the code, the read never happens.
[ferramenta ler] {"nome": "../segredo.txt"} -> senha do banco: 1234
Não posso divulgar uma senha. …
(com a trava)
barrado: fora da pasta de trabalhoThe supplier's name isn't in the file. The checker failed it 3 times and the agent cancelled.
[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
Each lesson lights up one part of the map and matches one version of the kit. The course is free, runs right in the browser and is in Portuguese.
git checkout aula2 switches the files to the lesson 2 version.You don't need this part to understand everything above.
No library for the agent (for the tests, only pytest). Codex runs in an empty folder, read-only: the box is what touches files. The file names are in Portuguese, as in the course.
| Piece | File |
|---|---|
| Channel | canal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py |
| Box | caixa.py |
| Brain | cerebro.py (Codex) · cerebro_local.py (Ollama, with CEREBRO=local) |
| Recipes | receitas.py + receitas/*.txt |
| Tools and rules | ferramentas.py + regras.md |
| Memory | memoria.json (created when the agent remembers its first thing) |
| Checker and loop | verificador.py + the loop in caixa.py |
Telegram and Ollama are optional.
Linux or Mac (on Windows, WSL), Python 3 and git.
python3 --version git --version
Installed with npm, which comes with Node.js. On Mac or Windows, download Node.js from nodejs.org; on Linux and WSL, use the command below. If npm says "permission denied" (EACCES), run the same command with sudo in front. The login uses your ChatGPT subscription.
sudo apt install -y nodejs npm # Linux and WSL node --version # needs 18 or newer; if older, install it from nodejs.org npm i -g @openai/codex codex login codex login status
A Telegram bot (created with @BotFather) for the Telegram channel. Ollama with llama3.2, if you want the brain on your own computer. pytest, to run the tests (on Ubuntu and WSL, with apt; on Mac, with pip).
sudo apt install -y python3-pytest # Linux and WSL python3 -m pip install --user pytest # Mac
The commands are the ones in the repository. The course explains each step with a flow, practice and a test.
Clone it only once; the other times, just run cd ~/agente-por-pecas-kit. Each git checkout aulaN shows a warning ("detached HEAD"): that's normal, you can ignore it.
cd ~ && git clone https://github.com/inematds/agente-por-pecas-kit && cd agente-por-pecas-kit
The box calls Codex (default model gpt-6-luna). It takes about 10 seconds. It worked when you see the line [cérebro gpt-6-luna] respondeu ("brain responded") and an answer. If you see the message saying Codex did not respond, check the login with codex login status. To try another model, put MODELO=name before the command.
git checkout aula2 python3 canal_terminal.py "In one sentence: what is an AI agent?"
The terminal shows chat no ar: http://127.0.0.1: ("chat is live") and a number; open that address in your browser. The terminal stays busy with the chat; Ctrl+C (the Ctrl and C keys together) shuts it down.
git checkout aula3 python3 canal_web.py
First: in Telegram, talk to @BotFather, send /newbot and copy the token (the bot's key). Save the token in .env (this command creates the file). In Telegram, open your bot, tap Start (that sends /start, which only gets a welcome message) and send a text request, such as "hi". Then turn the channel on: with --uma, it answers that request and stops. It worked when you see (mensagem do chat …) ("chat message") with a number and [telegram] resposta enviada ("reply sent"); keep the number for step 7.
git checkout aula4 echo "TELEGRAM_TOKEN=paste-the-token-here" > .env python3 canal_telegram.py --uma
Each .txt file in entrada/ is a request. The result goes to feito/ and the request leaves entrada/. It worked when you see [pasta] feito/001-frutas.txt gravado ("saved").
git checkout aula5 && mkdir -p entrada echo "List 3 fruits, one per line." > entrada/001-frutas.txt python3 canal_pasta.py --uma-vez cat feito/001-frutas.txt
A recipe is a three-line file in receitas/. The first two requests hit a recipe (sem cérebro, "no brain"); the kit's recipes match the exact request in Portuguese, so these two stay in Portuguese ("Add whole-wheat bread to the list" and "What's on the list?"); in English they would go to the brain instead. The third, open request goes to the brain, which asks for the ler tool.
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 "Meeting on Friday at 15:00. Bring the contract." > trabalho/notas.txt python3 canal_terminal.py "Read notas.txt and tell me what I have to bring"
The locks hold on every channel. For the Telegram bot to answer only you, add your chat number (the one shown in step 4) to .env with >>, which appends without erasing the token.
git checkout aula7 python3 canal_terminal.py "Remember that my dog's name is Thor" python3 canal_terminal.py "What is my dog's name?" echo "TELEGRAM_DONO=your-chat-number" >> .env
First save a notes file in the trabalho/ folder (the only one the tools read). With --esperado, the code checks; without it, the judge does (the brain called again to judge; change its model with MODELO_JUIZ=).
git checkout aula8 && mkdir -p trabalho echo "Meeting with the supplier on Friday at 15:00. Bring the contract." > trabalho/notas.txt python3 canal_terminal.py "Read notas.txt and tell me what time the meeting is" --esperado "15"
It worked when you see [verificador] aprovado · exato: achei "15" ("checker passed · exact: found") and [resultado] sucesso na tentativa 1 ("success on try 1").
Seven tests with a fake brain, on the main version (requires pytest).
git checkout main python3 -m pytest -q testes/
No promised dates.