Rastreo de llamadas de herramientas de Agente IA: Qué registrar en cada solicitud

Rastreos de agentes de IA: qué registrar para depurar, auditar y probar

Un usuario informa que el agente “hizo algo raro” ayer por la tarde. Abres los registros y solo encuentras que llamó a updateOrder, recibió un 200 y completó la ejecución. No sabes con qué argumentos, contra qué orden, por qué eligió esa herramienta ni qué devolvió.

Prueba Apidog hoy

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Los sistemas de agentes fallan de formas que solo tienen sentido en retrospectiva. Por eso, el registro es parte del producto.

Esta guía explica qué registrar en cada llamada a herramienta, cómo correlacionar una decisión del modelo con la solicitud HTTP resultante, cómo redactar datos sensibles y cómo convertir rastreos en pruebas reproducibles. Para la capa de servicio, consulta esta guía sobre observabilidad de API.

Apidog resulta especialmente útil una vez que tienes un rastreo: puedes reproducir una llamada errónea contra el mismo endpoint, inspeccionar su comportamiento y guardarla como prueba.

Tres capas, un solo rastreo

Cada ejecución de un agente produce eventos en tres capas:

1. Razonamiento: contexto disponible, herramientas ofrecidas, herramienta elegida y argumentos generados.
2. Herramientas: validación de argumentos, aplicación de políticas, transformación a HTTP y manejo del resultado.
3. HTTP: método, URL, encabezados, cuerpo, estado y latencia.

Los incidentes casi siempre cruzan capas:

• “El agente envió la ID de cliente incorrecta” es una decisión del modelo visible en la solicitud HTTP.
• “La API devolvió 200 con un cuerpo vacío” es un problema HTTP que puede producir razonamiento extraño varios pasos después.

La regla base es simple:

• Una trace_id por ejecución del agente.
• Una span_id por llamada a herramienta.
• Ambas IDs en todos los registros de las tres capas.

Los rastreos de OpenTelemetry ya modelan esta estructura. Complementa el esquema con las convenciones semánticas GenAI para mantener los datos portables.

Qué registrar en cada llamada a herramienta

Un evento útil debería tener esta forma:

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
  "tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": { "prompt": 8420, "completion": 96 },
  "policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}

Prioriza estos campos:

Campo	Por qué importa
tool_args	Registra los argumentos generados por el modelo antes de normalizarlos. Aquí se revela una ID incorrecta.
tools_available	Explica la selección: muestra qué alternativas tenía el modelo.
retry_count	Distingue una API lenta de una llamada que falló dos veces antes de funcionar.
outcome	Usa un enum explícito: success, failed, timed_out, blocked_by_policy, rejected_by_human.
policy	Conserva el rastro de aprobación, bloqueo y ejecución en modo simulación.

No infieras el resultado a partir de un código HTTP. Una llamada bloqueada por política no es un fallo: es una barrera de seguridad funcionando. Consulta también las barreras de seguridad para agentes de IA.

Registra la decisión, no solo la acción

Los incidentes difíciles suelen ser errores de selección. Para reconstruirlos, registra lo siguiente en cada ejecución:

• Definiciones o hash del conjunto de herramientas. Si una selección empeora, compara el hash entre una ejecución buena y una mala. Una edición en la descripción de una herramienta puede cambiar mucho el comportamiento. Consulta el diseño de esquemas de herramientas de API.
• Modelo y configuración. Incluye ID del modelo, temperatura y versión del prompt.
• Contexto recibido. Si no puedes almacenar el prompt completo, conserva su hash y número de tokens.
• Resultado bruto de la herramienta. Guarda la carga útil completa antes de recortarla para el modelo. De otro modo, no sabrás si faltaban datos o si tu ejecutor los eliminó. Consulta cómo mantener respuestas de herramientas fuera de la ventana de contexto.

Redacta antes de almacenar

Los rastreos de agentes pueden contener solicitudes, respuestas, prompts y datos personales. Aplica estas reglas en el límite de registro:

1. Nunca almacenes credenciales. Elimina Authorization, claves API, cookies y URLs firmadas. Registra un identificador de credencial, no su valor. Las claves API con privilegios mínimos para agentes ayudan a identificar qué agente actuó sin exponer secretos.
2. Redacta antes de enviar el evento. Filtrar durante la consulta es demasiado tarde: el secreto ya pudo escribirse, replicarse o respaldarse.
3. Hashea cuerpos que no puedas conservar. Un hash permite verificar que dos solicitudes fueron idénticas sin almacenar la carga útil.
4. Define retención por sensibilidad. Por ejemplo: rastros completos durante una semana y resúmenes redactados durante un año.

Convierte rastreos en pruebas

Cada ejecución fallida puede convertirse en una prueba de regresión:

1. Extrae las llamadas a herramientas del rastreo.
2. Reconstruye la solicitud contra el mismo endpoint.
3. Guarda el caso fallido en Apidog.
4. Añade aserciones para el comportamiento corregido.
5. Ejecútalo en CI.

Así, un incidente puntual se convierte en cobertura permanente.

Los rastreos también indican qué simular: los endpoints más usados por el agente y los fallos que realmente encuentra. Construye simulaciones a partir de esos datos y ejecuta los agentes contra ellas, siguiendo esta guía para usar simulaciones en lugar de producción.

Además, vigila cambios en la distribución de herramientas, reintentos, llamadas por tarea y bloqueos de política. Las pruebas de contrato de API pueden detectar cambios ascendentes antes de que se conviertan en incidentes.

Tres investigaciones que tu rastreo debe resolver

“El agente cobró al cliente equivocado”

Necesitas:

• Los tool_args generados por el modelo.
• La URL HTTP final.
• El resultado de la herramienta anterior.
• El paso inmediatamente anterior.

En muchos casos, una herramienta devolvió varias coincidencias y el modelo eligió la primera. Sin los argumentos y el resultado anterior, solo tendrás un 200 y un cliente descontento.

“Dejó de funcionar el martes”

Compara una ejecución buena y una mala campo por campo:

• ID del modelo.
• Hash del conjunto de herramientas.
• Versión del prompt.
• Tamaño promedio de las respuestas.

Algo cambió. Si ambas ejecuciones registran los mismos campos, normalmente podrás identificarlo rápido.

“¿Alguien aprobó esta acción?”

El bloque policy debe responderlo directamente:

{
  "approval_required": true,
  "approved_by": "user_31",
  "approved_at": "2026-08-26T14:03:11.482Z"
}

Escribe estos datos en el momento de la decisión, no intentes reconstruirlos después.

Muestreo: qué conservar siempre

El rastreo completo de cada ejecución puede resultar caro. Muestrea por señal, no solo por volumen.

Conserva siempre:

• Ejecuciones fallidas.
• Ejecuciones bloqueadas por política.
• Ejecuciones con escrituras o acciones destructivas.

Muestrea:

• Ejecuciones exitosas de solo lectura.
• Rastros completos con cuerpos y prompts de alto volumen.

Incluso si eliminas las cargas útiles, conserva un rastreo mínimo con nombres de herramientas, resultados y duraciones. Es suficiente para medir tendencias y responder preguntas operativas.

El capítulo de monitoreo del libro SRE de Google explica por qué conviene muestrear según señal y no únicamente por volumen.

Si usas muestreo de cola, decide qué conservar después de conocer el resultado final. Una ejecución que parece correcta en el paso tres y falla en el paso nueve debe conservarse completa.

Dónde debe vivir el rastreo

Si el agente es un servicio propio que llama a tus APIs, el almacenamiento del rastreo suele ser tu responsabilidad.

Pero los agentes de programación ejecutados en máquinas de desarrolladores plantean otra necesidad: el rastreo debería vivir junto a la tarea. Sharkly adopta este modelo: el historial de ejecución, los registros y el resultado se adjuntan a la tarea asignada al agente.

Esto no reemplaza el rastreo técnico ni el tiempo de ejecución. Herramientas como Claude Code y Codex siguen haciendo el trabajo. Lo que cambia es dónde encuentras la respuesta a: “¿Por qué hizo esto el agente?”.

Vigila cuatro métricas

Estos indicadores merecen espacio en un panel:

1. Llamadas por tarea completada. Si aumenta, el agente está explorando más o una dependencia empezó a fallar.
2. Tasa de reintentos por endpoint. Identifica dependencias poco fiables y degradaciones. Consulta la guía sobre recuperación de errores de agentes de IA.
3. Tasa de bloqueos por política. Debe ser baja y estable. Un pico puede indicar acciones indebidas o una política demasiado restrictiva.
4. Tiempo hasta la primera llamada a herramienta. Un inicio lento suele revelar un prompt inflado.

Lista de verificación

• [ ] Una trace_id por ejecución y una span_id por llamada de herramienta.
• [ ] IDs de rastreo en las capas de razonamiento, herramientas y HTTP.
• [ ] Argumentos del modelo registrados antes de normalizarlos.
• [ ] Lista de herramientas disponibles en cada llamada.
• [ ] Resultado como enum explícito, incluidos los bloqueos de política.
• [ ] Reintentos separados del número de llamadas.
• [ ] Modelo, temperatura, versión del prompt y hash del conjunto de herramientas.
• [ ] Resultados brutos de herramientas antes de recortarlos.
• [ ] Credenciales eliminadas en el middleware.
• [ ] Cuerpos hasheados cuando no puedan almacenarse.
• [ ] Retención escalonada según sensibilidad.
• [ ] Rastros fallidos convertidos en pruebas reproducibles.

El objetivo es sencillo: cuando alguien pregunte por qué el agente hizo algo, debes poder responder desde el registro, no desde una suposición. Descarga Apidog para reproducir llamadas de un rastreo y convertirlas en pruebas guardadas.

Preguntas frecuentes

¿Debo usar OpenTelemetry o una herramienta de observabilidad específica para agentes?

Usa OpenTelemetry para el transporte y el modelo de rastreo: ya resuelve la correlación y suele integrarse con tu infraestructura. Las herramientas específicas para agentes pueden añadir vistas útiles, pero los datos subyacentes deberían seguir siendo portables.

¿Cuánto cuesta almacenar un rastreo completo?

Menos de lo esperado si aplicas retención por niveles. Conserva cargas útiles completas durante unos días y registros estructurados sin cuerpos durante más tiempo. Los volcados de prompts suelen ser la parte costosa: hashea el contenido y registra su tamaño en lugar de almacenarlo por defecto.

¿Necesito registrar el texto de razonamiento del modelo?

Normalmente no. La herramienta elegida, los argumentos generados y las alternativas disponibles explican la mayoría de las decisiones. Si un proveedor expone razonamiento, almacénalo solo para ejecuciones fallidas y trátalo como información sensible.

¿Cómo rastreo múltiples agentes?

Mantén una trace_id para toda la tarea y asigna un span a cada agente. Registra cada transferencia como un evento. Consulta qué incluir en ese evento en la guía sobre transferencia de contexto entre agentes.

¿Qué ocurre si el agente se ejecuta en la máquina de un cliente?

Registra localmente, redacta de forma agresiva y envía solo métricas agregadas salvo que la persona usuaria acepte compartir más datos. Los nombres de herramientas, resultados y duraciones suelen ser suficientes para monitoreo de flota sin enviar cargas útiles fuera del dispositivo.

¿Un hash del cuerpo de la solicitud realmente sirve?

Sí. Permite demostrar que dos llamadas fueron idénticas, lo que resuelve muchas investigaciones de escrituras duplicadas sin conservar el cuerpo. Combínalo con claves de idempotencia para evitar que esas duplicaciones ocurran.