Arquitectura de agentes de IA: patrones para producción

Construir un agente que funciona en una demostración es relativamente sencillo. Conseguir que funcione de forma fiable para cientos de usuarios y miles de tareas plantea otros problemas.

Estos son los patrones a los que vuelvo después de construir y depurar sistemas de agentes. Cada uno aborda una forma de fallo que aparece en producción.

El problema central está en las conexiones

Los pasos individuales pueden funcionar: la llamada al modelo, la herramienta y la recuperación de información. Lo que falla es el paso de uno al siguiente.

• El paso anterior devuelve un formato inesperado.
• El agente repite acciones sobre un estado ambiguo sin una condición de salida.
• Una herramienta falla en silencio y el agente continúa con una suposición falsa.
• La intención del usuario se captura al principio y se desdibuja para el quinto paso.

Una buena arquitectura define cómo se comunican los pasos, cómo se propagan los errores, cómo se representa el estado y cómo se recupera el sistema de un imprevisto.

Patrón 1: una máquina de estados explícita

Un error frecuente es dejar que el modelo deduzca «dónde estamos» en cada paso a partir del historial. Puede funcionar hasta que un fallo sutil lo vuelve difícil de depurar.

Define los estados, sus transiciones y los datos disponibles en cada uno:

States: GATHERING_INFO → PLANNING → EXECUTING → VERIFYING → DONE | FAILED
Transitions: explicit conditions on structured output from each step

Así puedes identificar qué transición falló y qué datos tenía el agente en ese momento.

Exige más diseño inicial, pero ayuda cuando el agente recibe entradas diversas en producción.

Patrón 2: salidas estructuradas en cada frontera

El texto libre entre pasos puede romper la fiabilidad. Basta un cambio de prompt o una entrada inesperada para que falle el análisis de cadenas.

Usa salidas estructuradas, mediante modo JSON o llamadas a funciones, donde necesites extraer datos para el siguiente paso:

{
  "intent": "search_product",
  "parameters": { "query": "noise canceling headphones", "budget_max": 300 },
  "confidence": "high",
  "clarification_needed": false
}

Un esquema explícito permite validar la estructura antes de continuar. Los campos obligatorios ausentes y los resultados que no cumplen el criterio de confianza se detectan en esa frontera, sin propagarse en silencio.

Patrón 3: verificar antes de ejecutar

Si un agente escribe en bases de datos, llama APIs, cambia archivos o envía correos, incorpora una verificación previa de la acción.

El patrón:

1. Planificar: el modelo produce un plan estructurado.
2. Verificar: una comprobación separada evalúa si coincide con la intención del usuario y si incluye operaciones destructivas. Puede combinar reglas y revisión del modelo; los permisos obligatorios se aplican en código.
3. Ejecutar: solo continúa si supera la verificación.

Añade latencia, pero ayuda a detectar acciones más amplias de lo autorizado o instrucciones mal interpretadas. En operaciones con consecuencias, ese control merece el coste.

Patrón 4: reintentos limitados y una alternativa

Repetir indefinidamente la misma entrada no arregla un fallo persistente. Diseña reintentos con variación progresiva:

• Primer reintento: misma entrada, si el error es transitorio.
• Segundo: entrada simplificada o dividida, si el problema es de complejidad.
• Tercero: derivar a una persona, una regla más sencilla o una respuesta explícita de que no puede completarlo.

Como regla de trabajo, no reintento más de tres veces sin cambiar algo. Define la alternativa antes de publicar. Un «error, vuelve a intentarlo» deja el problema al usuario.

Patrón 5: las herramientas tienen contratos

Las definiciones de herramientas conectan al agente con el exterior. Trátalas como contratos de API:

• Precondiciones: qué debe ser cierto para que la llamada funcione.
• Poscondiciones: qué garantiza si tiene éxito.
• Modos de fallo: qué errores devuelve y por qué.
• Tipos precisos: esquemas de entrada y salida con restricciones claras.

El modelo decide cuándo y cómo usar una herramienta según su descripción. Una definición vaga facilita usos equivocados.

Patrón 6: contexto breve y memoria recuperable

Los historiales extensos pueden crear problemas:

• Se pierden de vista restricciones iniciales.
• Aumenta la latencia.
• Se acumulan costes.
• Algunas instrucciones dejan de influir en la respuesta.

Mantén pequeño y explícito el contexto activo. Traslada la historia a una memoria que puedas recuperar solo cuando sea pertinente.

Un formato práctico:

[CONTEXT WINDOW]
- Current task: {current_task}
- User preferences: {relevant_preferences}
- Last N actions: {recent_actions}
- Retrieved: {retrieval_results_for_current_step}

Evita incluir por defecto todo el historial, razonamientos antiguos o preguntas ya resueltas.

Patrón 7: diseña la observabilidad desde el principio

Sin instrumentación será difícil explicar un fallo. Antes de publicar:

• Asigna un identificador de traza a cada ejecución.
• Registra las entradas, salidas, herramientas, latencias y costes de cada paso.
• Registra las transiciones de estado.
• Conserva el contexto necesario para investigar los fallos, con controles de acceso y retención acordes a los datos.

Después prepara una forma de reproducir las ejecuciones fallidas con las mismas entradas.

El estado explícito, las fronteras estructuradas, los reintentos limitados y las trazas hacen que el comportamiento del agente sea más predecible y depurable.

Para una revisión sistemática, la lista de comprobación de fiabilidad de IA en producción incluye una sección dedicada a agentes.