Un usuario informa que el agente "hizo algo raro" ayer por la tarde. Abres los registros y encuentras esto:
INFO agent run started
INFO calling tool: updateOrder
INFO tool returned 200
INFO agent run completed
El agente llamó a updateOrder. No sabes con qué argumentos, contra qué orden, por qué eligió esa herramienta, o qué regresó. La ejecución tuvo éxito según todas las métricas que registraste, y no puedes reconstruir una sola decisión que tomó.
Los sistemas de agentes fallan de maneras que solo tienen sentido en retrospectiva, lo que significa que el registro es el producto. Esta guía cubre qué registrar en cada llamada a una herramienta, cómo correlacionar una decisión del modelo con la solicitud HTTP que produjo, qué redactar y cómo convertir los rastreos en pruebas. Nuestra publicación sobre la observabilidad de API cubre el lado del servicio; esta cubre la capa del agente que se encuentra encima.
Apidog es útil una vez que tienes un rastreo, porque la forma más rápida de entender una llamada errónea es reproducirla contra el mismo endpoint y observar qué sucede.
Tres capas, un rastreo
Un agente produce eventos en tres niveles, y la mayoría de los equipos solo registran el del medio.
La capa de razonamiento es donde el modelo decide. Qué estaba en contexto, qué herramientas se ofrecieron, cuál eligió y con qué argumentos.
La capa de herramientas es su ejecutor. Valida argumentos, aplica políticas, mapea la llamada a una solicitud HTTP y maneja el resultado.
La capa HTTP es la conexión. Método, URL, encabezados, cuerpo, estado, latencia.
La depuración casi siempre cruza capas. "El agente envió la ID de cliente incorrecta" es un problema de razonamiento visible solo en la capa HTTP. "La API devolvió un 200 con un cuerpo vacío" es un problema HTTP que se manifiesta como un razonamiento extraño tres pasos después. Si las tres capas no están unidas por un identificador compartido, estás atascado correlacionando por marca de tiempo, lo que deja de funcionar en el momento en que dos ejecuciones se superponen.
Así que la primera regla: una ID de rastreo por ejecución de agente, una ID de span por llamada de herramienta, y ambas marcadas en cada registro en cada capa. Los rastreos de OpenTelemetry ya modelan exactamente esta forma, y hay un conjunto creciente de convenciones semánticas GenAI para nombrar los atributos de modo que sus datos sean portátiles.
Qué registrar en cada llamada a una herramienta
Un registro que responde preguntas reales tiene aproximadamente 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 }
}
Cinco campos realizan un trabajo desproporcionado.
tool_args es el que falta con más frecuencia, y es el que siempre querrá. Registre los argumentos que produjo el modelo, antes de que su ejecutor los normalice. Cuando un agente envía la ID incorrecta, aquí es donde se hace visible.
tools_available explica la selección. Si el modelo eligió una herramienta extraña, la primera pregunta es de qué más disponía. Este campo cuesta unos pocos bytes y responde al instante.
retry_count separa "la API fue lenta" de "la API falló dos veces y luego funcionó". Sin él, tres intentos parecen una sola llamada.
outcome debe ser un enum explícito, no algo inferido de un código de estado. success (éxito), failed (falló), timed_out (agotó el tiempo), blocked_by_policy (bloqueado por política), rejected_by_human (rechazado por humano). Los dos últimos importan porque una llamada bloqueada es una barrera de seguridad que funciona, no un error, y mezclarlos corrompe su tasa de fallos.
policy es su rastro de auditoría. Cuando alguien pregunta si se aprobó una acción destructiva, esta es la respuesta. Se combina con la aplicación descrita en nuestra publicación sobre barreras de seguridad para agentes de IA.
Registre la decisión, no solo la acción
Los errores más difíciles de los agentes son las elecciones, así que registre lo suficiente para reconstruirlos.
Conserve las definiciones de herramientas utilizadas para la ejecución, o un hash de ellas. Cuando la precisión de la selección cambia, el primer sospechoso es una descripción que alguien editó, y un hash le dice inmediatamente si el conjunto de herramientas cambió entre una ejecución buena y una mala. Nuestra publicación sobre el diseño de esquemas de herramientas de API cubre por qué ese texto mueve tanto el comportamiento.
Registre el modelo y su configuración. ID del modelo, temperatura y versión del prompt pertenecen al registro de ejecución. El comportamiento cambia entre versiones del modelo, y sin este campo pasará un día investigando su propio código.
Registre lo que vio el modelo, o al menos su tamaño. Un volcado completo del prompt es costoso de almacenar y a menudo sensible. Un recuento de tokens más un hash le da la mayor parte del valor de diagnóstico: una ejecución cuyo prompt tiene el doble del tamaño habitual es una ejecución en la que se añadió algo que no debería haber sido.
Registre el resultado crudo de la herramienta antes de recortar. Si su ejecutor proyecta las respuestas hacia abajo antes de entregarlas al modelo, como en nuestra publicación sobre mantener las respuestas de las herramientas fuera de la ventana de contexto, almacene la carga útil completa en el rastreo. De lo contrario, no podrá saber si los datos faltaban o si usted los eliminó.
Redacte antes de almacenar
Los rastreos de agentes son inusualmente peligrosos porque contienen tanto la solicitud como el razonamiento a su alrededor, y los prompts tienen la costumbre de recopilar datos personales.
Cuatro reglas hacen que esto sea manejable.
Nunca almacene credenciales. Elimine Authorization, claves API, cookies y cualquier URL firmada. Registre el identificador de la credencial, como una ID de clave, y no el valor. Nuestra publicación sobre claves API con privilegios mínimos para agentes cubre por qué desea ese identificador: le dice qué agente actuó.
Redacte en el límite, no en la consulta. Filtrar en el momento de la lectura significa que el secreto se escribió en el disco, se replicó y se hizo una copia de seguridad. Redacte en el middleware de registro antes de que el registro salga del proceso.
Hash los cuerpos que no puede almacenar. Un hash del cuerpo de la solicitud aún le permite probar que dos llamadas fueron idénticas, que es la mayor parte de lo que necesita para las investigaciones de duplicados, sin mantener la carga útil.
Establezca la retención por sensibilidad. Rastros completos durante una semana, resúmenes redactados durante un año. La mayoría de la depuración ocurre en días; la mayoría de las preguntas de auditoría llegan en meses.
Convierta los rastreos en pruebas
La recompensa de un buen rastreo no es solo una depuración más rápida. Es un suministro de casos de prueba realistas.
Cada ejecución fallida es un escenario. Tome las llamadas a herramientas de un rastreo defectuoso, reprodúzcalas contra su API y tendrá una reproducción. Cuando llegue la corrección, conserve la reproducción como una prueba de regresión. En Apidog, puede reconstruir la solicitud fallida como un caso guardado, afirmar el comportamiento corregido y ejecutarla en CI, que es como un incidente puntual se convierte en cobertura permanente.
Los rastreos también le dicen qué simular. Los endpoints que su agente llama más, y los estados de fallo que realmente encuentra, provienen directamente de los datos en lugar de suposiciones. Construya las simulaciones alrededor de ellos, siguiendo nuestra publicación sobre ejecutar agentes contra simulaciones en lugar de producción.
Y sacan a la luz la lenta desviación que de otro modo se perdería. Rastree algunos números por semana: distribución de selección de herramientas, tasa de reintentos por endpoint, llamadas por tarea completada y el porcentaje de ejecuciones bloqueadas por política. Un cambio en cualquiera de ellos es una señal antes de que se convierta en un incidente. Las verificaciones a nivel de contrato, como en nuestra guía de pruebas de contrato de API, detectan el cambio ascendente que usualmente lo causó.
Tres investigaciones que el rastreo debe sobrevivir
"El agente le cobró al cliente equivocado." Necesita los argumentos que produjo el modelo, la URL resuelta y el paso anterior. Nueve de cada diez veces, la ID provino de un resultado de herramienta anterior que devolvió más de una coincidencia y el modelo eligió la primera. El rastreo muestra el resultado anterior, la ambigüedad y la elección. Sin tool_args, tiene un 200 y un cliente muy descontento.
"Dejó de funcionar el martes." Compare 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 la respuesta. Algo cambió, y uno de esos cuatro suele nombrarlo. Por eso el registro de ejecución contiene la configuración y no solo los eventos: una diferencia solo es posible cuando ambas partes registraron los mismos campos.
"¿Alguien aprobó esto?" El bloque de política es la respuesta completa, y debe escribirse en el momento de la decisión, no reconstruirse después. approval_required (aprobación requerida), approved_by (aprobado por) y una marca de tiempo convierten una conversación tensa en una consulta.
Observe lo que tienen en común. Ninguna de estas preguntas se responde con "la herramienta devolvió 200". Las tres se responden con campos que cuestan casi nada escribir y son imposibles de recuperar después del hecho.
Muestreo, y lo que nunca se debe muestrear
El rastreo de alta fidelidad en cada ejecución se vuelve costoso a gran volumen, por lo que los equipos muestrean. Muestree con cuidado, porque el tráfico de agentes no es uniforme.
Siempre conserve cada ejecución fallida, cada ejecución que activó un bloqueo de política y cada ejecución que contenga una escritura. Esas son las ejecuciones sobre las que cualquiera preguntará. Muestree las ejecuciones exitosas de solo lectura, ya que son la mayor parte del volumen y las menos interesantes individualmente, aunque aún querrá suficientes para calcular sus líneas base.
El capítulo del libro SRE de Google sobre monitoreo sigue siendo la declaración más clara de por qué se muestrea por señal en lugar de por volumen, y el razonamiento se aplica directamente.
Conserve el registro de ejecución incluso si elimina las cargas útiles. Un rastreo esquelético con nombres de herramientas, resultados y duraciones es pequeño y aún soporta las cuatro métricas anteriores. Las partes costosas son los cuerpos y los prompts, y esas son las partes que puede eliminar primero.
Una advertencia sobre el muestreo de cola: si decide qué conservar después de que una ejecución finaliza, asegúrese de que la decisión ocurra después de que se conozca el resultado. Una ejecución que parece correcta en el paso tres y falla en el paso nueve debe conservarse por completo, lo que significa almacenar en búfer en lugar de descartar sobre la marcha.
Dónde debería vivir el rastreo
Todo lo anterior asume que usted es propietario del almacenamiento. Esa es la suposición correcta cuando el agente es su propio servicio que llama a sus propias API. Es un ajuste deficiente cuando los agentes son tiempos de ejecución de codificación en las máquinas de los desarrolladores, porque el rastreo vive entonces en la terminal que lo ejecutó.
Sharkly adopta el otro enfoque: el rastreo de ejecución se adjunta a la Tarea asignada al agente. El historial de ejecución, el registro de ejecución y el resultado se encuentran junto al objetivo, el estado y el hilo de comentarios donde un humano revisó el trabajo. La diferencia práctica es la recuperación. "¿Por qué hizo eso el agente?" se convierte en una pregunta que usted responde abriendo la tarea, en lugar de encontrar la máquina, la sesión y el historial.
No reemplaza el rastreo descrito aquí, y tampoco reemplaza el tiempo de ejecución; Claude Code y Codex aún hacen el trabajo. Lo que sí cambia es dónde termina el registro cuando el agente no es un servicio que usted implementó.
Vigile cuatro números
Los rastreos solo son útiles si alguien los mira. Estos cuatro se ganan su lugar en un panel de control.
Llamadas por tarea completada. La medida de eficiencia más clara. Si aumenta, el agente está explorando más, generalmente porque una descripción empeoró o un endpoint comenzó a fallar.
Tasa de reintentos por endpoint. Clasifica sus dependencias menos fiables y muestra cuándo una se degrada. Nuestra publicación sobre la recuperación de errores de agentes de IA cubre qué hacer con la parte superior de esa lista.
Tasa de bloqueos por política. Debería ser baja y estable. Un pico significa que el agente está intentando cosas que no debería, o que una política es demasiado estricta y ahora es el cuello de botella.
Tiempo hasta la primera llamada a la herramienta. Un inicio lento generalmente significa un prompt inflado, y el tamaño del prompt es algo que crece sin que nadie decida que crezca.
Una lista de verificación
- Una ID de rastreo por ejecución, una ID de span por llamada a herramienta, estampadas en las tres capas.
- Argumentos del modelo registrados antes de la normalización.
- La lista de herramientas disponibles registrada en cada llamada.
- Resultado registrado como un enum explícito, incluyendo los bloqueos por política.
- Recuento de reintentos separado del recuento de llamadas.
- Modelo, temperatura, versión del prompt y hash del conjunto de herramientas en el registro de ejecución.
- Resultados brutos de las herramientas almacenados, no solo la versión recortada entregada al modelo.
- Credenciales eliminadas en el middleware, cuerpos hasheados donde no se pueden almacenar.
- Retención por niveles según la sensibilidad.
- Rastros fallidos convertibles en casos de prueba reproducibles.
El objetivo es simple de establecer: cuando alguien pregunta por qué el agente hizo eso, usted puede responder desde el registro en lugar de adivinar. Descargue Apidog para reproducir las llamadas en un rastreo y guardar las reproducciones como pruebas.
Preguntas frecuentes
¿Debo usar OpenTelemetry o una herramienta de observabilidad de agentes creada específicamente? Use OpenTelemetry para el transporte y el modelo de rastreo, ya que ya maneja la correlación y su infraestructura probablemente lo entiende. Las herramientas específicas de agentes añaden vistas útiles; los datos subyacentes aún deben ser portátiles.
¿Cuánto cuesta almacenar un rastreo completo? Menos de lo que la gente espera, si lo organiza por niveles. Las cargas útiles completas durante unos días y los registros estructurados sin cuerpos durante más tiempo mantienen la mayor parte del volumen bajo. Los volcados de prompts son la parte costosa, así que hasheelós y mida su tamaño en lugar de almacenarlos por defecto.
¿Necesito registrar el texto de razonamiento del modelo? No usualmente. La herramienta que eligió, los argumentos que produjo y las opciones que tenía explican la mayoría de las decisiones. Cuando un proveedor expone el contenido de razonamiento, almacénelo solo para las ejecuciones fallidas y trátelo como sensible.
¿Cómo rastreo a través de múltiples agentes? Mantenga una ID de rastreo para toda la tarea y asigne a cada agente su propio span, registrando la transferencia como un evento. Nuestra publicación sobre la transferencia multi-agente cubre lo que debe incluirse en ese registro de transferencia.
¿Qué pasa si el agente se ejecuta en la máquina de un cliente? Registre localmente, redacte agresivamente y envíe solo métricas agregadas a menos que el usuario opte por ello. Los nombres de las herramientas, los resultados y las duraciones suelen ser suficientes para el monitoreo a nivel de flota sin que se envíen cargas útiles fuera del dispositivo.
¿Un hash del cuerpo de la solicitud es realmente útil? Sí, para las preguntas más comunes. Demuestra que dos llamadas fueron idénticas, lo que resuelve la mayoría de las investigaciones de escritura duplicada, sin mantener la carga útil en sí. Combínelo con las claves de idempotencia que deberían haber evitado el duplicado.