Kit del curso Agente por piezas · Python puro · cerebro con tu suscripción

Tu agente solo dice listo después de comprobar

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.

Banner Agente por piezas: tu agente atiende en Telegram y solo dice listo después de comprobar
En resumen

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.

Seis tarjetas: el mapa de las piezas, chat en una página, Telegram, robot de la carpeta, receta sin IA y verificador que cancela

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.

Video

Entiéndelo en 3 minutos

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

▶ Ver en YouTube

Las piezas

Un agente está hecho de piezas, y cada una es un archivo

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.

Canal→Caja→Receta o Cerebro→Herramientas→Verificador→Resultado

💬 Canal

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.

📦 Caja

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.

🧠 Cerebro

El modelo que piensa: el Codex de tu suscripción. Solo decide y pide; no abre ningún archivo por su cuenta.

📋 Recetas

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.

🛠️ Herramientas, memoria y reglas

Lo que el agente puede hacer (leer, guardar, anotar, recordar cosas de ti) y lo que no puede, bloqueado en el código.

🔍 Verificador

Compara el resultado con el pedido. Con un ejemplo concreto, lo comprueba el código; sin ejemplo, un juez. Si reprueba 3 veces, cancela.

Lo que se probó

Tres momentos reales, tal como salieron en la terminal

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.

Receta: sin IA

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é

El agujero y el bloqueo

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 trabalho

Cancela en lugar de inventar

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

Ocho clases, una pieza a la vez

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.

Clase 1
El mapa y el objetivoLa diferencia entre el chat y un agente, y lo que tu agente hace, lo que no hace y cuándo está listo.
Clase 2
Caja y cerebroEl primer pedido: la caja llama al Codex de tu suscripción.
Clases 3–5
Los canalesUn chat en una página, Telegram y una carpeta donde el robot trabaja sin conversación.
Clase 6
Recetas y herramientasEl pedido exacto va a la receta; el abierto va al cerebro, que pide herramientas.
Clase 7
Memoria y reglasLo que recuerda de ti y los bloqueos que valen aunque engañen al modelo.
Clase 8
Verificador y bucleAprueba, lo intenta de nuevo o cancela, y por qué un ejemplo concreto vale más que un juez.

Abrir el curso (en portugués)

Palabras de esta página

Si algún nombre es nuevo para ti

Agente
Un programa con IA que recibe un pedido, hace la tarea y la comprueba, en lugar de solo responder con texto.
Codex
La herramienta de OpenAI que funciona en la terminal y usa tu suscripción de ChatGPT. Aquí es el cerebro.
Clave de API
Una contraseña para pagar el uso de un modelo por fuera de la suscripción. El kit no la usa.
RPA
Un robot que sigue pasos fijos. Las recetas del kit son eso.
Tag
Una marca de versión en git. git checkout aula2 cambia los archivos a la versión de la clase 2.
Terminal
La ventana donde escribes comandos. En Windows, usa WSL, que es un Linux dentro de Windows.
Bot de Telegram
Una cuenta de Telegram controlada por un programa. Creas la tuya en @BotFather.
Token
La clave de tu bot. Quien tiene el token controla el bot: queda en un archivo fuera del código.
Juez
Cuando el pedido no trae un ejemplo concreto, se llama de nuevo al cerebro, esta vez para juzgar si el resultado cumple el pedido.
Ollama y llama3.2
Un programa que ejecuta modelos de IA en tu computadora, y uno de esos modelos. Son opcionales.
npm y Node.js
Node.js es un programa que ejecuta herramientas hechas en JavaScript; npm viene incluido e instala esas herramientas, como el Codex.
.env
Un archivo de secretos (como el token) que queda solo en tu computadora, fuera de git.
gpt-6-luna
El nombre del modelo del Codex que el kit usa por defecto, dentro de tu suscripción.
Clone y pytest
Clonar es descargar una copia del repositorio con git. pytest es la herramienta que ejecuta las pruebas.
Parte técnica

El kit: para quien quiere ejecutar, cambiar o estudiar el código

No necesitas esta parte para entender lo que está arriba.

Qué es el kit

Python puro, un tag por clase, pruebas sin modelo

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.

PiezaArchivo
Canalcanal_terminal.py, canal_web.py + chat.html, canal_telegram.py, canal_pasta.py
Cajacaixa.py
Cerebrocerebro.py (Codex) · cerebro_local.py (Ollama, con CEREBRO=local)
Recetasreceitas.py + receitas/*.txt
Herramientas y reglasferramentas.py + regras.md
Memoriamemoria.json (nace cuando el agente recuerda la primera cosa)
Verificador y bucleverificador.py + el bucle en caixa.py
Requisitos previos

Lo que necesitas

Telegram y Ollama son opcionales.

Terminal, Python y git

Linux o Mac (en Windows, WSL), Python 3 y git.

python3 --version
git --version

Codex

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

Opcionales

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
Guía de uso · paso a paso

Del clone al verificador

Los comandos son los del repositorio. El curso (en portugués) explica cada paso con flujo, práctica y prueba.

1

Descarga el kit

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
2

El primer pedido (clase 2)

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

Chat en una página (clase 3)

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
4

Telegram (clase 4)

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
5

Carpeta, sin conversación (clase 5)

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
6

Recetas y herramientas (clase 6)

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

Memoria y reglas (clase 7)

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
8

Verificador (clase 8)

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.

9

Pruebas sin modelo

Siete pruebas con un cerebro falso, en la versión principal (necesita pytest).

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

Dónde está el kit

Sin promesa de fecha.

Hecho
Un agente, cuatro canalesLas ocho versiones del curso, con salidas reales capturadas y pruebas sin modelo.
Idea
Varios agentesUn agente gerente que divide el pedido entre otros agentes y comprueba el conjunto al final.