Skip to content

English · Español

Fase 32 — Agentes: planificación, memoria, sandboxing (aplicación capstone)

Requiere: 29 — Retrieval-Augmented Generation (RAG) · 31 — Uso de tools y el Model Context Protocol (MCP) Enseña: agents · react-loop · planning · agent-memory · sandboxing Salta a cualquier capítulo desde el índice de referencia de fases.

Mapa del capítulo

🇪🇸 La fase capstone. Aquí el modelo (Fases 17–22), las herramientas (Fase 31), el decoding restringido (Fase 30) y el RAG (Fase 29) se juntan para formar un tutor de gramática que corrige oraciones inglesas y, cuando procede, glosa la forma corregida en español. No es un toy demo: es el producto del libro.

Referencias: LYNX_CORTEX.md §4 / PHASE 32, PHASE_32_PLAN.md, LYNX_CORTEX_ADDENDUM.md §A13 (el marco del tutor de gramática).

Por qué existe esta fase

Las treinta y una fases anteriores convergen aquí. La Fase 17 nos dio la arquitectura del modelo; las Fases 18–22 lo entrenaron y lo sirvieron; la Fase 28 lo afinó (fine-tuning) para seguir instrucciones; la Fase 30 hizo que emitiera salida estructurada; la Fase 31 lo cableó a herramientas vía MCP. La Fase 32 pone todo esto en un loop cerrado con un planificador (planner), scratchpad, memoria persistente y un sandbox — es decir, convierte un modelo en un agente.

El producto capstone es un tutor de gramática: lee una frase en inglés, identifica el verbo y el sujeto inferido, invoca un conjunto pequeño de herramientas (búsqueda de forma verbal, comprobación de concordancia, clasificador de regularidad), produce una corrección estructurada y — cuando la forma corregida difiere de la original — proporciona una glosa en español. Según LYNX_CORTEX_ADDENDUM.md §A13, esta es la aplicación que define el proyecto.

Qué construirás

                                                  ┌─────────┐
                                                  │ Memory  │
                                                  │ (long)  │
                                                  └────▲────┘
                                                       │
   User sentence                                       │
        │                                              │
        ▼                                              │
   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──┴────┐
   │  Agent   │───▶│ Planner  │───▶│ Tool via │───▶│ Scratch │
   │  (loop)  │◀───│ (masked) │◀───│   MCP    │◀───│   pad   │
   └──────────┘    └──────────┘    └──────────┘    └─────────┘
        │                                              │
        ▼                                              │
   Correction                                          │
   (structured)                                        ▼
                                                  ┌─────────┐
                                                  │ Sandbox │
                                                  │ policy  │
                                                  └─────────┘

Cinco componentes, todos en src/miniagent/:

  • agent.py — GrammarTutorAgent, el orquestador. Contiene el loop.
  • planner.py — planificador con generación enmascarada. Emite ToolCall o FinalAnswer.
  • memory.py — ScratchpadMemory (por corrección) + LongTermMemory (entre correcciones).
  • sandbox.py — enum SandboxPolicy + un envoltorio run_under_sandbox.
  • types.py — los dataclasses que circulan por el loop.

El entregable es: el agente corrige ≥ 90 % de las 30 frases canónicas de prueba.

Archivos

phase-32-agents/
├── README.md                          # este archivo
├── theory/
│   ├── 00-motivation.md              # qué es un agente, qué no lo es
│   ├── 01-react-and-planning.md      # ReAct, plan-and-execute, planificadores restringidos
│   ├── 02-memory.md                  # scratchpad vs long-term; qué persistir
│   └── 03-sandboxing.md              # subprocess, rlimits, política de red
├── lab/
│   ├── 00-planner-by-mask.md         # implementa el planner bajo JSONSchemaMask
│   ├── 01-tutor-end-to-end.md        # ejecuta sobre 30 frases canónicas
│   ├── 02-sandbox-an-evil-tool.md    # demuestra contención
│   └── 03-failure-mode-tour.md       # induce + diagnostica 4 modos de fallo clásicos
├── solutions/                         # se rellena al abrir la fase; NO leer antes
├── notebooks/
└── diagrams/                          # bucle ReAct, ciclo de vida del scratchpad, histograma de pasos

Lo que esta fase NO cubre

  • Diálogo multi-turno. El tutor de la Fase 32 es de un solo turno (correct(sentence) → correction). El multi-turno vive en una futura fase de "conversación" que no está en la hoja de ruta de 40 fases.
  • Autenticación de usuario. La capa HTTP de la Fase 33 añade sesiones. La LongTermMemory de la Fase 32 indexa por un nombre de aprendiz codificado a mano (borja).
  • Entrenamiento de herramientas / fine-tuning para uso de herramientas. Las herramientas se cablean mediante generación estructurada (Fase 30) y MCP (Fase 31), no se aprenden. Un agente real de producción podría hacer fine-tuning sobre trazas de tool calling; la Fase 32 no lo hace.
  • Sistemas multi-agente. Un solo agente, un modelo, un planificador. La orquestación multi-agente (debate, supervisor-worker) es interesante y queda fuera de alcance.
  • Recuperación con base de datos vectorial dentro del loop del agente. La Fase 29 (RAG) es una herramienta batch que el agente puede invocar, no la memoria central del agente. La memoria propia del agente es estructurada y pequeña.

Lista de comprobación de apertura de fase (según CLAUDE.md §1)

  1. Releer PHASE_32_PLAN.md §§0–8.
  2. Releer LYNX_CORTEX_ADDENDUM.md §A13 — el conjunto de verbos §A13 y la especificación del tutor.
  3. Releer la Fase 30 (generación estructurada) y la Fase 31 (MCP) — la Fase 32 se construye directamente sobre ambas.
  4. Ejecutar las herramientas de la Fase 31 para confirmar que aún funcionan de extremo a extremo (sanity check).
  5. Abrir src/miniagent/BLUEPRINT.md — la sección de añadidos de la Fase 32 ya debería estar redactada; revísala antes del código.

Una nota sobre el hype de "agente"

La palabra "agente" carga mucho peso de marketing. Para este proyecto, un agente es precisamente: un loop alrededor de un modelo que mantiene estado, invoca herramientas y termina. Nada más. No hay reclamo implícito de "inteligencia" o "autonomía" más allá de lo que el loop y las herramientas proporcionan. El tutor de gramática §A13 es un agente perfectamente respetable que hace exactamente una cosa bien.

Este encuadre importa porque el anti-objetivo §10 de LYNX_CORTEX.md (en la raíz del repo) excluye langchain / llama-index — esas librerías empaquetan el loop en una abstracción opaca. La Fase 32 construye el loop a mano, para que Borja pueda leer el código fuente de cualquier framework de agentes y reconocer las piezas en movimiento.

Siguiente: theory/00-motivation.md

Lecturas recomendadas

Opcional — enriquece pero no es necesario para aprobar la fase.