12 Factor Agents: patrones para agentes que llegan a producción

Agentes como software con decisiones explícitas

El marco 12 Factor Agents de HumanLayer parte de una idea pragmática: un agente de producción suele combinar lógica determinista con pasos de modelo allí donde el lenguaje, la clasificación o la selección de una herramienta aportan valor. No propone eliminar el software tradicional ni adoptar una arquitectura única; ofrece principios para hacer controlable el comportamiento.

En un ciclo acotado, el modelo propone una salida estructurada, el programa valida la propuesta y ejecuta solo capacidades permitidas, y el resultado se convierte en nueva evidencia. El sistema decide cómo manejar errores, límites, estado y condiciones de parada.

Los 12 factores, agrupados por responsabilidad

La guía original enumera estos factores. Agruparlos ayuda a convertirlos en decisiones de diseño:

1. Interfaz y entradas: 1) traducir lenguaje natural a llamadas estructuradas; 2) poseer y versionar los prompts; 3) administrar la ventana de contexto.
2. Herramientas y flujo: 4) tratar las llamadas como salidas estructuradas; 5) unificar estado de ejecución y de negocio; 6) exponer APIs sencillas de lanzar, pausar y reanudar; 7) contactar personas mediante herramientas; 8) conservar el control del flujo en código.
3. Errores y escala: 9) resumir errores para que el modelo pueda recuperarse; 10) preferir agentes pequeños y enfocados; 11) permitir activación desde distintos eventos; 12) modelar al agente como reductor sin estado, con estado explícito fuera del modelo.

Inner loop y outer loop

El inner loop procesa pasos acotados: contexto autorizado, decisión estructurada, validación determinista, ejecución y resultado. El outer loop coordina el proceso de negocio: inicia tareas, persiste estado, aplica timeouts, gestiona reintentos y decide cuándo una persona debe revisar o reanudar.

Pausar no debería ser una excepción improvisada. El sistema puede detenerse antes de una acción sensible, presentar a una persona el contexto y el efecto esperado, y reanudar con la decisión recibida. La aprobación debe corresponder a una acción y versión concretas, no a un permiso abierto para todo el agente.

Controles para que el patrón sea operable

Valida cada salida contra un esquema, aplica permisos en el servicio que realiza la operación, acota el número de pasos y conserva identificadores de ejecución. Para acciones repetibles, diseña idempotencia; para acciones de impacto, pide autorización explícita y registra quién decidió qué.

Los factores son principios de diseño, no una garantía de seguridad ni una receta completa. El sistema debe evaluarse con escenarios representativos, fallos de herramienta, respuestas adversariales, pérdida de sesión y requisitos reales de privacidad y operación.