12-factor-agents: Los doce principios que tu agente IA debe cumplir antes de tocar producción.

Los doce principios que tu agente IA debe cumplir antes de tocar producción.

Sin commits desde septiembre 2025, pero sigue siendo lectura obligada cada vez que alguien arma un agente real. Es la versión 12-factor-app del mundo de LLMs, cómo manejar contexto, errores, memoria y costos sin que se caiga en producción.

Estrellas

22k★

Lenguaje

TypeScript

Principios

Revisado

22 may 2026

De un vistazo, lo que vas a obtener si lo instalas.

Reference standard del espacio

Se cita cada vez que sale un agente nuevo serio en HackerNews o LinkedIn. Es el manifiesto del momento.

Manejo de contexto

El factor 3 (own your context window) es de los más importantes y el más ignorado. Explica cómo evitar que el contexto explote.

Errores y reintentos

Cómo el agente falla bonito en lugar de colgarse o devolver basura cuando algo sale mal.

Cost control desde el diseño

Patrones para que el costo por petición sea predecible, no una sorpresa mensual.

Listo para producción

Diseñado para clientes reales y SLAs reales, no para demos.

El contexto detrás del repo.

Cuando Heroku publicó "The Twelve-Factor App" en 2012, marcó el estándar de cómo se hablaba de software-as-a-service. No era un framework ni una librería: era un manifiesto de principios destilados de la experiencia operando productos reales. Cualquier conversación seria sobre arquitectura cloud-native referencia esos 12 factores.

Dex (autor del repo, viene de humanlayer.dev) intenta lo mismo para agentes IA. Después de "probar todo framework de agentes que existe" —de los plug-and-play tipo crewAI hasta los minimalistas como smolagents— destila 12 principios que cualquier agente listo para producción debería cumplir: manejo del context window, errores y reintentos, memoria, herramientas, deployment, cost control.

No es código instalable, es un repo de documentación técnica densa con ejemplos. El proyecto está "stale" en commits (último cambio importante en septiembre 2025) pero sigue sumando estrellas porque la referencia no caduca. Cada vez que sale un agente nuevo en HackerNews, alguien cita estos 12 factores en los comentarios.

Cuándo lo recomiendo (y cuándo no).

Lo recomiendo como lectura obligada para cualquiera que esté construyendo agentes para producción. Si tu equipo está pasando del prototipo al despliegue, este documento es el filtro antes de mandar a clientes — si tu agente no cumple los 12 factores, no está listo.

No lo confundas con un framework. No vas a instalar nada, vas a leer y aplicar. Los principios son agnósticos de stack: aplican igual a LangChain, a un agente custom en TypeScript, a una integración con Claude Code, a Hermes. La universalidad es lo que le da valor.

En 3 pasos, listo para probar.

Léelo. Empieza por la introducción.

# No hay install. Es documentación.
open https://github.com/humanlayer/12-factor-agents

Es un repo de markdown. La estructura está pensada para leer en orden o saltar a un factor específico. La intro y los primeros 3 factores (especialmente factor 3 — own your context window) son los más densos en valor inmediato.

Aplica el checklist a tu agente actual

Toma tu agente o el de tu equipo y pasa cada uno de los 12 factores como pregunta — "¿cumplimos esto?". Cualquier factor donde la respuesta sea "no" o "no estoy seguro" es probablemente lo que va a fallar primero en producción.

Vuelve cuando construyas algo nuevo

La utilidad real del repo es ser referencia. La primera vez lo lees completo. Las siguientes vas a un factor específico cuando enfrentas una decisión de diseño.

Por qué este repo no caduca aunque esté stale

La mayoría del contenido sobre agentes envejece rápido. Cada mes sale un framework nuevo, una API nueva, un patrón nuevo. Lo que escribiste hace 6 meses puede ser obsoleto.

Los 12 factores son distintos porque atacan principios, no tecnologías. "Own your context window" sigue siendo cierto sin importar si usas Claude, GPT, Gemini o un modelo open-weight. "Failure isolation" aplica igual a un agente en TypeScript que a uno en Python. Por eso sigue sumando estrellas aunque el repo no haya tenido commits importantes en meses.

Los factores que más se ignoran

Tres factores que en mi experiencia los equipos saltan más seguido:

Factor 3 — Own your context window. Casi todo el mundo deja que el contexto crezca sin gestión. Cuando explota, es un problema operativo grande.
Factor 8 — Stateless tools. Las herramientas que tu agente llama no deberían depender de estado compartido entre llamadas. Si lo hacen, debug se vuelve infierno.
Factor 12 — Cost as a first-class metric. Pocos equipos miden costo por interacción desde el día uno. La factura sorpresa llega después.

Mi recomendación

Si construyes agentes, léelo este fin de semana. Toma una tarde. Vale más que 90% de los blogposts sobre el tema. Y si lideras un equipo que está construyendo agentes, compártelo como reading obligatorio antes de la próxima review de arquitectura.