Agentes de 12 factores: patrones para aplicaciones LLM confiables

 (github.com/humanlayer)
1 puntos por GN⁺ 2025-04-17 | 1 comentarios | Compartir por WhatsApp
  • 12-Factor Agents es una guía abierta que reúne 12 principios para crear software basado en LLM lo suficientemente confiable como para ofrecerlo a clientes en producción.
  • Plantea que un buen agente no se parece tanto a “darle un prompt y un conjunto de herramientas para que itere hasta alcanzar un objetivo”, sino más bien a una estructura en la que la mayor parte es software determinista con pasos de LLM insertados donde hacen falta.
  • Un loop típico de agente hace que el LLM decida el siguiente paso como una llamada estructurada a herramientas en JSON; luego código determinista la ejecuta, agrega el resultado a la ventana de contexto y repite hasta completar la tarea.
  • Según la guía, muchos creadores de SaaS empiezan rápido con un framework y llegan a una calidad del 70–80%, pero eso no alcanza para funciones de cara al cliente, por lo que terminan haciendo ingeniería inversa del framework, los prompts y el flujo, o empezando de nuevo desde cero.
  • La forma más rápida de entregar software de IA de alta calidad a clientes no es adoptar un framework completo de agentes, sino integrar conceptos pequeños y modularizados de construcción de agentes en el producto existente.

El problema que aborda el proyecto

  • 12-Factor Agents es un proyecto abierto que busca aplicar el espíritu de 12 Factor Apps a los principios para construir aplicaciones LLM.
  • La pregunta central es: “¿Qué principios podemos usar para crear software basado en LLM que sea realmente bueno y lo bastante confiable como para ponerlo en manos de clientes en producción?”.
  • Parte de la experiencia de probar diversos frameworks de agentes y conversar con fundadores técnicos dentro y fuera de YC.
    • Muchos fundadores están construyendo su propio stack en lugar de usar intensivamente frameworks para agentes de cara al cliente en producción.
    • Considera que muchos productos llamados “AI Agent” no son completamente agénticos, sino que en su mayoría combinan código determinista con pasos de LLM en los puntos adecuados.

Perspectiva básica sobre los agentes

  • Un buen agente no se compone solo del patrón “prompt, conjunto de herramientas e iteración hasta alcanzar el objetivo”.
  • El software puede verse como un grafo dirigido (DG), y esa es también la razón por la que antes se representaban los programas como diagramas de flujo.
  • Desde hace unos 20 años se empezaron a usar ampliamente los orquestadores DAG.
    • Como ejemplos se mencionan Airflow, Prefect, dagster, inggest y windmill.
    • Siguen un patrón de grafos al que agregan observabilidad, modularidad, reintentos y capacidades de administración.
  • La promesa de los agentes es que, en lugar de que el ingeniero codifique todos los pasos y excepciones, solo proporcione el objetivo y las transiciones, y que el LLM decida la ruta en tiempo real.
    • Este enfoque genera la expectativa de escribir menos código, recuperarse de errores y permitir que el LLM encuentre soluciones nuevas.
    • Pero en la práctica, considera que este enfoque no funciona tan bien como se espera.

Modelo de ejecución del loop de agente

  • El loop básico de un agente se compone de juicio del LLM → ejecución de herramienta → agregar resultado al contexto → repetición.
  • El flujo es el siguiente:
    • El contexto inicial es un evento de inicio, como un mensaje del usuario, una ejecución de cron o un webhook.
    • El LLM decide el siguiente paso o si la tarea está completa.
    • El siguiente paso se emite como una llamada a herramienta en formato JSON estructurado.
    • Código determinista ejecuta la llamada a la herramienta.
    • El resultado de la ejecución se agrega a la ventana de contexto.
    • Si el siguiente paso es done, se devuelve la respuesta final.
  • El ejemplo del README muestra un loop que determina el siguiente paso con llm.determine_next_step(context), lo ejecuta con execute_step(next_step) y luego adjunta el resultado al contexto.

Por qué hacen falta 12 principios

  • Mientras construía HumanLayer, el autor conversó con al menos 100 creadores de SaaS, en general fundadores técnicos que buscaban hacer que sus productos existentes fueran más agénticos.
  • El recorrido típico es el siguiente:
    • Deciden construir un agente.
    • Definen el diseño del producto, el mapeo de UX y el problema a resolver.
    • Para avanzar rápido, eligen un framework específico.
    • Llegan a un nivel de calidad del 70–80%.
    • Se dan cuenta de que una calidad del 80% no es suficiente para la mayoría de las funciones de cara al cliente.
    • Para superar ese 80%, deben hacer ingeniería inversa del framework, los prompts, los flujos, etc.
    • Al final, empiezan de nuevo desde cero.
  • Esta crítica no pretende atacar a los frameworks ni a sus creadores, y se aclara que los frameworks han acelerado el ecosistema de IA.
  • No aborda MCP; los ejemplos usan principalmente TypeScript, pero se afirma que también pueden aplicarse en Python u otros lenguajes.

Los 12 factores

Forma de aplicación y materiales relacionados

  • Considera que adoptar un framework completo y terminar prácticamente en una reescritura greenfield puede ser contraproducente.
  • Aunque al adoptar un framework se pueden obtener la mayoría de los principios clave que hacen bueno a un agente, el camino para entregar rápidamente software de IA de alta calidad a clientes es integrar conceptos más pequeños y modularizados en el producto existente.
  • Señala que estos conceptos modulares también pueden ser definidos y aplicados por ingenieros de software experimentados sin experiencia previa en IA.
  • Como materiales relacionados se enlazan Building Effective Agents de Anthropic, Prompts are Functions, Library patterns: Why frameworks are evil y The Wrong Abstraction, entre otros.
  • El contenido y las imágenes se ofrecen bajo licencia CC BY-SA 4.0, y el código bajo licencia Apache 2.0.

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-04-17
Comentarios de Hacker News

  • Los puntos de este artículo son excelentes. También hay una lista de lecciones aprendidas tras varios años haciéndolo en la práctica: https://mg.dev/lessons-learned-building-ai-agents/
    Si tuviera que agregar algo importante hoy, sería adueñarte del bucle de planificación del nivel más bajo. La planificación dinámica está bien, pero hay que tener tu propio bucle de observar-evaluar-decidir-actuar (OODA), además de heurísticas para determinar si está convergiendo hacia una solución (por ejemplo, puntuación) o condiciones de salida (por ejemplo, número máximo de iteraciones)
    También valdría la pena considerar meter un motor de workflows. En vez de hacer que el modelo mantenga y avance un workflow implícito a lo largo de varios turnos, es mejor que el modelo genere una especificación de workflow para que se ejecute en ese motor, y volver a invocar al modelo en cada etapa si hace falta

    • Esta guía está buena, y en particular coincido con la idea de que “las interfaces de chat son tontas”. Las UI impulsadas por IA todavía están muy verdes

  • Me pregunto cómo encajan librerías como DSPY con el factor 2: https://dspy.ai/, https://github.com/humanlayer/12-factor-agents/blob/main/con...
    Mientras leía, vi que mencionaban generar prompts con BAML. Personalmente, nunca me resultó fácil escribir a mano prompts para extraer información estructurada de datos no estructurados, y hasta ahora he tenido bastante buenas experiencias con DSPY
    Si usan los prompts crudos de BAML, me interesa saber qué opinan del enfoque de usar prompts crudos en DSPY: https://dspy.ai/tutorials/observability/#using-inspect_histo...

    • Interesante, pero en esta parte coincido más con la postura de Boundary (YC W23). Si quieres rendimiento de punta, necesitas poder abrir la caja y modificar el interior tú mismo
      No coincido del todo con este artículo, https://www.chrismdp.com/beyond-prompting/, pero la comparación de tarjetas perforadas → ensamblador → C → lenguajes de alto nivel sirve bastante aquí
      Todavía no sé cuándo aparecerán las abstracciones adecuadas, y no creo que LangChain o DSPY sean todavía el “lenguaje de programación C” de la IA. Tal vez algún día lo sean
      Por ahora, yo usaría un banco de trabajo de bajo nivel donde pueda inspeccionar tokens, cambiar el orden de tokens especiales como system/user/JSON, y ajustar rápido las rarezas de los modelos nuevos sin quedar atado mientras espero soporte de una librería

  • Hay un artículo viejo, conocido pero no tanto, sobre patrones de frameworks que me ha resonado durante toda mi carrera, y creo que también aplica aquí: https://tomasp.net/blog/2015/library-frameworks/
    Con los LLM, por las razones que explica el artículo y más aún, especialmente en una etapa como la actual donde todo cambia rápido, es mejor usarlos como librerías que como frameworks. Pero los frameworks son más sexys y más fáciles de vender, y como llevan al lock-in y a servicios adicionales, se promocionan más

    • Esta analogía está muy buena. Un tour paquetizado es como comprar un framework: transporte, hotel, comida y actividades quedan dentro del molde que te da el framework. En cambio, viajar por libre es como combinar varias librerías: tienes que armar tú mismo vuelos, hospedaje e itinerario, y aunque da más trabajo, te deja controlarlo todo a tu manera
    • Buen punto. Lo voy a agregar a la sección de enlaces

  • Hicimos público hace poco nuestro propio “framework de agentes de IA”, SecAI, construido sobre el modelo de actores, máquinas de estado y programación orientada a aspectos: https://github.com/pancsta/secai
    En particular me gustaron el punto 5, “unifica el estado de ejecución y el estado de negocio”, y el 8, “adueñate del flujo de control”. El núcleo de SecAI es una librería de flujo de control basada en grafos; usa multigrafos en lugar de DAG, y las llamadas al LLM vienen integradas en los nodos del grafo
    Los flujos se refuerzan con negociación, cancelación y relaciones con estado para funcionar de forma más orgánica. También incluye herramientas de desarrollo dedicadas que suelen faltar en otros frameworks (dbg, repl, svg), programación asumiendo fallas, inspección detallada de cada paso, exportación automática de datos (métricas, trazas, logs, SQL) e integraciones simples (bash)
    También publicamos la primera demo técnica, que muestra las herramientas de desarrollo con una implementación de referencia de deepresearch portada desde AtomicAgents: https://youtu.be/0VJzO1S-gV0
    Los botones Send/Stop son, en la práctica, “Factor 6. iniciar/pausar/reanudar con una API simple”, y además tiene transparencia de red, así que escala

    • Coincido en que a otros frameworks a menudo les faltan herramientas de desarrollo dedicadas. Por lo que he probado, PydanticAI resolvió muy bien la depuración de agentes con Logfire, y fue mucho más fácil y efectivo que otros frameworks y librerías que evalué: https://ai.pydantic.dev/logfire/#pydantic-logfire
    • Me gusta la UI de terminal y la integración con OTel. Me da curiosidad en qué tipo de trabajo lo están usando ahora

  • Yo agregaría una más: hay que planificar el costo cuando esto escale
    Estos sistemas no salen baratos cuando crecen, así que si alguna tarea puede resolverse con un componente determinista, conviene intentar eso primero. No solo reduce alucinaciones y latencia, también puede marcar una gran diferencia en la rentabilidad final

    • Totalmente de acuerdo. El patrón más común que veo es: “al principio arrancas con algo lento y caro pero que requiere poco esfuerzo de desarrollo, y luego vas optimizando gradualmente cuando detectas cuellos de botella de velocidad, calidad o costo en los que sí vale la pena invertir”

  • Para que sea más fácil seguir cada principio, estaría bueno tener una narrativa consistente que cruce varios factores. Si se usara de forma continua un ejemplo de sistema cercano a la realidad, creo que sería más fácil de entender

    • Buen feedback. Me pregunto qué tipo de caso de uso sería adecuado
      Me gustaría seguir desarrollándolo en público junto con la comunidad

  • Excelente. Ya aprendí el 80% a las malas, y el 20% restante parece valer la pena leerlo
    En lo personal, me ha funcionado la combinación de LangGraph + esquemas de pydantic. También me da curiosidad qué otras herramientas le han resultado útiles a los demás

  • Este artículo salió justo cuando lo necesitaba
    Estoy experimentando con una idea de sandbox audiovisual. Es algo como vvvv, pero mucho más simple y con funciones mínimas: https://kfs.mkj.lt/#audiovisllm, https://vvvv.org/
    La idea es insertar “nodos” de LM o redes neuronales locales simples que se encarguen de tareas específicas y tengan una salida muy restringida. Por eso ejemplos como “question -> answer: float” me resultan muy atractivos. En mi caso, algunas de las preguntas pueden ser bastante abstractas, pero las pipelines de varias etapas también me parecen interesantes

    • La salida tipada de los LLM cambia por completo las reglas del juego

  • No lo he leído a fondo, pero quiero usar la mayor cantidad posible de código determinista y recurrir lo menos posible al LLM
    Así se obtienen resultados predecibles, costos operativos bajos y además se da la señal de que a otros no les será tan fácil copiar la misma app rápidamente. En vez de usar tal cual el pegamento de moda para conectar LLM con otros sistemas, prefiero crear mis propias herramientas
    Si estas condiciones no se cumplen o no hacen falta, creo que alguien puede sacar la misma solución en un instante con vibe coding. Hay que mantener el control. Soy de la postura de morir en la colina del control. Eso no significa que no me impresionen los LLM; de hecho, es todo lo contrario

    • Control está bien y la determinación también. El objetivo principal es convencerte de que no renuncies a demasiado control, pero el objetivo secundario es mostrarte “estos son precisamente los puntos donde sí puedes soltar un poco el control”