Agents Lab

Un entorno experimental de ingeniería de software multiagente creado para estudiar orquestación, validación y ciclos de corrección. Agentes de IA especializados llevan un requisito desde el descubrimiento del proyecto hasta la revisión, sobre una copia aislada; lo interesante no son los agentes, sino los controles a su alrededor.

Estado
I+D experimental
Periodo
2026
Stack
Python · FastAPI · WebSocket · React · TypeScript · OpenAI Agents SDK · Playwright

Proyecto propio de I+D: no es un producto, no está listo para producción y no es un desarrollador autónomo. El código fuente es privado y aquí solo se muestran resultados sanitizados. Las corridas y la evidencia pueden revisarse durante una entrevista.

Ver proyecto en vivo ↗

Por qué lo construí

Para aprender, en la práctica, a controlar agentes: cómo coordinar roles especializados, ejecutar un flujo de desarrollo de varios pasos y mantener su estado, ejecutar herramientas de forma segura, validar el trabajo, manejar revisiones, recolectar evidencia y ver dónde fallan los sistemas con agentes.

Pregunta de investigación

No “¿puede una IA escribir código?”, sino: ¿cómo se coordinan varios agentes especializados para que la planeación, la implementación, QA, las correcciones y la revisión formen un flujo de ingeniería controlado?

Los agentes basados en modelos de lenguaje reportan trabajo que no hicieron: un archivo "actualizado" que nunca cambió, pruebas "aprobadas" que nunca corrieron, una revisión escrita sin leer el código.

Un flujo de desarrollo con varios agentes solo sirve si cada afirmación se puede comprobar, si ningún agente puede actuar fuera de su rol y si una corrida no puede ciclarse ni gastar sin límite.

Arquitectura

Cómo avanza una corrida por el sistema

  1. 01Requisito y proyectoCopia aislada
  2. 02DescubrimientoCódigo, no un modelo
  3. 03ArquitectoPropone el diseño
  4. 04PlanificadorTareas ordenadas, criterios de aceptación
  5. 05Tech LeadElige el orden de las tareas
  6. 06DesarrolladorÚnico rol que escribe
  7. 07QAEjecuta pruebas aprobadas
  8. 08RevisorLee, aprueba o rechaza
  9. Ciclos de correcciónUna falla de QA devuelve el trabajo al Desarrollador y QA lo valida de nuevo; un rechazo del Revisor lleva a una corrección y a una nueva revisión. Ambos se detienen en un límite de revisiones.
  10. 09Completado o fallidoLo deciden los controles de evidencia
Ciclos de correcciónUna falla de QA devuelve el trabajo al Desarrollador y QA lo valida de nuevo; un rechazo del Revisor lleva a una corrección y a una nueva revisión. Ambos se detienen en un límite de revisiones.

En todas las etapas

  • Orquestador y estadoImpone el orden de las etapas y guarda el estado de la corrida
  • Ejecución de herramientasCada rol recibe solo sus herramientas; cada llamada emite un evento
  • Presupuestos de solicitudes y tokensSe revisan antes de cada llamada al modelo
  • Aislamiento del espacio de trabajoRutas validadas, sin terminal, comandos de prueba permitidos
  • Recuperación ante fallasLos errores vuelven al agente; los límites cierran la corrida limpiamente
  • Evidencia y eventosCada afirmación se contrasta con la evidencia registrada de las herramientas
  • Validación estática y en navegadorLint, pruebas y build, y verificaciones en un navegador real, por separado
Vista conceptual, simplificada. Las etapas con borde de color son código determinista; las demás son agentes guiados por un modelo. Los ciclos de corrección están disponibles en cada corrida, pero no todas los necesitan.
  • Un núcleo en Python expone APIs REST y WebSocket; una interfaz en React y TypeScript muestra la corrida mientras ocurre.
  • Los agentes corren sobre el OpenAI Agents SDK. El proveedor del modelo está detrás de un adaptador; hoy hay un proveedor operativo.
  • El orquestador es dueño del estado de la corrida y decide qué rol puede actuar. Cada agente recibe solo las herramientas que su rol permite: leer, listar, buscar, escribir o ejecutar pruebas.
  • Cada llamada a una herramienta pasa por un espacio de trabajo aislado y emite un evento. Los eventos van a un almacén, a una proyección y, por WebSocket, a la interfaz.
  • Las verificaciones estáticas (lint, pruebas y build) y las verificaciones en un navegador real con Playwright se ejecutan por separado, sobre el producto que construyó el Desarrollador.
  • Una corrida nunca toca el proyecto original: trabaja sobre una copia aislada.

Roles de los agentes

Descubrimiento
Código determinista, no un agente. Lee manifiestos y documentación y produce un perfil del proyecto para los demás roles.
Arquitecto
Propone el diseño. No puede escribir código.
Planificador
Convierte el diseño en tareas ordenadas, con dependencias y criterios de aceptación.
Tech Lead
Coordina y elige el orden de las tareas. Nunca implementa; el código valida su elección antes de usarla.
Desarrollador
El único rol con permiso de escritura en el espacio de trabajo.
QA
Ejecuta pruebas, solo desde una lista de comandos permitidos definida en código. No puede editar archivos.
Revisor
Solo lectura. Cada hallazgo debe citar texto que existe en el archivo revisado.

Flujo de ejecución

  • Orquestación híbrida: el código impone las invariantes del flujo (el orden de las etapas, qué rol puede actuar, cuándo puede completarse una corrida) y el agente Tech Lead solo propone el orden de las tareas.
  • El estado de cada corrida se guarda, y cada cambio de etapa y cada llamada a una herramienta quedan registrados como eventos, así que una corrida puede revisarse después de terminar.
  • Los presupuestos de solicitudes y de tokens se revisan antes de cada llamada al modelo, así que una llamada que excedería el límite nunca se envía. Cada rol tiene además un límite de turnos, y las revisiones tienen un tope.
  • La ejecución y la presentación están separadas: la interfaz muestra una proyección de los eventos y nunca controla la corrida.

Validación y corrección

Evidencia antes que veredictos

  • Una llamada a herramienta que falla se devuelve al agente como resultado, para que corrija el rumbo en lugar de terminar la corrida.
  • Llegar a un límite de turnos o de presupuesto termina la corrida con una falla estructurada que indica qué límite se alcanzó, en lugar de quedarse colgada o gastar de más.
  • Las fallas de QA y los rechazos del Revisor pueden devolver el trabajo al Desarrollador para corregirlo, hasta un límite de revisiones. La corrida se detiene si las revisiones no avanzan.
  • La falta de evidencia se trata como bloqueo, no como rechazo, así que el Desarrollador nunca es enviado a cambiar código que quizá ya está bien.

Decisión principal

Controles de evidencia, aplicados en código

La primera corrida real falló porque los agentes reportaron trabajo que no habían hecho. La corrección se hizo en el código, no en los prompts. Una tarea solo pasa con evidencia de las herramientas: recibos de escritura con hashes de los archivos para la implementación, una ejecución real de las pruebas cuyo código de salida prevalece sobre el veredicto de QA, y una lectura registrada de cada archivo relevante para la revisión. Un control final verifica que nada cambió después de QA.

  1. Descubrimiento como código determinista

    Entender el proyecto lo hace código que lee manifiestos y documentación, no un modelo. Es predecible, se puede probar y no consume llamadas al modelo.

  2. Una sola pasada conjunta de QA y revisión

    QA y revisión se ejecutan una vez al final de todas las tareas, en lugar de después de cada una, porque las tareas que escriben pruebas dependen de tareas de implementación anteriores.

  3. Límites tomados de corridas reales

    Los límites de turnos se definieron a partir de lo que necesitaron las corridas reales, más un margen, en lugar de adivinarlos.

  4. Sin aprobaciones automáticas

    Una tarea solo puede darse por cumplida de antemano con una razón explícita y evidencia real.

Lo que he aprendido

  • Un falso PASS es la falla que más importa: una corrida que reporta éxito sobre trabajo roto es peor que una que se detiene. Los controles de evidencia existen por eso.
  • La falla contraria también importa. En las campañas del benchmark, la mayoría de las corridas fallidas fueron falsos FAIL: productos correctos que el propio QA en navegador del sistema rechazó.
  • La evidencia estática y la evidencia en navegador son cosas distintas. Una corrida cuyas pruebas pasaron podía fallar en el build y mostrar una página en blanco, así que el lint, las pruebas, el build y las verificaciones en navegador se juzgan por separado.
  • Los errores de herramientas y de QA deben ser recuperables: volver al agente como información, no terminar la corrida.
  • La portabilidad es parte de la confiabilidad. Ejecutar los comandos de prueba de un proyecto en Windows requirió su propia corrección.
  • Los ciclos de corrección necesitan un límite y una noción de avance, o giran sin mejorar nada.
  • La mayoría de los modos de falla de la orquestación, como roles que se quedan sin turnos, solo aparecieron en corridas reales, no en el diseño ni en pruebas con un modelo simulado.
  • El QA visual y en navegador es lo más difícil de volver determinista. Los cambios más recientes compilan las verificaciones de navegador a partir del plan, en lugar de dejar que QA las escriba.
  • Solo una validación fuera del sistema, con un verificador independiente, hace creíble un resultado.

Trade-offs

  • La orquestación híbrida le da al Tech Lead menos autonomía que una corrida manejada por completo por agentes, a cambio de invariantes que ningún agente puede evadir argumentando. También se construyeron un pipeline determinista y un modo manager; el híbrido es el predeterminado.
  • Los controles de evidencia son estrictos: una corrida puede detenerse por falta de evidencia aunque el trabajo estuviera bien. Se prefiere eso a aceptar afirmaciones que no se pueden verificar.
  • Una pasada conjunta de QA y revisión mantiene simples las dependencias entre tareas, pero un problema se detecta más tarde y puede costar una revisión más grande.
  • Los presupuestos y límites de turnos estrictos protegen el costo y evitan ciclos, pero un límite demasiado bajo detiene una corrida legítima. Eso pasó en un proyecto más grande.
  • Las tareas se ejecutan una a la vez: el estado y la evidencia son más fáciles de razonar, a costa de velocidad.
  • Sin terminal y con comandos de prueba permitidos, la ejecución es más segura, pero QA solo puede ejecutar lo que se configuró.

Límites actuales

  • El QA en navegador todavía rechaza trabajo correcto con demasiada frecuencia; es el principal problema abierto.
  • Solo hay un proveedor de modelos operativo.
  • Es una herramienta de un solo usuario que corre en una máquina local, sin autenticación.
  • Una corrida interrumpida no puede reanudarse, las tareas se ejecutan una a la vez y no hay integración con git.

Estado actual de I+D

  • I+D experimental: un laboratorio para estudiar orquestación, validación y ciclos de corrección. No ha cumplido sus propios criterios de graduación y no está listo para producción.
  • Se mide con un Basic Capability Benchmark: nueve tareas pequeñas en tres niveles, cada una verificada por un verificador independiente. Graduarse requiere al menos dos de tres tareas por nivel, cero falsos PASS y al menos un ciclo de corrección exitoso.
  • Las corridas del benchmark han expuesto límites reales de QA y de orquestación, sobre todo falsos FAIL: productos correctos que el QA en navegador del sistema rechazó. Los cambios que se hicieron en respuesta, verificaciones de navegador deterministas y control de costos, todavía no se han medido con el benchmark.
  • Antes, una corrida real de punta a punta sobre un proyecto pequeño existente se completó y una verificación independiente la confirmó después. Las corridas sobre un proyecto real más grande han llegado a QA, pero no se han completado.

Proyecto en vivo

El sitio público es una reproducción de solo lectura de una corrida real grabada, una tarea pequeña del benchmark que el sistema completó. Los agentes no se están ejecutando en vivo y la página no llama a ningún modelo.

agentslab.abrahamguerra.dev

Ver proyecto en vivo ↗