Observabilidad para agentes: cómo entender qué hicieron y por qué

Un agente tarda 47 segundos en cerrar una gestión que normalmente resuelve en ocho. La respuesta final parece correcta. ¿El retraso vino del modelo, de una búsqueda lenta, de tres llamadas repetidas al CRM o de una aprobación que quedó esperando?

Si el sistema solo guarda la pregunta y la respuesta, faltará la información necesaria para explicarlo. Un agente recorre una trayectoria formada por decisiones, llamadas y cambios de estado. Observarlo exige reconstruirla y conectarla con el resultado que importaba al negocio.

Logs, métricas y trazas responden preguntas distintas

Los logs registran sucesos: una herramienta devolvió un error, se bloqueó una acción o cambió el estado. Las métricas agregan comportamiento: tasa de finalización, latencia percentil 95, coste medio o número de escalados. Las trazas enlazan las operaciones de una ejecución para explicar cómo se llegó al resultado.

En una aplicación convencional ya necesitamos las tres señales. En un agente resultan más importantes porque el camino puede cambiar entre dos solicitudes parecidas. El modelo elige herramientas, reformula consultas y decide si continuar. Una media diaria no explica por qué una ejecución concreta entró en bucle.

OpenTelemetry propone convenciones comunes para registrar operaciones de IA generativa, incluidos modelo, tokens, duración y —cuando se habilita— mensajes y llamadas a herramientas. Su objetivo es evitar que cada framework produzca una telemetría incompatible (OpenTelemetry, mayo de 2026). Estas convenciones siguen evolucionando, así que conviene desacoplar el esquema interno del proveedor de visualización.

La unidad útil es el trabajo, no la llamada al modelo

Una traza debería representar una gestión completa: “resolver incidencia 1842”, “preparar informe de riesgo” o “actualizar oportunidad comercial”. Dentro aparecen spans o tramos para cada operación: planificación, generación, búsqueda, herramienta, guardrail, transferencia y aprobación.

El SDK de agentes de OpenAI registra de forma nativa turnos, ejecuciones de agentes, generaciones, llamadas a funciones, guardrails y handoffs. También permite añadir tramos propios para actividades del negocio (OpenAI Agents SDK). Esta última parte es la que suele faltar. Saber que update_record tardó 320 milisegundos ayuda poco si no sabemos si la oportunidad terminó realmente actualizada.

Una jerarquía razonable sería:

El identificador del flujo debe sobrevivir a colas, pausas y reanudaciones. Para conversaciones o procesos con varias ejecuciones, un identificador de grupo permite conectarlas sin confundirlas con una única llamada.

Qué registrar en cada paso

No hace falta guardar el razonamiento interno del modelo. Necesitamos decisiones observables y reproducibles: versión de instrucciones, modelo, herramientas disponibles, llamada seleccionada, argumentos, resultado, documentos recuperados, estado antes y después, y motivo estructurado de un escalado.

También conviene registrar la configuración que cambia el comportamiento: versión del índice, política de permisos, estrategia de memoria, límites de reintento y conjunto de guardrails. “El mismo prompt” no implica el mismo sistema si cualquiera de esas piezas cambió.

En las herramientas distinguimos al menos cuatro desenlaces: éxito, resultado vacío, error recuperable y error definitivo. Si todos vuelven como texto, el modelo puede interpretar una caída del servicio como ausencia de datos. La telemetría tampoco sabrá separarlos.

Para agentes de larga duración, el estado persistente y la traza cumplen funciones diferentes. El primero permite continuar; la segunda permite investigar. En nuestra arquitectura para agentes que trabajan durante horas o días explicamos por qué ambos deben sobrevivir a reinicios.

Métricas que descubren problemas reales

Los tokens son fáciles de contar. El SDK de OpenAI agrega peticiones y tokens de entrada y salida a lo largo de una ejecución, incluidas herramientas y transferencias, y ofrece el detalle por solicitud (OpenAI Agents SDK). Así se puede atribuir el consumo a una tarea concreta y no únicamente a una clave de API.

Un cuadro de mando centrado en tokens puede optimizar lo equivocado. Un agente que usa un 15 % más de inferencia y reduce a la mitad los expedientes reabiertos quizá sea más rentable. Por eso organizamos las métricas en cuatro capas:

• Resultado: trabajos completados, calidad, resolución a la primera y resultado de negocio.
• Trayectoria: pasos, reintentos, bucles, escalados, abstenciones y acciones rechazadas.
• Operación: disponibilidad, errores, latencia total y por dependencia.
• Economía: coste por trabajo completado, por resultado correcto y por excepción humana.

Los percentiles son más útiles que la media para latencia. También interesa separar tiempo de modelo, herramientas, colas y aprobación humana. Si una gestión tarda tres horas porque espera a un revisor, acelerar 200 milisegundos la inferencia no cambiará la experiencia.

La traza explica el recorrido; la evaluación mide su calidad

La observabilidad describe lo ocurrido y la evaluación aplica los criterios que determinan si el resultado y el recorrido eran correctos. Ambas señales se necesitan para decidir qué corregir.

Una traza puede alimentar evaluadores que comprueben si se usó la política vigente, si las afirmaciones tienen evidencia, si los argumentos de una herramienta eran válidos o si el agente se detuvo a tiempo. Los resultados de esas evaluaciones vuelven como atributos de la ejecución y permiten buscar patrones: por ejemplo, fallos de citas concentrados en una fuente concreta.

Las revisiones humanas deberían partir de muestras deliberadas, no solo de incidentes. Incluimos ejecuciones normales, caras, lentas, bloqueadas y de baja confianza. Las correcciones del usuario también son señal: editar un borrador, rechazar una acción o rehacer manualmente la gestión revela problemas que el sistema puede haber marcado como éxito.

La observabilidad del harness que rodea al modelo permite distinguir un fallo de razonamiento de un contrato de herramienta ambiguo, una fuente vacía o una condición de salida mal diseñada. Sin esa distinción, el remedio habitual es cambiar el prompt y esperar.

Las trazas contienen más de lo que parece

Entradas, salidas y argumentos pueden incluir contratos, datos de clientes, credenciales pegadas por error o información médica. La documentación de OpenAI advierte que las generaciones y llamadas a funciones pueden capturar contenido sensible; permite desactivar su inclusión, que está habilitada por defecto en ese SDK (OpenAI Agents SDK). En organizaciones con política de retención cero, su servicio de trazas no está disponible.

La política debe decidir qué campos se recogen, cuáles se redactan, quién accede y cuándo se eliminan. Para muchas métricas basta con identificadores seudonimizados, categoría de herramienta, duración y resultado. El contenido completo puede reservarse para muestras autorizadas o incidentes concretos.

Tampoco conviene introducir datos de alta cardinalidad —como el texto íntegro de una consulta— en etiquetas de métricas. Encarece el sistema y dificulta operar. Ese detalle pertenece a eventos o trazas con acceso controlado.

Alertas que permiten actuar

“La latencia ha subido” es una alerta incompleta. Una señal operativa debe incluir ámbito, gravedad y una ruta de respuesta. Ejemplos útiles: aumento de reintentos en la herramienta de pedidos, caída de recuperación de documentos vigentes, coste por resolución por encima del límite o crecimiento de aprobaciones rechazadas.

Los umbrales estáticos sirven para límites claros. Para comportamientos graduales, comparamos con la línea base por versión, flujo y segmento. Un cambio de mezcla —más casos complejos esa semana— puede explicar un aumento legítimo de coste.

Cada despliegue lleva identificador de modelo, instrucciones, herramientas y políticas. Así podemos hacer una publicación gradual, comparar cohortes y revertir. Los cambios silenciosos de proveedor o de índice destruyen esa capacidad.

Un diseño mínimo que sí ayuda a operar

Para el primer agente de producción suele bastar una traza completa por trabajo, estados estructurados de herramientas, consumo por ejecución, tres o cuatro métricas de resultado y alertas sobre fallos graves. El panel puede crecer cuando aparezcan preguntas que esos datos no resuelvan.

Después se amplía a partir de preguntas reales. Si cuesta explicar por qué aumenta el coste, añadimos atribución por fase. Si aparecen fugas de permisos, registramos versión de política y fuente. Si nadie usa un panel, se retira.

Una arquitectura interoperable separa instrumentación, transporte y análisis. OpenTelemetry está trabajando en convenciones para aplicaciones y frameworks de agentes precisamente para facilitar esa portabilidad, aunque parte del estándar siga madurando (OpenTelemetry). Conviene adoptar nombres comunes sin fingir que hoy todos los proveedores representan igual cada detalle.

Preguntas frecuentes