Intro

Los agentes no fallan solamente en la respuesta final.

Fallan en el camino.

Eligen una herramienta incorrecta. Usan contexto viejo. Reintentan sin cambiar la hipótesis. Interpretan mal un resultado intermedio. Pierden una validación. Confunden una recomendación con una autorización. Gastan tokens en una rama inútil. Tardan demasiado en una etapa que parecía menor. O llegan a una respuesta razonable, pero sin evidencia suficiente para explicar cómo llegaron ahí.

Por eso, cuando un agente empieza a tocar workflows reales, los logs sueltos dejan de alcanzar.

Un log puede decir que algo pasó. Pero muchas veces no alcanza para reconstruir qué vio el agente, qué decidió, qué herramienta usó, qué resultado obtuvo, qué validó, qué ignoró y dónde cambió el estado del sistema.

La observabilidad en agentes necesita mirar la trayectoria completa, no solo eventos aislados.

El problema de mirar agentes como si fueran una API clásica

En una API tradicional, la unidad natural de observación suele ser bastante clara:

request -> handler -> base de datos -> response

Hay latencia, status code, logs, métricas, errores, trazas distribuidas y alertas. Eso sigue siendo útil. Pero un agente agrega una capa distinta: toma decisiones intermedias y puede cambiar el flujo según contexto, herramientas, resultados y validaciones.

Un flujo agentic se parece más a esto:

objetivo inicial
  -> selección de contexto
  -> razonamiento / planificación
  -> tool call A
  -> interpretación del resultado
  -> nueva decisión
  -> tool call B
  -> validación
  -> posible retry
  -> posible aprobación humana
  -> respuesta o acción final

Si solo guardamos logs lineales, vemos pedazos. No vemos el sistema.

Y cuando algo sale mal, esa diferencia se nota enseguida.

El operador pregunta: ¿por qué eligió esa tool y no otra? ¿Qué contexto tenía disponible? ¿La tool falló o el agente interpretó mal la respuesta? ¿Hubo retry? ¿Cambió el prompt efectivo? ¿Cuánto costó esa corrida? ¿Qué validación se salteó? ¿Quién aprobó la acción? ¿Esto ya había pasado antes?

Un archivo de logs puede contener algunas respuestas. Una traza bien diseñada permite reconstruirlas.

Logs, métricas y trazas no son lo mismo

Conviene separar conceptos.

Logs registran eventos: una tool fue llamada, una respuesta llegó, una excepción ocurrió. Son útiles para detalle local, pero suelen ser difíciles de correlacionar cuando el flujo crece.

Métricas agregan señales numéricas: latencia, tasa de error, costo promedio, tokens por corrida, cantidad de retries, porcentaje de aprobaciones humanas. Sirven para tendencias, alertas y comparación.

Trazas conectan pasos relacionados dentro de una ejecución. Permiten ver la forma de la corrida: qué pasó primero, qué dependía de qué, cuánto tardó cada etapa y dónde se tomó cada decisión.

En agentes, la traza suele ser la pieza que falta.

Porque el valor no está solo en saber que hubo una llamada a una tool. Está en saber en qué paso ocurrió, con qué input, con qué permisos, con qué resultado, bajo qué objetivo y qué decisión produjo después.

La unidad mínima: una corrida observable

Antes de instrumentar todo, hace falta definir una unidad básica: la corrida.

Una corrida debería tener un identificador estable y agrupar todo lo que pertenece a una ejecución concreta del agente:

run_id
  objetivo
  usuario / sistema iniciador
  versión de prompt o policy
  modelo usado
  contexto cargado
  pasos ejecutados
  tools llamadas
  validaciones
  errores y retries
  approvals
  resultado final
  costo y duración

Ese run_id permite dejar de perseguir logs dispersos y empezar a hablar de una ejecución verificable.

Sin esa unidad, el debugging suele depender de intuición, grep, timestamps aproximados y memoria humana. Funciona en demos. No escala bien en operación.

Spans: cómo partir el trabajo sin perder el mapa

Una traza se puede pensar como un árbol de spans.

Cada span representa una etapa relevante:

  • carga de contexto;
  • llamada al modelo;
  • llamada a una herramienta;
  • validación de salida;
  • retry;
  • aprobación humana;
  • escritura de estado;
  • publicación o acción externa.

Ejemplo simple:

agent.run
  context.retrieve
  model.plan
  tool.search_docs
  model.decide
  tool.create_ticket
  approval.wait
  action.notify_user

No hace falta instrumentar cada línea de código desde el primer día. Pero sí conviene que las fronteras importantes queden explícitas.

Un span debería responder qué etapa representa, cuándo empezó y terminó, qué input recibió, qué output produjo, si terminó bien o con error, qué metadata operativa importa y qué relación tiene con otros spans.

La clave es que el span no sea solo decorativo. Debe ayudar a explicar el comportamiento del agente.

Qué medir de verdad

Medir todo no es observar mejor. A veces solo crea ruido, costo y riesgo de privacidad.

Lo importante es capturar señales que permitan responder preguntas operativas concretas.

1. Contexto efectivo

No alcanza con decir “usó RAG” o “tenía memoria”. Hay que poder saber qué contexto vio realmente el agente en cada paso importante.

Señales útiles:

  • documentos recuperados;
  • fragmentos incluidos;
  • fuentes descartadas;
  • score o criterio de recuperación;
  • antigüedad del dato;
  • etiquetas de confianza;
  • tamaño del contexto;
  • cambios entre una corrida y otra.

Muchos errores de agentes no son errores del modelo: son errores de contexto. Si el agente recibe información incorrecta, incompleta o demasiado ruidosa, la respuesta final puede sonar razonable y estar mal igual.

La observabilidad tiene que permitir distinguir entre:

el modelo razonó mal

y:

el sistema le dio mal contexto al modelo

Son problemas distintos y se arreglan en capas distintas.

2. Tool calls

Las herramientas son donde el agente deja de hablar y empieza a tocar sistemas.

Por eso cada tool call debería dejar evidencia suficiente:

  • nombre de la tool;
  • versión o implementación;
  • parámetros normalizados;
  • permisos aplicados;
  • resultado resumido;
  • error, si existió;
  • latencia;
  • si hubo side effects;
  • si la llamada fue simulada, aprobada o ejecutada.

Esto no significa guardar secretos o payloads sensibles sin control. Significa diseñar una representación segura y útil para auditoría.

Un buen trace permite ver si el problema fue selección incorrecta de tool, parámetros mal construidos, respuesta ambigua, permisos demasiado amplios, validación insuficiente, error externo o interpretación equivocada del resultado.

Sin esa separación, todo termina siendo “el agente falló”. Y esa frase no sirve para mejorar el sistema.

3. Decisiones intermedias

No siempre conviene guardar razonamiento interno completo del modelo. Puede ser costoso, sensible, inconsistente o directamente no estar disponible según el proveedor.

Pero sí conviene registrar decisiones observables:

  • hipótesis elegida;
  • próxima acción seleccionada;
  • criterio usado;
  • alternativa descartada, si el sistema la expone;
  • nivel de confianza operacional;
  • razón resumida para pedir aprobación o continuar.

La meta no es leer la mente del modelo. La meta es tener un rastro suficiente para operar el sistema.

Ejemplo:

{
  "decision": "request_human_approval",
  "reason": "acción externa con impacto en cliente",
  "risk_level": "medium",
  "policy": "approval_required_for_external_send"
}

Eso es más útil que un log genérico diciendo “waiting for user”.

4. Validaciones

Los validadores son una parte central del harness. Si no se observan, quedan invisibles justo cuando más importan.

Conviene medir qué validación corrió, contra qué regla, si pasó o falló, qué campo falló, si el sistema permitió retry, si el error bloqueó la acción y si alguien lo sobreescribió manualmente.

Esto ayuda a detectar patrones: schemas mal diseñados, salidas que siempre fallan en el mismo campo, tools que devuelven formatos inestables o prompts que empujan al agente hacia respuestas inválidas.

5. Retries y recuperación

Un retry no es un detalle menor. En agentes, puede esconder comportamiento importante.

Hay retries buenos: una API transitoria falló y el sistema reintentó con backoff.

Y hay retries malos: el agente repite la misma acción porque no entiende el estado, o prueba variantes hasta que alguna pasa sin saber por qué.

Medir retries permite ver cuántos hubo, qué cambió entre intentos, si se redujo el alcance, si se pidió más contexto, si aumentó el riesgo y si se terminó por timeout o por éxito real.

Un sistema con muchos retries puede parecer resiliente. A veces solo está ocultando mala arquitectura.

6. Latencia por etapa

Medir solo duración total no alcanza.

Necesitamos saber dónde se consume el tiempo: recuperación de contexto, llamada al modelo, tool externa, espera de aprobación, procesamiento de archivos, validación, publicación o escritura final.

Esto evita optimizar lo equivocado. Quizás el modelo no es el cuello de botella; quizás la tool tarda, el contexto se recupera mal o el sistema espera una aprobación sin timeout claro.

7. Costo y tokens

En agentes, el costo no es solo una métrica financiera. También revela diseño.

Señales útiles:

  • tokens de entrada y salida por paso;
  • costo por corrida;
  • costo por tarea con tools;
  • crecimiento del contexto;
  • costo de retries;
  • costo por resultado exitoso vs fallido.

Si una tarea simple se vuelve cara, puede haber contexto excesivo, loops, retries inútiles o falta de cache.

8. Aprobaciones humanas

Cuando hay human-in-the-loop, la aprobación también forma parte de la traza.

No alcanza con registrar “approved”. Hace falta saber qué se aprobó, quién aprobó, cuándo, con qué información visible, si el payload cambió después, qué política exigía aprobación y si hubo rechazo o ajuste.

Esto es importante para seguridad, auditoría y confianza operativa.

Una aprobación no debería ser una interrupción informal. Debería ser un evento del sistema.

Lo que una buena trazabilidad habilita

La observabilidad no es un dashboard lindo. Es una herramienta para tomar mejores decisiones.

Debugging más rápido

Cuando algo falla, la traza permite ir al punto real: contexto, tool, validación, policy, modelo, latencia, retry o integración externa.

Sin traza, el equipo suele discutir síntomas.

Comparar corridas

Dos ejecuciones parecidas pueden producir resultados distintos. Con trazabilidad, se puede comparar qué cambió: modelo, prompt, documentos recuperados, tool result, policy, estado externo, temperatura, permisos o versión del workflow.

Eso vuelve investigable lo que antes parecía “comportamiento raro del modelo”.

Mejorar evals

Los evals no deberían mirar solo la respuesta final. Las trazas permiten crear evals sobre proceso: si eligió la tool correcta, si pidió aprobación cuando correspondía, si rechazó una instrucción peligrosa, si validó antes de actuar, si mantuvo el costo bajo un umbral o si evitó filtrar datos sensibles.

Esto conecta observabilidad con calidad real.

Auditar acciones

Si un agente puede modificar sistemas, crear tickets, enviar mensajes o ejecutar scripts, la auditoría deja de ser opcional.

Una traza clara permite explicar qué pasó sin depender de capturas, recuerdos o conversaciones sueltas.

Diseñar mejores límites

La observabilidad muestra dónde el sistema pide demasiado al modelo y demasiado poco al harness.

Si una misma clase de error aparece seguido, tal vez no se resuelve con un prompt más largo. Tal vez se resuelve con una policy externa, un validador, una tool más específica, permisos más chicos o un paso de aprobación mejor diseñado.

Riesgos de observar mal

Más observabilidad no siempre significa mejor gobierno.

Hay riesgos reales:

  • guardar datos sensibles sin redacción;
  • convertir traces en depósitos de secretos;
  • capturar prompts completos cuando no hace falta;
  • perder trazabilidad por exceso de ruido;
  • crear dashboards que nadie usa;
  • medir métricas vistosas pero irrelevantes;
  • depender de un vendor sin entender el modelo de datos;
  • creer que un trace bonito compensa un workflow mal diseñado.

La pregunta no es “¿podemos registrar todo?”.

La pregunta es:

¿qué necesitamos saber para depurar, auditar, mejorar y limitar riesgo sin exponer más datos de los necesarios?

Un modelo práctico para empezar

No hace falta construir una plataforma enorme desde el primer día.

Un punto de partida razonable:

  1. asignar run_id a cada ejecución;
  2. registrar spans para contexto, modelo, tools, validaciones y approvals;
  3. guardar metadata segura, no secretos crudos;
  4. medir latencia, errores, retries, tokens y costo;
  5. asociar cada corrida con versión de prompt, modelo y workflow;
  6. generar un resumen final de la ejecución;
  7. usar trazas reales para alimentar evals y mejoras.

Una estructura mínima podría verse así:

{
  "run_id": "agent_2026_05_18_001",
  "workflow": "triage_ticket",
  "model": "llm-x",
  "prompt_version": "v12",
  "status": "blocked_for_approval",
  "spans": [
    {"name": "context.retrieve", "duration_ms": 420, "docs": 4},
    {"name": "model.plan", "duration_ms": 1800, "tokens_in": 5400, "tokens_out": 320},
    {"name": "tool.lookup_customer", "duration_ms": 260, "status": "ok"},
    {"name": "validation.policy", "status": "requires_approval"}
  ],
  "cost_usd": 0.08,
  "approval_required": true
}

No es perfecto. Pero ya permite operar mucho mejor que una carpeta de logs inconexos.

La señal más importante: poder explicar el cambio de estado

En agentes, lo más delicado no es que el modelo escriba una frase incorrecta. Lo más delicado es que cambie algo: un archivo, un ticket, una configuración, un mensaje, una factura, una publicación, una decisión de negocio.

Por eso, toda acción con side effect debería poder responder:

  • qué objetivo habilitó la acción;
  • qué contexto la justificó;
  • qué tool la ejecutó;
  • qué validaciones pasaron;
  • qué permisos aplicaron;
  • qué aprobación existió, si correspondía;
  • qué cambió exactamente;
  • cómo revertir o corregir.

Si el sistema no puede responder eso, todavía no está listo para operar con confianza.

Observabilidad como parte del harness

La observabilidad no vive separada del diseño del agente. Es parte del harness.

Un agente confiable necesita contexto, tools, permisos, validadores, evals, approvals, memoria y trazabilidad trabajando juntos.

Si la observabilidad se agrega al final como “logs para cuando algo rompa”, llega tarde. Tiene que estar en el diseño del flujo.

Cada paso importante debería dejar evidencia proporcional a su riesgo.

Una consulta de lectura puede requerir trazabilidad liviana. Una acción externa o irreversible debería requerir trazabilidad fuerte, validación clara y, muchas veces, aprobación humana.

Conclusión

Los logs siguen siendo útiles. Pero en agentes no alcanzan.

Porque el problema no es solo registrar eventos. Es reconstruir trayectorias.

Un agente operativo necesita que podamos ver qué contexto recibió, qué herramientas usó, qué decisiones intermedias tomó, qué validaciones pasaron, qué retries ocurrieron, cuánto costó, cuánto tardó y qué aprobación habilitó una acción.

Esa trazabilidad no es burocracia. Es la diferencia entre confiar en una demo y operar un sistema.

Cuando el agente solo responde, un log puede ser suficiente.

Cuando el agente actúa, necesitamos algo más: trazas que expliquen el camino completo entre intención, decisión, herramienta, control y cambio de estado.