El Agente de IA de los 12 Factores: Cómo Construir Sistemas de IA Efectivos y Escalables
Descubre los 12 factores para construir agentes de IA robustos y escalables: desde la conversión de lenguaje natural y la propiedad de los prompts, hasta la colaboración humana y el diseño sin estado. Construye sistemas de IA listos para producción que generen valor real para el negocio.
¿Qué Hace que un Agente de IA Sea Efectivo?
Antes de sumergirnos en los factores, aclaremos a qué nos referimos con “agentes de IA”. En esencia, son sistemas capaces de interpretar solicitudes en lenguaje natural, tomar decisiones basadas en el contexto y ejecutar acciones específicas a través de herramientas o APIs, todo mientras mantienen interacciones coherentes y continuas.
Los agentes más potentes combinan las capacidades de razonamiento de los modelos de lenguaje con la fiabilidad del código determinista. Pero lograr este equilibrio requiere decisiones de diseño cuidadosas, y eso es precisamente lo que abordan estos factores.
Los 12 Factores para Construir Agentes de IA Robustos
1. Domina la Conversión de Lenguaje Natural a Llamadas de Herramientas
La capacidad de transformar solicitudes en lenguaje natural en llamadas estructuradas a herramientas está en el corazón de la funcionalidad del agente. Esto permite que un agente tome un simple comando como “crea un enlace de pago por $750 para Terri para el meetup de AI Tinkerers de febrero” y lo convierta en una llamada API correctamente formateada.
{
"function": {
"name": "create_payment_link",
"parameters": {
"amount": 750,
"customer": "cust_128934ddasf9",
"product": "prod_8675309",
"price": "prc_09874329fds",
"quantity": 1,
"memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
}
}
}
La clave para que esto funcione de forma confiable es usar código determinista para manejar la salida estructurada de tu modelo de lenguaje. Valida siempre las cargas útiles de la API antes de ejecutarlas para evitar errores, y asegúrate de que tu LLM devuelva formatos JSON consistentes que puedan ser analizados de manera confiable.
2. Posee Completamente Tus Prompts
Tus prompts son la interfaz entre tu aplicación y el modelo de lenguaje: trátalos como código de primera clase. Aunque los frameworks que abstraen los prompts pueden parecer convenientes, a menudo oscurecen cómo se pasan las instrucciones al LLM, dificultando o imposibilitando el ajuste fino.
En su lugar, mantén el control directo sobre tus prompts escribiéndolos explícitamente:
function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
prompt #"
{{ _.role("system") }}
You are a helpful assistant that manages deployments for frontend and backend systems.
...
{{ _.role("user") }}
{{ thread }}
What should the next step be?
"#
}
Este enfoque te da varias ventajas:
- Control total para escribir instrucciones precisas adaptadas a tu caso de uso específico
- Capacidad de construir evaluaciones y pruebas para los prompts como cualquier otro código
- Transparencia para entender exactamente qué recibe el LLM
- Libertad para iterar en función de métricas de rendimiento
3. Diseña Estrategicamente Tu Ventana de Contexto
La ventana de contexto sirve como entrada para el LLM, abarcando prompts, historial de conversación y datos externos. Optimizar esta ventana mejora el rendimiento y la eficiencia de los tokens.
Ve más allá de los formatos estándar basados en mensajes hacia estructuras personalizadas que maximizan la densidad de información:
<slack_message>
From: @alex
Channel: #deployments
Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
tags:
- name: "v1.2.3"
commit: "abc123"
date: "2024-03-15T10:00:00Z"
</list_git_tags_result>
Este enfoque ofrece varios beneficios:
- Reducción del uso de tokens con formatos compactos
- Mejor filtrado de datos sensibles antes de pasar al LLM
- Flexibilidad para experimentar con formatos que mejoren la comprensión del LLM
4. Implementa Herramientas como Salidas Estructuradas
En esencia, las herramientas son simplemente salidas JSON del LLM que activan acciones deterministas en tu código. Esto crea una separación clara entre la toma de decisiones de la IA y la lógica de ejecución.
Define claramente los esquemas de las herramientas:
class CreateIssue {
intent: "create_issue";
issue: {
title: string;
description: string;
team_id: string;
assignee_id: string;
};
}
class SearchIssues {
intent: "search_issues";
query: string;
what_youre_looking_for: string;
}
Luego construye análisis confiables para las salidas JSON del LLM, usa código determinista para ejecutar las acciones y retroalimenta los resultados en el contexto para flujos iterativos de trabajo.
5. Unifica la Ejecución y el Estado de Negocio
Muchos frameworks de agentes separan el estado de ejecución (por ejemplo, el paso actual en un proceso) del estado de negocio (por ejemplo, el historial de llamadas a herramientas y sus resultados). Esta separación añade complejidad innecesaria.
En su lugar, almacena todo el estado directamente en la ventana de contexto, infiriendo el estado de ejecución a partir de la secuencia de eventos:
<deploy_backend>
intent: "deploy_backend"
tag: "v1.2.3"
environment: "production"
</deploy_backend>
<error>
error running deploy_backend: Failed to connect to deployment service
</error>
Este enfoque unificado proporciona:
- Simplicidad con una sola fuente de la verdad para el estado
- Mejor depuración con todo el historial en un solo lugar
- Recuperación sencilla reanudando desde cualquier punto cargando el hilo
Llevando los Agentes de IA a Producción
6. Diseña APIs para Lanzar, Pausar y Reanudar
Los agentes de nivel producción deben integrarse perfectamente con sistemas externos, pausando para tareas de larga duración y reanudando cuando se activan por webhooks u otros eventos.
Implementa APIs que permitan lanzar, pausar y reanudar agentes, con almacenamiento robusto del estado entre operaciones. Esto permite:
- Soporte flexible para flujos de trabajo asíncronos
- Integración limpia con webhooks y otros sistemas
- Reanudación confiable después de interrupciones sin reiniciar
7. Habilita la Colaboración Humana Mediante Llamadas de Herramientas
Los agentes de IA frecuentemente necesitan la intervención humana para decisiones críticas o situaciones ambiguas. Usar llamadas de herramientas estructuradas hace que esta interacción sea fluida:
class RequestHumanInput {
intent: "request_human_input";
question: string;
context: string;
options: {
urgency: "low" | "medium" | "high";
format: "free_text" | "yes_no" | "multiple_choice";
choices: string[];
};
}
Este enfoque proporciona una especificación clara del tipo de interacción y urgencia, soporta la entrada de múltiples usuarios y combina bien con APIs para flujos de trabajo duraderos.
8. Controla el Flujo de tu Agente
El flujo de control personalizado te permite pausar para aprobación humana, almacenar resultados en caché o implementar límites de velocidad, adaptando el comportamiento del agente a tus necesidades específicas:
async function handleNextStep(thread: Thread) {
while (true) {
const nextStep = await determineNextStep(threadToPrompt(thread));
if (nextStep.intent === 'request_clarification') {
await sendMessageToHuman(nextStep);
await db.saveThread(thread);
break;
} else if (nextStep.intent === 'fetch_open_issues') {
const issues = await linearClient.issues();
thread.events.push({ type: 'fetch_open_issues_result', data: issues });
continue;
}
}
}
Con este enfoque, obtienes:
- Interrumpibilidad para pausar y revisar con humanos antes de acciones críticas
- Opciones de personalización para registro, caché o resumen
- Manejo confiable de tareas de larga duración
9. Compacta los Errores en el Contexto para la Auto-Curación
Incluir errores directamente en la ventana de contexto permite que los agentes de IA aprendan de los fallos y ajusten su enfoque:
try {
const result = await handleNextStep(thread, nextStep);
thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
thread.events.push({ type: 'error', data: formatError(e) });
}
Para que esto funcione eficazmente:
- Limita los reintentos para evitar bucles infinitos
- Escala a humanos tras fallos repetidos
- Da formato claro a los errores para que el LLM entienda qué salió mal
Mejores Prácticas Arquitectónicas
10. Construye Agentes Pequeños y Enfocados
Los agentes pequeños que manejan entre 3 y 20 pasos mantienen ventanas de contexto manejables, mejorando el rendimiento y la fiabilidad del LLM. Este enfoque proporciona:
- Claridad con un alcance bien definido para cada agente
- Menor riesgo de que el agente pierda el foco
- Pruebas y validación más sencillas de funciones específicas
A medida que los LLMs continúan mejorando, estos agentes pequeños pueden expandir su alcance manteniendo la calidad, asegurando la escalabilidad a largo plazo.
11. Activa Disparadores desde Múltiples Fuentes
Haz que tus agentes sean accesibles permitiendo activadores desde Slack, correo electrónico o sistemas de eventos, encontrando a los usuarios donde ya trabajan.
Implementa APIs que lancen agentes desde varios canales y respondan por el mismo medio. Esto permite:
- Mejor accesibilidad al integrarse con las plataformas preferidas de los usuarios
- Soporte para flujos de trabajo de automatización impulsados por eventos
- Flujos de aprobación humana para operaciones críticas
12. Diseña Agentes como Reductores sin Estado
Trata a los agentes como funciones sin estado que transforman el contexto de entrada en acciones de salida, simplificando la gestión del estado y haciéndolos predecibles y fáciles de depurar.
Este enfoque conceptual ve a los agentes como funciones puras que no mantienen estado interno, proporcionando:
- Comportamiento predecible para entradas determinadas
- Trazabilidad de problemas fácilmente a través del historial de contexto
- Pruebas y validaciones más simples
Construyendo para el Futuro
El campo de los agentes de IA está evolucionando rápidamente, pero estos principios básicos seguirán siendo relevantes incluso cuando los modelos subyacentes mejoren. Al comenzar con agentes pequeños y enfocados que sigan estas prácticas, puedes crear sistemas que aporten valor hoy y se adapten a los avances futuros.
Recuerda que los agentes de IA más efectivos combinan las capacidades de razonamiento de los modelos de lenguaje con la fiabilidad del código determinista, y estos 12 factores te ayudan a lograr ese equilibrio.
Cómo FlowHunt Aplicó la Metodología de 12 Factores
En FlowHunt, hemos puesto en práctica estos principios desarrollando nuestro propio agente de IA que crea automáticamente automatizaciones de flujos de trabajo para nuestros clientes. Así es como aplicamos la metodología de 12 factores para construir un sistema confiable y listo para producción
Preguntas frecuentes
- ¿Qué es la metodología del Agente de IA de 12 Factores?
La metodología del Agente de IA de 12 Factores es un conjunto de mejores prácticas inspiradas en el modelo de aplicaciones de 12 factores, diseñada para ayudar a los desarrolladores a construir agentes de IA robustos, mantenibles y escalables que funcionen de manera confiable en entornos de producción reales.
- ¿Por qué es importante la gestión del contexto para los agentes de IA?
La gestión del contexto asegura que los agentes de IA mantengan el historial de conversación relevante, los prompts y el estado, optimizando el rendimiento, reduciendo el uso de tokens y mejorando la precisión en la toma de decisiones.
- ¿Cómo permiten los agentes de IA de FlowHunt la colaboración humana?
Los agentes de IA de FlowHunt estructuran las llamadas a herramientas para solicitar la intervención humana cuando es necesario, permitiendo una colaboración fluida, aprobaciones y flujos de trabajo duraderos para escenarios complejos o críticos.
- ¿Cuáles son los beneficios de diseñar agentes de IA sin estado?
Los agentes de IA sin estado son predecibles, más fáciles de depurar y más sencillos de escalar porque transforman el contexto de entrada en acciones de salida sin mantener un estado interno oculto.
Arshia es ingeniera de flujos de trabajo de IA en FlowHunt. Con formación en ciencias de la computación y una pasión por la IA, se especializa en crear flujos de trabajo eficientes que integran herramientas de IA en las tareas cotidianas, mejorando la productividad y la creatividad.
Arshia Kahani
Ingeniera de flujos de trabajo de IA
Construye Agentes de IA Escalables con FlowHunt
¿Listo para crear agentes de IA robustos y listos para producción? Descubre las herramientas de FlowHunt y observa cómo la metodología de 12 factores puede transformar tu automatización.
Saber más
