Una tarde de martes, después de doce intentos de depuración, mi agente afirmaba que el endpoint /users respondía en cuarenta y siete segundos. El valor real era cuarenta y siete milisegundos.
Llevaba dos días persiguiendo el error. Añadía print al servidor MCP, cambiaba el system prompt, comparaba respuestas del modelo y cada ejecución parecía acercarme a la causa. No era así.
Lo que faltaba era ver el rastro de ejecución completo: qué recibió el modelo, qué herramienta llamó, qué parámetros envió, qué devolvió la herramienta y cómo interpretó esos datos. Para eso usé el Depurador de Agentes de IA de Apidog. En doce minutos encontré el problema.
El error que estaba persiguiendo
La configuración era simple:
- Un agente sobre GPT-5.5
- Un servidor MCP propio
- Una herramienta
get_response_time(endpoint) - Un
system promptcorto - Una pregunta de usuario: “¿Qué tan rápido es el endpoint /users?”
El agente respondía rápido y con confianza, pero mal:
- “El endpoint está respondiendo en 47 segundos.”
- “Alrededor de 0.05 segundos.”
- “El rendimiento es aceptable.”
El problema al depurar agentes es que el fallo puede estar en varios puntos:
system prompt- elección del modelo
- definición de la herramienta
- parámetros enviados por el modelo
- datos devueltos por la herramienta
- interpretación final del modelo
Los logs normales suelen mostrar solo una parte. Necesitaba ver todo el intercambio.
Qué muestra el panel de Trazas
El depurador de Apidog organiza la sesión en tres columnas:
- Sesiones a la izquierda
- Turnos en el centro
- Trazas a la derecha
Al abrir una sesión, puedes inspeccionar cada paso del flujo:
-
System promptrecibido por el modelo -
User promptrecibido por el modelo - llamada a la herramienta, con nombre y parámetros en JSON
- resultado devuelto por la herramienta, también en JSON
- respuesta final del modelo
- tiempo, tokens y coste del turno
En mi caso, la llamada era correcta:
get_response_time(endpoint="/users")
El modelo había elegido la herramienta correcta y enviado el argumento correcto.
El problema apareció al expandir el resultado:
{
"value": 47,
"p95": 89,
"samples": 1240
}
La tubería de métricas devolvía milisegundos, pero la respuesta no incluía la unidad. El modelo asumió segundos.
La herramienta estaba bien. El modelo interpretó mal el valor. Mi system prompt tampoco indicaba cómo tratar unidades.
La solución tomó seis líneas
Corregí la respuesta del servidor MCP para hacer explícitas las unidades:
{
"value": {
"amount": 47,
"unit": "ms"
},
"p95": {
"amount": 89,
"unit": "ms"
},
"samples": 1240
}
Después añadí una instrucción al system prompt:
Los resultados de la herramienta devuelven las unidades explícitamente. Léalas con atención.
Volví a ejecutar la misma pregunta tres veces. Las tres sesiones devolvieron correctamente que /users respondía alrededor de 47 ms.
También ejecuté la misma prueba con Claude Opus 4.7 en otra sesión. Mismo resultado, mayor coste y una respuesta algo más larga. Con las métricas del panel izquierdo pude comparar:
- turnos
- pasos
- tiempo
- tokens
- coste
Antes hacía esa comparación en una hoja de cálculo. Aquí fueron unas pocas ejecuciones dentro del mismo flujo.
Lo que estaba haciendo mal
Estaba leyendo la salida del modelo e intentando adivinar la causa.
Eso no es depurar el agente. Es depurar una hipótesis sobre el agente.
Un agente es un sistema compuesto por:
- modelo
prompt- herramientas
- respuestas de herramientas
Si no puedes ver esos cuatro elementos juntos, el fallo queda oculto entre capas.
El depurador también reveló un segundo problema: no determinismo. Ejecuté el mismo prompt cinco veces después de la corrección:
- tres ejecuciones llamaron a
get_response_timeuna vez - dos ejecuciones la llamaron dos veces
- en esas dos, la segunda llamada usó una capitalización distinta en la ruta
Mi esquema de herramientas distinguía mayúsculas y minúsculas. No lo había detectado porque mis pruebas usaban rutas en minúsculas.
Regla práctica: ejecuta el mismo caso varias veces. Cualquier diferencia entre ejecuciones es una zona frágil del agente.
Configuración paso a paso
Si quieres reproducir un flujo similar, este es el proceso desde una instalación limpia hasta una sesión de depuración.
Paso 1: Crear una nueva sesión de depuración
Abre Apidog y entra en AI Agent Debugger desde la barra superior.
Configura:
- proveedor del modelo, por ejemplo OpenAI o Anthropic
- modelo específico, por ejemplo
gpt-5.5 - URL Base, que se rellena automáticamente al elegir proveedor
- botón Run para iniciar la sesión
Paso 2: Configurar los prompts
En la pestaña Prompts configura dos entradas:
- System Prompt: rol, objetivo, restricciones y reglas de uso de herramientas.
- User Prompt: entrada de prueba para la sesión.
Ejemplo:
System Prompt:
Eres un agente técnico. Usa las herramientas disponibles para responder con datos verificables. Lee cuidadosamente las unidades devueltas por las herramientas.
User Prompt:
¿Qué tan rápido es el endpoint /users?
Haz clic en Run cuando ambos estén listos.
Si quieres borrar el input después de cada ejecución, activa Clear after Send.
Paso 3: Configurar herramientas
La pestaña Tools lista las herramientas disponibles para el agente.
Puedes usar herramientas integradas o conectar herramientas MCP.
Herramientas integradas
| Herramienta | Qué hace |
|---|---|
bash |
Ejecuta comandos en una sesión de shell persistente |
web_fetch |
Busca contenido web y lo convierte a Markdown, texto o HTML |
read |
Lee archivos de texto, imagen o PDF |
edit |
Aplica reemplazos de cadena precisos a archivos |
write |
Crea o sobrescribe archivos |
grep |
Busca contenido de archivos con expresiones regulares |
glob |
Encuentra archivos usando patrones glob |
kill_shell |
Reinicia la sesión de shell actual |
Herramientas MCP
Las herramientas MCP permiten conectar sistemas externos o capacidades personalizadas mediante Servidores MCP.
Métodos de conexión disponibles:
- STDIO: inicia un proceso de Servidor MCP local
- HTTP: conecta con un Servidor MCP compatible con HTTP Streamable
- SSE: conecta con un Servidor MCP basado en Server-Sent Events
Si el servidor requiere autenticación, puedes usar encabezados de solicitud o flujos OAuth 2.0. Cuando la conexión sea correcta, selecciona qué herramientas expone el servidor al agente.
Paso 4: Configurar habilidades, autenticación y parámetros
Completa la configuración con estas pestañas.
Skills
Usa Skills para definir flujos de trabajo reutilizables. Son útiles para:
- tareas repetitivas
- flujos de proyecto estables
- reducir texto duplicado en
system prompts - cargar instrucciones bajo demanda en tiempo de ejecución
Authentication
Configura las credenciales necesarias para:
- servicios del modelo
- servicios MCP
- herramientas externas
Settings
Ajusta parámetros de ejecución del modelo, como:
- Temperatura
- Máx. Tokens
- Top P
Los parámetros compatibles dependen del proveedor. Verifica qué acepta realmente el modelo que estás usando.
Paso 5: Leer los tres paneles
Después de hacer clic en Run, la nueva sesión aparece en el panel izquierdo con un resumen como este:
Sesión 3
1 turno · 1 paso · 10s · 3.1k tokens · $0.02
gpt-5.5
Usa los paneles así:
- Panel de sesiones: historial de ejecuciones con métricas resumidas.
- Panel de turnos: cada ronda usuario/modelo.
- Panel de trazas: ejecución completa del agente en orden.
En el panel de trazas puedes revisar:
system promptuser prompt- llamadas al modelo
- razonamiento del modelo, si el modelo lo expone
- llamadas a herramientas MCP
- ejecuciones de Skills
- parámetros de entrada
- resultados de herramientas
- tiempo consumido
- errores
- salida final
Cuando una herramienta falla o el modelo devuelve una excepción, el paso fallido queda visible con sus entradas y salidas. No necesitas reconstruir el flujo desde logs separados.
Paso 6: Comparar modelos
Para comparar modelos, mantén constante:
- mismo
system prompt - mismo
user prompt - mismas herramientas
- mismos parámetros relevantes
Luego cambia solo el modelo y ejecuta de nuevo.
Métricas útiles:
- número de pasos para completar la tarea
- precisión al elegir herramientas
- tiempo de respuesta
- consumo de tokens
- coste
- variación entre ejecuciones
Este flujo sirve para decidir qué modelo llevar a producción sin depender solo de la calidad aparente de una respuesta.
Checklist práctico para depurar agentes
Cuando un agente responda mal, revisa en este orden:
Prompt recibido por el modelo
Confirma que elsystem prompty eluser promptson exactamente los esperados.Herramienta elegida
Verifica si el modelo llamó la herramienta correcta.Parámetros enviados
Revisa nombres, tipos, capitalización y valores.Respuesta de la herramienta
Comprueba si el JSON es ambiguo, incompleto o carece de unidades.Interpretación del modelo
Evalúa si el modelo transformó correctamente los datos devueltos.Variación entre ejecuciones
Ejecuta el mismo caso varias veces y busca diferencias.
En mi caso, el error estaba en el punto 4: la respuesta de la herramienta no incluía unidades. El modelo completó el vacío con una suposición incorrecta.
Conclusión
El error no estaba en el endpoint, ni en la herramienta MCP, ni en el modelo por sí solo. Estaba en la frontera entre la respuesta de la herramienta y la interpretación del modelo.
Ese es el tipo de fallo que los logs tradicionales no siempre muestran bien.
El valor del Depurador de Agentes de IA de Apidog está en ver el sistema completo: prompts, llamadas, parámetros, resultados, costes y variaciones entre ejecuciones.
Descarga Apidog y úsalo la próxima vez que un agente responda con seguridad pero esté equivocado.
La referencia completa de funciones, configuración de transporte MCP y disponibilidad del plan está en Depurador de Agentes de IA de Apidog: disponibilidad, cobertura y configuración.
Top comments (0)