Observabilidad de los agentes de IA: cómo saber qué hizo el agente y qué registrar

Qué es la observabilidad de un agente de IA

La observabilidad de los agentes de IA consiste en poder responder a tres preguntas basándose en los artefactos, no en la memoria ni en las palabras del agente: qué hizo, por qué lo hizo así y con qué se confirma que el resultado es correcto. Si tras veinte minutos de trabajo el agente dice «listo, pero dos pruebas fallan, quizá por el tiempo de espera», y cuando le preguntan qué rutas se tocaron responde «déjeme ver el código», no hay observabilidad. El agente no es tonto: simplemente no tiene nada que presentar.

El problema es sistémico. Un mismo agente puede decir diez veces en una semana, con honestidad, «listo», y cada vez eso significará algo distinto: en un caso se pasaron todas las pruebas, en otro solo una, en otro ninguna. Cuanto más vive un proyecto, más cuesta cada sesión nueva, porque empieza con una excavación.

Dos capas: runtime y proceso

La observabilidad se confunde con los logs, pero los logs son solo la mitad.

Solo runtime: se ve qué se rompió, pero no está claro qué se pretendía. Solo proceso: se entiende qué se quería, pero no se ve por qué no salió. Hacen falta las dos.

Por qué el agente no lo hará por sí solo

Pedirle al agente «registra mejor» no funciona, por tres motivos.

• No sabe lo que no sabe. El agente no registrará una señal cuya importancia no intuye.
• El formato varía. En una sesión escribe con detalle, en otra en una sola línea. Comparar sesiones y calcular agregados es imposible.
• El proceso no se cierra con logs. La respuesta a «¿por qué así?» vive en documentos creados antes del trabajo, no en la salida de los comandos.

Por eso la observabilidad se incorpora al harness, es decir, al entorno del agente: plantillas, hooks, scripts y un formato de informe obligatorio.

Qué registrar: el conjunto mínimo

Un buen diario no es una transcripción de todo, sino un conjunto de hechos con los que se puede reconstruir el curso del trabajo y calcular estadísticas.

• Identificadores: id de la sesión, id de la tarea o función, modelo del agente.
• Acciones con efectos secundarios: qué comandos se ejecutaron, qué archivos cambiaron. La lectura de archivos normalmente no hace falta registrarla.
• Resultados de las comprobaciones: qué comando de verificación, código de retorno, cuántas pruebas pasaron y cuántas fallaron.
• Reintentos: cuántos intentos costó un paso y en qué se diferenciaban.
• Consumo: tokens y tiempo, si la herramienta los informa.
• Resultado final: si la tarea se aceptó, se rechazó o se abandonó, y por qué.

Lo que no hay que escribir: secretos, tokens de acceso, datos personales de la salida de los comandos. El diario puede acabar en un lugar de acceso compartido o de nuevo en el contexto del modelo.

Diario de acciones mediante hooks de Claude Code

En Claude Code el diario se lleva cómodamente con hooks, comandos que lanza la propia herramienta y no el modelo, por eso se ejecutan siempre. El hook recibe en la entrada un JSON con la descripción del evento, incluidos el id de la sesión, el nombre de la herramienta y sus parámetros. Ejemplo de configuración en .claude/settings.json que, después de cada llamada a Bash, Edit o Write, añade una línea al diario:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — una línea JSON por acción
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

El formato JSONL (un registro JSON por línea) es cómodo porque se filtra fácilmente con jq y se carga en cualquier sistema de análisis. Además, Claude Code guarda localmente el historial completo de las sesiones en el directorio ~/.claude/projects/: se puede abrir si quiere ver los razonamientos y la salida completa, pero para estadísticas es más cómodo su propio diario compacto.

Trazas: una traza por sesión, un span por tarea

Cuando hay muchos agentes o trabajan según un horario, los diarios de texto no bastan: hacen falta agregados. Aquí sirven las herramientas habituales de trazado distribuido y el estándar OpenTelemetry.

• Traza: una sesión del agente.
• Span: una tarea dentro de la sesión.
• Spans anidados: los pasos de verificación: build, pruebas, e2e.

El mínimo de atributos por span: id de la función y de la sesión, modelo, resultado de la comprobación, tokens y número de reintentos. Estos datos se leen en Jaeger, Grafana Tempo o Honeycomb y responden preguntas que no se ven en una sola sesión: qué tipo de tareas necesita más reintentos, dónde gasta más tokens el agente, después de qué cambio del harness cayó la proporción de tareas aceptadas. Claude Code tiene una exportación integrada de métricas y eventos mediante OpenTelemetry; se activa con variables de entorno, y los detalles están en la documentación de la herramienta.

Los commits como diario

El diario más barato y fiable ya lo tiene: es git. Solo hay que hacerlo legible.

1. Un commit, una tarea. Así el git log coincide con la lista de lo hecho, y deshacer una tarea es un solo git revert.
2. En el mensaje, qué se hizo y cómo se comprobó. No «fix», sino qué se cambió, por qué y con qué comando se verificó.
3. Commit solo después de una comprobación en verde. Así cada punto de la historia es un estado de trabajo, y git bisect encuentra al culpable.

fix(payments): redondeo del descuento a céntimos

El descuento se calculaba en float; con un importe de 999.99 se perdía un céntimo.
Se pasó el cálculo a int en céntimos.
Comprobado: make test (142 passed), make e2e checkout — ok.
Fuera de alcance: redondeo en los informes, anotado en BACKLOG.md.

Informe del agente: pruebas en lugar de impresiones

El mensaje final del agente también es un artefacto de observabilidad, siempre que tenga una forma fija. Fije una plantilla en AGENTS.md o en CLAUDE.md:

## Informe al terminar la tarea
- Qué se hizo: lista de cambios (archivo — qué)
- Cómo se comprobó: comandos exactos y su resultado
- Qué NO se comprobó y por qué
- Desviaciones del acuerdo sobre la tarea
- Preguntas abiertas para la persona

La regla principal: cada afirmación remite a una prueba: un archivo y una línea, la salida de un test, una entrada del diario. «Tiene buena pinta» y «me parece bien» no cuentan como informe. El punto «qué no se comprobó» es especialmente valioso, porque muestra con honestidad los límites de la confianza.

Acuerdo antes del código y rúbrica después

La capa de proceso empieza antes del trabajo. Un acuerdo breve sobre la tarea (sprint contract) fija el alcance, los criterios de aceptación, el apartado «fuera de alcance» y las preguntas abiertas que decide la persona. El apartado «fuera de alcance» evita la mitad de las discusiones sobre el resultado.

Después del trabajo, el resultado se evalúa con una rúbrica, no con una impresión. Si no, dos revisores experimentados darán veredictos distintos y la evaluación se convertirá en una lotería.

Cada dimensión se puntúa de la A a la D, y una puntuación sin referencia no es válida. Regla simple de decisión: una D o dos C, rechazar con una lista de lo que hay que corregir. La misma rúbrica puede aplicarla un agente verificador separado.

Cómo revisar lo que hizo el agente durante una sesión

Si no hay informe o no se le puede tener confianza, recorra los artefactos en este orden.

1. Estado del árbol: git status: qué no está confirmado y si hay archivos basura.
2. Historia: git log --stat desde el inicio de la sesión: qué commits y archivos.
3. Alcance de los cambios: git diff --stat main...HEAD y luego el diff completo de los archivos importantes.
4. Diario de acciones: qué comandos se ejecutaron y qué devolvieron las comprobaciones.
5. Nueva comprobación: ejecute usted mismo el build y las pruebas. Fíese de la salida del comando, no del relato.

# qué comandos ejecutó el agente en la última sesión
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# qué archivos se modificaron con más frecuencia
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Errores típicos

• Registrarlo todo. Los gigabytes de transcripciones no los lee nadie. Registre las acciones con efectos secundarios y los resultados de las comprobaciones.
• Formato libre. Si el formato del diario lo decide el agente, no habrá agregados. El formato lo fija el harness.
• Creer el informe sin la salida de los comandos. «Las pruebas están en verde» sin la salida es una opinión.
• Reintentos a ciegas. Sin la causa del fallo, el agente corrige lugares al azar. Exija primero un diagnóstico con referencia al log, y solo después el cambio.
• «Lo quitamos después». Los archivos de depuración y los cambios sin confirmar confunden a la siguiente sesión: no distinguirá lo temporal de lo intencionado.

Resumen

La observabilidad de los agentes de IA se construye con dos capas: el runtime (diario de acciones mediante hooks, trazas, commits con la descripción de las comprobaciones) y el proceso (acuerdo sobre la tarea antes del código, rúbrica e informe con referencias a las pruebas). Así, «listo» significa lo mismo en cada sesión y revisar el trabajo del agente lleva minutos. Este tema se explica en la práctica dentro del curso de harness engineering, en un proyecto de ejemplo de backend de pagos.