Agents Lab
Un sistema de I+D que orquesta agentes de IA especializados en un flujo de desarrollo de software, desde el descubrimiento del proyecto hasta la revisión, sobre una copia aislada de un proyecto existente. Lo interesante no son los agentes, sino las garantías a su alrededor.
Proyecto propio de I+D; no es un producto ni está listo para producción. El código fuente es privado y aquí solo se muestran resultados sanitizados. Las corridas y la evidencia pueden revisarse durante una entrevista.
Problema
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.
Mi rol
Proyecto propio. Definí el problema, el flujo, los límites de cada rol y las garantías que impone el sistema, construí el sistema y ejecuté las corridas reales de validación. Las decisiones de abajo son mías.
Arquitectura
Cómo avanza una corrida por el sistema
- 01Proyecto existenteCopia aislada
- 02DescubrimientoCódigo, no un modelo
- 03ArquitectoPropone el diseño
- 04PlanificadorTareas ordenadas, criterios de aceptación
- 05Tech LeadElige el orden de las tareas
- 06DesarrolladorÚnico rol que escribe
- 07QAEjecuta pruebas aprobadas
- 08RevisorLee, aprueba o rechaza
- Ciclo de correcciónQA o el Revisor pueden devolver el trabajo al Desarrollador para corregirlo, hasta un límite de revisiones.
- 09CompletadoSolo con controles de evidencia
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
- 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.
- Una corrida nunca toca el proyecto original: trabaja sobre una copia aislada.
Límites de cada agente
- 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.
Orquestación y estado
- 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.
Recuperación ante fallas y ciclos de corrección
- 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.
Decisiones de arquitectura clave
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.
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.
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.
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.
Sin aprobaciones automáticas
Una tarea solo puede darse por cumplida de antemano con una razón explícita y evidencia real.
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ó.
Validación y evidencia
Fuera de línea, suites de pruebas automatizadas ejercitan la orquestación, las herramientas y el ejecutor de pruebas reales con un modelo simulado. La evidencia que importa es una corrida real sobre un proyecto existente:
- Llamadas reales a un modelo de lenguaje, sin simulaciones.
- Descubrimiento real del proyecto existente.
- Modificación real de archivos por parte del Desarrollador.
- Ejecución real de las pruebas de QA.
- Una revisión real que aprobó el cambio.
- Recuperación ante un error real de herramienta durante la corrida.
- Ejecución de punta a punta que llegó a RUN_COMPLETED.
Una verificación independiente posterior repitió las pruebas y las verificaciones funcionales fuera del sistema y confirmó que el cambio solo tocó los archivos esperados.
Esa corrida no necesitó un ciclo de corrección. Los ciclos de QA y revisión están implementados, y las corridas reales los han ejercitado solo en parte.
Las corridas reales anteriores fallaron. Esas fallas son las que llevaron a los controles de evidencia y a los límites de turnos.
Límites actuales
- Hasta ahora, las corridas reales exitosas son sobre un proyecto pequeño y controlado. Un piloto sobre un monorepo real se detuvo en la etapa de arquitectura: el descubrimiento solo revisa un nivel de profundidad y el Arquitecto se quedó sin turnos.
- Solo hay un proveedor de modelos operativo.
- Una corrida interrumpida no puede reanudarse, las tareas se ejecutan en secuencia y no hay integración con git.
- Es una herramienta de un solo usuario que corre en una máquina local, sin autenticación.