En el chat, la IA responde "listo" y ni sabes si comprobó algo; cuando se equivoca, te enteras después. El Agente por piezas es un agente que armas y entiendes: recibe el pedido por Telegram, por una página de chat o por una carpeta, hace la tarea, la comprueba y, si no sale bien en 3 intentos, cancela y avisa.

Este es el kit del curso gratuito Agente por piezas (en portugués): un agente de IA pequeño, en Python puro, en el que cada pieza es un archivo que abres y lees. Sirve para quien ya usa ChatGPT o Claude y quiere ver por dentro cómo un agente recibe un pedido, hace la tarea y comprueba el resultado. El cerebro es el Codex de tu suscripción de ChatGPT, sin clave de API (o un modelo en tu computadora, si lo prefieres). Para usarlo necesitas una terminal, Python 3 y el Codex instalado; el curso enseña el resto, una clase a la vez.
Los dos banners son ilustraciones hechas con IA. Las salidas de terminal más abajo son reales, capturadas ejecutando el kit el 14/11/2026.
Por qué un agente de verdad solo dice listo después de verificar, las piezas que tiene y el juez que cancela tras 3 intentos (video en portugués).
El pedido entra por un canal, la caja decide quién lo hace, el cerebro piensa, las herramientas actúan y el verificador comprueba antes de que recibas la respuesta.
Por donde llega el pedido: la terminal, un chat en una página de tu computadora, Telegram, o un archivo dejado en una carpeta, sin nadie conversando.
La rutina que recibe el pedido de cualquier canal y decide quién lo hace. Es ella la que ejecuta las herramientas, nunca el modelo.
El modelo que piensa: el Codex de tu suscripción. Solo decide y pide; no abre ningún archivo por su cuenta.
Para el pedido exacto ("añade pan a la lista"), un paso a paso de tres líneas, sin IA: al instante, igual cada vez y gratis.
Lo que el agente puede hacer (leer, guardar, anotar, recordar cosas de ti) y lo que no puede, bloqueado en el código.
Compara el resultado con el pedido. Con un ejemplo concreto, lo comprueba el código; sin ejemplo, un juez. Si reprueba 3 veces, cancela.
Capturados el 14/11/2026 con el Codex de la suscripción como cerebro. La contraseña es falsa, puesta para la prueba. Las salidas de terminal son capturas reales, en portugués.
Tres pedidos exactos (pan, café y "¿qué hay en la lista?"), ninguno llamó al 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é
Sin el bloqueo, la herramienta leyó la contraseña y solo después la IA dijo "no puedo". Con el bloqueo en el código, la lectura no ocurre.
[ferramenta ler] {"nome": "../segredo.txt"} -> senha do banco: 1234
Não posso divulgar uma senha. …
(com a trava)
barrado: fora da pasta de trabalhoEl nombre del proveedor no está en el archivo. El verificador reprobó 3 veces y el agente canceló.
[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 clase enciende una parte del mapa y corresponde a una versión del kit. El curso es gratuito, está en portugués y funciona directamente en el navegador.
git checkout aula2 cambia los archivos a la versión de la clase 2.No necesitas esta parte para entender lo que está arriba.
Ninguna biblioteca para el agente (para las pruebas, solo pytest). El Codex se ejecuta en una carpeta vacía, solo lectura: quien toca los archivos es la caja.
| Pieza | Archivo |
|---|---|
| Canal | canal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py |
| Caja | caixa.py |
| Cerebro | cerebro.py (Codex) · cerebro_local.py (Ollama, con CEREBRO=local) |
| Recetas | receitas.py + receitas/*.txt |
| Herramientas y reglas | ferramentas.py + regras.md |
| Memoria | memoria.json (nace cuando el agente recuerda la primera cosa) |
| Verificador y bucle | verificador.py + el bucle en caixa.py |
Telegram y Ollama son opcionales.
Linux o Mac (en Windows, WSL), Python 3 y git.
python3 --version git --version
Se instala con npm, que viene con Node.js. En Mac o en Windows, descarga Node.js en nodejs.org; en Linux y en WSL, con el comando de abajo. Si npm dice "permission denied" (EACCES), ejecuta el mismo comando con sudo delante. El inicio de sesión usa tu suscripción de ChatGPT.
sudo apt install -y nodejs npm # Linux y WSL node --version # necesita 18 o más reciente; si es más antiguo, instálalo desde nodejs.org npm i -g @openai/codex codex login codex login status
Un bot de Telegram (creado en @BotFather) para el canal Telegram. Ollama con llama3.2, si quieres el cerebro en tu computadora. pytest, para ejecutar las pruebas (en Ubuntu y en WSL, con apt; en Mac, con pip).
sudo apt install -y python3-pytest # Linux y WSL python3 -m pip install --user pytest # Mac
Los comandos son los del repositorio. El curso (en portugués) explica cada paso con flujo, práctica y prueba.
Clona una sola vez; las demás veces basta con cd ~/agente-por-pecas-kit. Cada git checkout aulaN muestra un aviso en inglés ("detached HEAD"): es normal, puedes ignorarlo.
cd ~ && git clone https://github.com/inematds/agente-por-pecas-kit && cd agente-por-pecas-kit
La caja llama al Codex (modelo predeterminado gpt-6-luna). Tarda unos 10 segundos. Funcionó cuando aparece la línea [cérebro gpt-6-luna] respondeu y una respuesta. Si aparece el error del Codex sin respuesta (el kit lo escribe en portugués: o Codex não respondeu), revisa el inicio de sesión con codex login status. Para probar otro modelo, pon MODELO=nombre antes del comando.
git checkout aula2 python3 canal_terminal.py "En una frase: ¿qué es un agente de IA?"
La terminal muestra chat no ar: http://127.0.0.1: y un número; abre esa dirección en el navegador. La terminal queda ocupada con el chat; Ctrl+C (las teclas Ctrl y C juntas) lo apaga.
git checkout aula3 python3 canal_web.py
Antes: en Telegram, habla con @BotFather, envía /newbot y copia el token (la clave del bot). Guarda el token en el .env (este comando crea el archivo). En Telegram, abre tu bot, toca Iniciar (eso envía /start, que solo recibe una bienvenida) y envía un pedido de texto, como "hola". Entonces enciende el canal: con --uma, atiende ese pedido y se detiene. Funcionó cuando aparecen (mensagem do chat …) con un número y [telegram] resposta enviada; guarda el número para el paso 7.
git checkout aula4 echo "TELEGRAM_TOKEN=pega-aqui-el-token" > .env python3 canal_telegram.py --uma
Cada archivo .txt en entrada/ es un pedido. El resultado va a feito/ y el pedido sale de entrada/. Funcionó cuando aparece [pasta] feito/001-frutas.txt gravado.
git checkout aula5 && mkdir -p entrada echo "Enumera 3 frutas, una por línea." > entrada/001-frutas.txt python3 canal_pasta.py --uma-vez cat feito/001-frutas.txt
Una receta es un archivo de tres líneas en receitas/. Los dos primeros pedidos caen en una receta (sem cérebro); el tercero, abierto, va al cerebro, que pide la herramienta ler. Las recetas del kit están escritas en portugués, así que los dos pedidos exactos ("añade pan integral a la lista" y "¿qué hay en la lista?") van en portugués para que la receta los reconozca; en español irían al cerebro.
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ón el viernes a las 15 h. Llevar el contrato." > trabalho/notas.txt python3 canal_terminal.py "Lee notas.txt y di qué tengo que llevar"
Los bloqueos valen en todos los canales. Para que el bot de Telegram atienda solo a ti, añade el número de tu chat (el que apareció en el paso 4) al .env con >>, que añade sin borrar el token.
git checkout aula7 python3 canal_terminal.py "Recuerda que mi perro se llama Thor" python3 canal_terminal.py "¿Cómo se llama mi perro?" echo "TELEGRAM_DONO=numero-de-tu-chat" >> .env
Primero guarda un archivo de notas en la carpeta trabalho/ (la única que leen las herramientas). Con --esperado, lo comprueba el código; sin él, el juez (el cerebro llamado de nuevo para juzgar; cambia su modelo con MODELO_JUIZ=).
git checkout aula8 && mkdir -p trabalho echo "Reunión con el proveedor el viernes a las 15 h. Llevar el contrato." > trabalho/notas.txt python3 canal_terminal.py "Lee notas.txt y di a qué hora es la reunión" --esperado "15"
Funcionó cuando aparecen [verificador] aprovado · exato: achei "15" y [resultado] sucesso na tentativa 1.
Siete pruebas con un cerebro falso, en la versión principal (necesita pytest).
git checkout main python3 -m pytest -q testes/
Sin promesa de fecha.