El Agente de IA de los 12 Factores: Cómo Construir Sistemas de IA Efectivos y Escalables

¿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.

Image URL

{
  "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.

Image URL

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[];  
  };  
}

Image URL

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:

Image URL

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

Image URL

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.

Image URL

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