12 Factor Agents - 12 Principios para Construir Aplicaciones LLM Confiables

Resumen

12 Factor Agents es una metodología de principios para construir software impulsado por LLM listo para producción, desarrollada por Dex Horthy y el equipo de HumanLayer.

Antecedentes y Motivación

¿Por qué se necesitan estos principios?

Después de hablar con más de 100 constructores de SaaS (principalmente fundadores técnicos), los autores descubrieron que la mayoría del desarrollo de Agentes de IA se encuentra con un "cuello de botella de calidad del 70-80%":

1. Progreso inicial rápido: Alcanzar rápidamente el 70-80% de la funcionalidad utilizando marcos existentes.
2. Cuello de botella de calidad: Descubrir que el 80% no es lo suficientemente bueno para una función orientada al cliente.
3. Limitaciones del marco: Para superar el 80%, es necesario aplicar ingeniería inversa a los marcos, prompts, flujos, etc.
4. Empezar de cero: Finalmente, tener que desechar el marco y empezar de nuevo.

Idea Central

• La mayoría de los "Agentes de IA" exitosos a nivel de producción no son tan "agentes" en realidad.
• Son principalmente sistemas de software cuidadosamente diseñados que utilizan LLM de manera inteligente en puntos clave.
• La forma más rápida de que los clientes utilicen software de IA de alta calidad es adoptar conceptos pequeños y modulares e integrarlos en los productos existentes.

12 Principios Fundamentales

Factor 1: Lenguaje Natural a Llamadas a Herramientas

Natural Language to Tool Calls

La superpotencia central de los LLM es convertir el lenguaje natural en datos estructurados (JSON). Todas las operaciones del Agente deben comenzar con esta transformación fundamental.

// Patrón central
const response = await llm.generateToolCall(userMessage, availableTools);
// response es JSON estructurado, no texto libre

Factor 2: Posee tus prompts

Own your prompts

Trata los prompts como activos de código críticos y versionados, no como entradas de una sola vez.

• Gestiona los prompts en la base de código de la aplicación.
• Soporta pruebas, despliegues y reversiones sistemáticas.
• Asegura consistencia, reproducibilidad y evolución controlada.

Factor 3: Posee tu ventana de contexto

Own your context window

Gestiona de forma proactiva e intencionada la ventana de contexto del LLM.

• Asegura que la ventana de contexto solo contenga información directamente relevante para la tarea actual.
• Poda datos innecesarios para prevenir la "deriva de contexto".
• Mejora el rendimiento del LLM y reduce el uso de tokens.

Factor 4: Las herramientas son solo salidas estructuradas

Tools are just structured outputs

Considera las "herramientas" como JSON estructurado de la salida del LLM y valídalas.

// Las llamadas a herramientas son solo validación de esquema JSON
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Factor 5: Unifica el estado de ejecución y el estado de negocio

Unify execution state and business state

Asegura que el "estado de ejecución" interno del LLM esté sincronizado con el "estado de negocio" real de la aplicación.

• Previene que el LLM opere basándose en información obsoleta o incorrecta.
• Evita alucinaciones u operaciones inválidas.
• Persiste el estado de ejecución junto al estado de negocio.

Factor 6: Lanza/Pausa/Reanuda con APIs simples

Launch/Pause/Resume with simple APIs

Diseña agentes LLM con interfaces de programación claras que soporten la gestión del ciclo de vida.

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Factor 7: Contacta a humanos con llamadas a herramientas

Contact humans with tool calls

Maneja la interacción humana como una llamada a herramienta de primera clase.

• Enruta pasos de alto riesgo para revisión humana.
• La retroalimentación humana se devuelve al sistema como entrada estructurada.
• Flujos de colaboración humano-máquina sin interrupciones.

Factor 8: Posee tu flujo de control

Own your control flow

Mantén el flujo de control en código normal o en tu propio motor de flujo de trabajo.

• Ejecuta un ciclo OODA explícito (Observar-Orientar-Decidir-Actuar).
• Usa heurísticas de convergencia en lugar de prompts anidados.
• Evita que el LLM gestione flujos de control complejos.

Factor 9: Comprime los errores en la ventana de contexto

Compact Errors into Context Window

Comprime la información de error en el siguiente prompt para cerrar el ciclo de retroalimentación.

• Permite que el LLM aprenda y se recupere de los errores.
• Proporciona información de error estructurada.
• Soporta capacidades de auto-reparación.

Factor 10: Agentes pequeños y enfocados

Small, Focused Agents

Construye agentes pequeños y de un solo propósito, en lugar de grandes chatbots monolíticos.

// Buena práctica: Agentes pequeños y enfocados
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Factor 11: Activa desde cualquier lugar, encuentra a los usuarios donde estén

Trigger from anywhere, meet users where they are

Activa los agentes desde donde los usuarios ya están trabajando: CLI, webhook, cron, etc.

• Integración en flujos de trabajo existentes.
• Múltiples mecanismos de activación.
• Puntos de acceso amigables para el usuario.

Factor 12: Haz de tu agente un reductor sin estado

Make your agent a stateless reducer

La aplicación gestiona el estado, el Agente permanece sin estado.

// Patrón de Agente sin estado
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

Patrones de Arquitectura Técnica

Simplificación del Bucle Central

Cada Agente se reduce esencialmente a:

const prompt = "Instrucciones para la selección del siguiente paso";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

Distinción de los DAG Tradicionales

• DAG Tradicional: Los ingenieros de software codifican cada paso y caso de borde.
• Método del Agente: Se le da al Agente un objetivo y un conjunto de transformaciones, permitiendo que el LLM decida la ruta en tiempo real.
• Situación Real: Las implementaciones más exitosas utilizan inteligentemente el patrón de Agente dentro de un DAG determinista más grande.

Escenarios Aplicables

Escenarios Más Adecuados

• Tareas estructuradas que requieren comprensión del lenguaje natural.
• Flujos de trabajo que necesitan colaboración humano-máquina.
• Procesos de negocio complejos de múltiples pasos.
• Entornos de producción que requieren alta fiabilidad.

Escenarios No Adecuados

• Tareas deterministas simples (es mejor escribir código directamente).
• Tareas de misión crítica que requieren 100% de precisión.
• Entornos con recursos extremadamente limitados.

Recomendaciones de Implementación

Adopción Progresiva

1. Empieza pequeño: Elige un principio relevante para un desafío actual.
2. Implementa y observa: Ve los efectos de la mejora.
3. Añade gradualmente: Luego añade otro principio.
4. Optimiza continuamente: Refina y ajusta constantemente.

Pila Tecnológica Recomendada

• Lenguaje: TypeScript (recomendado por los autores, también soporta Python y otros lenguajes).
• Librería clave: BAML (para el análisis de alineación de esquemas).
• Despliegue: Soporta cloud-native y Kubernetes.

Recursos Relacionados

Recursos Oficiales

• Repositorio de GitHub
• Sitio web de HumanLayer
• Blog The Outer Loop

Lectura Adicional

• Building Effective Agents (Anthropic)
• Metodología original de 12 Factor Apps
• Function Calling vs Structured Outputs vs JSON Mode

Resumen

12 Factor Agents ofrece un enfoque sistemático para construir aplicaciones LLM verdaderamente listas para producción. No se trata de construir marcos más mágicos, sino de aplicar mejores prácticas de ingeniería de software a las capacidades de los LLM. Recuerda la idea central: Los Agentes son software, trátalos como software, y te recompensarán con fiabilidad, mantenibilidad y capacidades que tus competidores no podrán igualar.