Observabilidad para agentes: cómo detectar que tu agente está fallando

Un agente que falla en silencio es peor que uno que no funciona: el que no funciona lo notas al día uno; el que falla en silencio te cuesta clientes, datos y presupuesto durante semanas. Los agentes fallan de formas que el software tradicional no: responden con confianza pero inventan datos, entran en loops de tool calls que queman tokens, o degradan su calidad cuando cambias de modelo. La observabilidad es lo único que convierte esas fallas invisibles en problemas con causa. Esta guía define qué medir, con qué herramientas y cómo investigar un fallo real paso a paso.

Qué medir: las seis métricas que importan

1. Trazas por ejecución: el registro completo de una tarea —mensaje entrante, cada tool call con su input y output, decisión final—. Sin trazas, no hay debugging posible; con ellas, cualquier fallo es un árbol de causas.
2. Tool calls: cuáles se llamaron, en qué orden, cuántas veces. El patrón "llama la misma API 8 veces" es la firma clásica de un agente en loop.
3. Tokens por tarea: entrada, salida y caché. Es tu métrica de costo por tarea y la alerta temprana de prompts que crecen sin control.
4. Latencia por paso: el modelo no es el único cuello de botella; a veces la herramienta tarda 10 segundos. Separa latencia del LLM, de herramientas y de red.
5. Errores y reintentos: fallos de herramientas, respuestas fuera de schema, excepciones del runtime. Cada error es una oportunidad de mejorar el prompt o la herramienta.
6. Calidad percibida: correcciones humanas, rechazos, escalamientos. Es la señal más honesta: un agente puede pasar todos los checks técnicos y aun así no servir.

Logging estructurado: el piso de todo

Antes de cualquier herramienta de tracing, define el formato de log. Cada evento del agente debe ser un JSON con el mismo shape:

{
  "traceId": "abc123",
  "event": "tool_call",
  "tool": "search_orders",
  "input": {"orderId": "ORD-4471"},
  "output": {"status": "shipped"},
  "tokens": {"input": 812, "output": 96},
  "latencyMs": 1420,
  "model": "gpt-4.1-mini",
  "timestamp": "2026-08-14T15:04:22Z"
}

Reglas: un traceId por tarea que atraviesa todos los pasos, campos estables (nada de inventar keys por evento), y redacción de datos sensibles en el momento del log. Este formato es lo que hace que Langfuse, LangSmith o cualquier pipeline de OpenTelemetry te sirvan de verdad: son consumidores de eventos, no magia.

Herramientas de tracing: las tres opciones reales

Herramienta	Modelo	Fuerza principal
Langfuse	Open source, self-hostable o nube	Trazas de agentes con evals integrados y control de datos
LangSmith	Nube (LangChain)	Trazas + playground + evaluaciones en el ecosistema LangChain
OpenTelemetry	Estándar abierto	Semántica GenAI para spans (LLM, tool, embedding), portable entre backends

Si ya usas LangChain, LangSmith es la ruta natural. Si quieres control total y open source, Langfuse self-hosted. Y si quieres estándares y no atarte a un vendor, las convenciones semánticas GenAI de OpenTelemetry definen exactamente cómo nombrar los spans de modelos, herramientas y embeddings para que cualquier backend los entienda. No necesitas las tres: necesitas una, usada bien, con el logging estructurado como base.

Alertas: qué debe sonarte y qué no

Las alertas que valen la pena (y evitan el ruido):

• Costo por día supera umbral: la alerta de presupuesto es la primera que configuras; los tokens son dinero.
• Tasa de errores de herramienta alta: si una API falla más del X% en una ventana, algo cambió afuera o adentro.
• Loops detectados: una tarea con más de N tool calls sin decisión final es un agente dando vueltas; corta y alerta.
• Latencia p95 degradada: los usuarios sienten la latencia antes que cualquier métrica interna.

Evita alertar por cada fallo individual: los agentes fallan a veces y eso es normal. Alerta por tasa y por tendencia, no por evento.

Cómo investigar un fallo real: caso paso a paso

Escenario: el agente de soporte empezó a responder con datos de otro cliente.

1. Encuentra la traza: filtra por el traceId del reporte, o por la conversación del cliente afectado. La traza muestra el mensaje exacto que recibió el agente.
2. Lee las tool calls: mira qué herramienta se llamó y con qué argumentos. El input revela el bug: el agente pasó el customerId del prompt del usuario en vez del ID autenticado de la sesión.
3. Revisa el contexto inyectado: los documentos o la memoria que entraron al prompt de esa llamada. Probablemente el prompt del sistema mezcló instrucciones con datos de otro tenant.
4. Confirma con tokens y latencia: ¿fue un caso aislado o hay más trazas con el mismo patrón? Agrupa por input de herramienta y por prompt version.
5. Corrige la causa raíz: en este caso, el ID debe venir de la sesión autenticada, nunca del texto del usuario. Cambia el código, agrega el caso a los evals y despliega.
6. Verifica en producción: la alerta o el dashboard deben mostrar que el patrón desapareció en las horas siguientes.

La regla de oro: nunca despliegues un cambio de agente sin trazas activas. El momento de agregar observabilidad es antes del primer usuario, porque el primer fallo real siempre llega cuando menos lo esperas, y sin trazas solo te queda adivinar. Los evals complementan la observabilidad: las trazas te dicen qué pasó, los evals para agentes te dicen si el agente sigue cumpliendo el contrato; las dos guías juntas —esta y la de evals— son el mínimo de operación seria.

Checklist para implementar hoy

1. Logging estructurado con traceId estable y campos fijos.
2. Redacción de PII en los logs desde el día uno.
3. Una herramienta de tracing (Langfuse, LangSmith u OpenTelemetry) conectada.
4. Métricas de tokens, latencia y tool calls por tarea.
5. Alertas de costo diario, tasa de errores y loops.
6. Procedimiento documentado para investigar fallos con trazas.

Un agente sin observabilidad es una caja negra que cobra por token. Con trazas, métricas y alertas, la caja negra se convierte en un sistema operado: falla, pero falla con causa, y eso es lo único que te permite mejorar. El hub de seguridad, coste y operación tiene las guías de evals, costos y seguridad que completan la operación de tu agente, y si todavía estás montando el runtime base, el curso gratuito te muestra dónde se conecta cada pieza de monitoreo.