Kit for the course Agent by pieces · plain Python · brain from your subscription

Your agent only says done after checking

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.

Agent by pieces banner: your agent answers on Telegram and only says done after checking
In short

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.

Six cards: the map of the pieces, chat on a page, Telegram, the folder robot, a recipe with no AI and a checker that cancels

Both banners are illustrations made with AI. The terminal outputs further down are real, captured by running the kit on Nov 14, 2026.

Video

Understand it in 3 minutes

Why a real agent only says done after checking, the parts it has, and the judge that cancels after 3 attempts (video in Portuguese).

▶ Watch on YouTube

The pieces

An agent is made of pieces, and each one is a file

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.

Channel→Box→Recipe or Brain→Tools→Checker→Result

💬 Channel

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.

📦 Box

The routine that takes the request from any channel and decides who does it. The box runs the tools, never the model.

🧠 Brain

The model that thinks: the Codex from your subscription. It only decides and asks; it doesn't open any file by itself.

📋 Recipes

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.

🛠️ Tools, memory and rules

What the agent can do (read, write, take notes, remember things about you) and what it can't, locked in the code.

🔍 Checker

Checks the result against the request. With a concrete example, the code checks; with no example, a judge does. Failed 3 times, it cancels.

What was tested

Three real moments, exactly as they came out in the terminal

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.

Recipe: no AI

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é

The hole and the lock

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 trabalho

Cancels instead of making things up

The 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
The course

Eight lessons, one piece at a time

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.

Lesson 1
The map and the goalThe difference between a chat and an agent, and what your agent does, doesn't do and when it is finished.
Lesson 2
Box and brainThe first request: the box calls the Codex from your subscription.
Lessons 3–5
The channelsA chat on a page, Telegram and a folder where the robot works with no conversation.
Lesson 6
Recipes and toolsThe exact request goes to the recipe; the open one goes to the brain, which asks for tools.
Lesson 7
Memory and rulesWhat it remembers about you and the locks that hold even if the model is fooled.
Lesson 8
Checker and loopPass, try again or cancel, and why a concrete example is worth more than a judge.

Open the course (in Portuguese)

Words on this page

If any name is new to you

Agent
An AI program that takes a request, does the task and checks it, instead of just answering with text.
Codex
OpenAI's tool that runs in the terminal and uses your ChatGPT subscription. Here it is the brain.
API key
A password for paying to use a model outside the subscription. The kit doesn't use one.
RPA
A robot that follows fixed steps. The kit's recipes are exactly that.
Tag
A version marker in git. git checkout aula2 switches the files to the lesson 2 version.
Terminal
The window where you type commands. On Windows, use WSL, which is Linux inside Windows.
Telegram bot
A Telegram account controlled by a program. You create yours with @BotFather.
Token
Your bot's key. Whoever has the token controls the bot, so it lives in a file outside the code.
Judge
When the request doesn't come with a concrete example, the brain is called again, this time to judge whether the result does what was asked.
Ollama and llama3.2
A program that runs AI models on your computer, and one of those models. Both are optional.
npm and Node.js
Node.js is a program that runs tools written in JavaScript; npm comes with it and installs those tools, such as Codex.
.env
A file of secrets (such as the token) that stays only on your computer, outside git.
gpt-6-luna
The name of the Codex model the kit uses by default, within your subscription.
Clone and pytest
Cloning means downloading a copy of the repository with git. pytest is the tool that runs the tests.
Technical part

The kit: for those who want to run, change or study the code

You don't need this part to understand everything above.

What the kit is

Plain Python, one tag per lesson, tests with no model

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.

PieceFile
Channelcanal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py
Boxcaixa.py
Braincerebro.py (Codex) · cerebro_local.py (Ollama, with CEREBRO=local)
Recipesreceitas.py + receitas/*.txt
Tools and rulesferramentas.py + regras.md
Memorymemoria.json (created when the agent remembers its first thing)
Checker and loopverificador.py + the loop in caixa.py
Prerequisites

What you need

Telegram and Ollama are optional.

Terminal, Python and git

Linux or Mac (on Windows, WSL), Python 3 and git.

python3 --version
git --version

Codex

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

Optional

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
User guide · step by step

From the clone to the checker

The commands are the ones in the repository. The course explains each step with a flow, practice and a test.

1

Download the kit

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
2

The first request (lesson 2)

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

Chat on a page (lesson 3)

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
4

Telegram (lesson 4)

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
5

Folder, no conversation (lesson 5)

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
6

Recipes and tools (lesson 6)

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

Memory and rules (lesson 7)

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
8

Checker (lesson 8)

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

9

Tests with no model

Seven tests with a fake brain, on the main version (requires pytest).

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

Where the kit stands

No promised dates.

Done
One agent, four channelsThe eight versions of the course, with real captured outputs and tests with no model.
Idea
Several agentsA manager agent that splits the request among other agents and checks the whole thing at the end.