Una tarde de martes. Doce intentos en una sesión de depuración, y el agente me decía con confianza que nuestro endpoint /users respondía en cuarenta y siete segundos. El número real era cuarenta y siete milisegundos.
Llevaba dos días persiguiendo este error. Cada vez que añadía una sentencia `print` al servidor MCP, la respuesta del agente cambiaba lo suficiente como para hacerme pensar que estaba progresando. Cada vez que reescribía el `system prompt`, la respuesta sonaba más plausible. Nada de eso era correcto.
Lo que no había hecho, hasta esa tarde, era abrir el rastro de ejecución real y ver qué se estaba pasando entre el modelo y la herramienta. Para eso sirve el Depurador de Agentes de IA de Apidog. Lo había instalado tres semanas antes y lo había olvidado. Me llevó doce minutos encontrar el error.
Esto es lo que me sorprendió.
El error que había estado persiguiendo
La configuración era sencilla. Un agente construido sobre GPT-5.5. Un servidor MCP que había escrito en un fin de semana, que exponía una herramienta get_response_time(endpoint) que consultaba nuestra tubería de métricas. Un `system prompt` de quizás cuarenta palabras. La pregunta del usuario: "¿Qué tan rápido es el endpoint /users?"
El agente respondió rápido. Respondió con confianza. Respondió mal, cada vez, de diferentes maneras. A veces "el endpoint está respondiendo en 47 segundos." A veces "alrededor de 0.05 segundos." Una vez, memorablemente, "el rendimiento es aceptable."
Había estado haciendo lo que se hace. Añadiendo `logging` al servidor MCP. Leyendo la respuesta del modelo token por token. Comparando `system prompts`. Maldiciendo. Tenía tres ventanas de terminal abiertas y una página de Notion de hipótesis fallidas para el martes por la mañana.
Lo que ocurre al depurar agentes es que el error rara vez se encuentra donde se busca primero. Puede estar en el `system prompt`, en la elección del modelo, en la definición de la herramienta, en los parámetros que el modelo pasó a la herramienta, en los datos que la herramienta devolvió, o en cómo el modelo interpretó esos datos. Seis lugares. Una consola de registros te muestra uno.
Lo que realmente muestra el panel de Trazas
El depurador de Apidog se abre en tres columnas. Sesiones a la izquierda. Turnos en el medio. Trazas a la derecha. Haz clic en cualquier sesión y la columna central te muestra el diálogo: mensaje del usuario, respuesta del modelo, llamada a la herramienta, resultado de la herramienta, siguiente respuesta del modelo. Haz clic en cualquier turno y la columna de la derecha se expande en el árbol de ejecución completo debajo.
El árbol de ejecución era la parte que me faltaba. Cada paso, en orden:
- `System prompt` tal como lo recibió el modelo
- `User prompt` tal como lo recibió el modelo
- Nombre y parámetros de la llamada a la herramienta, como JSON, exactamente como los emitió el modelo
- Carga útil del resultado de la herramienta, como JSON, exactamente como la devolvió la herramienta
- Respuesta del modelo, con tiempo y tokens para el turno
Abrí la sesión fallida. La llamada a la herramienta parecía correcta: get_response_time(endpoint="/users"). El modelo había elegido la herramienta correcta con el argumento correcto.
Luego expandí el resultado de la herramienta.
{"value": 47, "p95": 89, "samples": 1240}
Ahí estaba. La tubería de métricas devolvía el valor en milisegundos. El modelo asumía segundos. 47 se convirtió en "47 segundos" a través de una alucinación segura que no se molestó en cuestionar la unidad. La herramienta era correcta. El modelo estaba equivocado. Mi `system prompt` no tenía instrucciones sobre unidades, y la respuesta de la herramienta no tenía anotación de unidad.
Doce minutos desde que abrí el depurador. Dos días había estado culpando al `system prompt`.
La solución tomó seis líneas
Cambié dos cosas. En el servidor MCP, actualicé la forma de la respuesta:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Luego agregué una oración al `system prompt`: "Los resultados de la herramienta devuelven las unidades explícitamente. Léalas con atención."
Ejecuté la misma pregunta de /users tres veces más. Tres sesiones diferentes en el panel izquierdo. Las tres devolvieron correctamente "el endpoint está respondiendo en alrededor de 47 ms" con un desglose de milisegundos a percentiles en el razonamiento del modelo. El costo de los tokens fue dieciocho por ciento más bajo que mis ejecuciones fallidas, probablemente porque el modelo no estaba generando prosa de recuperación en torno a sus propias suposiciones erróneas.
Ejecuté la misma pregunta en Claude Opus 4.7 en una segunda sesión, una al lado de la otra. Mismo resultado, el doble de costo, ligeramente más verboso. Sabía qué modelo iría a producción.
Esta es la parte de la herramienta que se ganó mi respeto. No la capacidad de encontrar errores, que cualquier depurador decente debería hacer. La comparación de modelos, ejecutada en configuraciones idénticas con métricas resumidas en el panel izquierdo: recuento de turnos, recuento de pasos, tiempo, tokens, dólares. Había estado haciendo esa comparación en una hoja de cálculo de Google durante seis meses. Ahora eran tres clics.
Lo que había estado haciendo mal
La interpretación fácil es que el Depurador de Agentes de IA es una herramienta de registro. No lo es. Las herramientas de registro te muestran lo que sucedió. El depurador te muestra lo que el modelo y la herramienta realmente intercambiaron, que es una capa diferente.
Si escribes agentes y has estado haciendo lo que yo hacía, que es leer la salida del modelo y adivinar la causa de los fallos, aquí hay algo en lo que insistiría. No estás depurando el agente. Estás depurando tu hipótesis sobre el agente. Son cosas diferentes, y solo una de ellas te lleva a una solución.
Lo que me había negado a interiorizar durante seis meses era que el agente es un sistema cerrado entre el modelo, el `prompt`, las herramientas y las respuestas de las herramientas. El error siempre reside en uno de esos cuatro. Si puedes ver los cuatro al mismo tiempo, puedes encontrar el error en doce minutos. Si no puedes, puedes perseguirlo durante una semana.
La otra cosa que el depurador reveló, y que no esperaba, fue el no determinismo en mi propio agente. Ejecuté el mismo `prompt` cinco veces después de la corrección, solo para confirmar. Tres ejecuciones llamaron a `get_response_time` una vez. Dos ejecuciones lo llamaron dos veces, la segunda vez con la ruta del endpoint en diferente capitalización. Mi esquema de herramientas distinguía mayúsculas y minúsculas. No me había dado cuenta porque todos mis casos de prueba fallidos usaban minúsculas. Ese fue un segundo error que habría lanzado sin verlo.
El análisis de múltiples ejecuciones es la característica que más voy a usar en el futuro. Haz clic en "Ejecutar" cinco veces. Mira el panel de sesiones. Cualquier cosa que varíe entre las ejecuciones es un lugar donde tu agente es frágil.
Pruébalo tú mismo: una guía completa de configuración
Si quieres tener la misma configuración que yo tenía abierta durante la búsqueda de errores, aquí tienes el camino desde una instalación nueva hasta una sesión de depuración en funcionamiento. Cinco pantallas, en orden.
Paso 1: Crear una nueva sesión de depuración de agentes
Abre Apidog y haz clic en AI Agent Debugger en la barra de pestañas superior. La sección superior de la página configura el modelo y el estado de ejecución.
- Selecciona el proveedor del modelo a la izquierda (OpenAI, Anthropic y otros)
- Selecciona el modelo específico en el medio, por ejemplo,
gpt-5.5 - La URL Base se rellena automáticamente una vez que se selecciona el proveedor, no es necesaria la entrada manual
- Haz clic en Run para iniciar una sesión
Paso 2: Configurar los `prompts`
La pestaña Prompts tiene dos áreas de entrada.
- System Prompt: define el rol, los objetivos, las restricciones y las reglas de uso de herramientas del agente.
- User Prompt: la entrada de prueba para esta sesión, por ejemplo, "¿Qué es Apidog?"
Haz clic en Run en la parte superior derecha cuando ambos estén configurados. Si quieres que el cuadro de entrada se borre automáticamente después de cada ejecución, marca Clear after Send.
Paso 3: Configurar las herramientas
La pestaña Tools lista todo lo que el agente puede llamar en tiempo de ejecución. El número en la pestaña es el recuento actual de herramientas disponibles o configuradas.
Las Built-in tools se incluyen con el depurador. Actívalas o desactívalas según sea necesario.
| Herramienta | Lo que 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 |
Las herramientas MCP añaden sistemas externos o capacidades personalizadas a través de Servidores MCP. Tres métodos de conexión:
- STDIO: inicia un proceso de Servidor MCP local
- HTTP: se conecta a un Servidor MCP que soporta HTTP Streamable
- SSE: se conecta a un Servidor MCP basado en Eventos Enviados por el Servidor
Los Servidores MCP que requieren autenticación aceptan encabezados de solicitud o flujos OAuth 2.0. Una vez que la conexión se realiza con éxito, selecciona qué herramientas expone el servidor al agente.
Paso 4: Configurar habilidades, autenticación y parámetros del modelo
Tres pestañas más pequeñas completan la configuración.
- Skills: flujos de trabajo reutilizables para el agente. Útil para flujos de trabajo de proyectos fijos, especificaciones de operaciones de tareas comunes y reducción de texto largo repetitivo en los `system prompts`. Las habilidades se cargan según sea necesario en tiempo de ejecución.
- Authentication: credenciales requeridas por los servicios del modelo o los servicios MCP.
- Settings: parámetros de tiempo de ejecución del modelo como Temperatura, Máx. Tokens y Top P. Los parámetros soportados varían según el proveedor, así que verifica lo que tu modelo realmente acepta.
Paso 5: Leer los tres paneles
Después de hacer clic en "Ejecutar", la sesión que acabas de crear aparece en el panel izquierdo. Cada sesión muestra un resumen de una línea:
Sesión 3
1 turno · 1 paso · 10s · 3.1k tokens · $0.02
gpt-5.5
- Panel de sesiones (izquierda): historial de cada ejecución con métricas resumidas
- Panel de turnos (medio): cada ronda de diálogo usuario/modelo. Haz clic en una ronda para cargar su detalle de ejecución a la derecha.
- Panel de trazas (derecha): la cadena de ejecución completa del agente en orden, incluyendo los `system` y `user prompts`, cada llamada al modelo, el proceso de pensamiento del modelo si el modelo lo expone, las llamadas a herramientas MCP y las ejecuciones de Habilidades personalizadas, los parámetros de entrada de las herramientas, los resultados, el tiempo consumido, los mensajes de error y la salida final.
Cuando una llamada a una herramienta falla o el modelo devuelve una excepción, el paso fallido se encuentra directamente en el panel de Trazas con sus entradas y salidas visibles. Sin inmersiones en los registros.
Paso 6: Comparar el rendimiento del modelo
Mismo `prompt`, misma configuración de herramientas, diferente modelo. Cada ejecución crea una nueva sesión, y el panel izquierdo te permite compararlas una al lado de la otra.
Métricas útiles para comparar:
- Número de pasos de ejecución para la misma tarea
- Qué modelo elige las herramientas con mayor precisión
- Qué modelo tiene un tiempo de respuesta más bajo
- Qué modelo mantiene el consumo de tokens y el costo más predecibles
La conclusión
Dos días de depuración se redujeron a una tarde, y no aprendí la lección sobre el error. La aprendí sobre las herramientas. La razón por la que había estado persiguiendo la solución incorrecta era que las herramientas que estaba usando no me mostraban lo que necesitaba ver. Tenía una salida del modelo y una salida de la herramienta, y ningún marco compartido para verlas juntas. El marco compartido es el punto clave.
Si has escrito más de un agente y aún no has abierto el Depurador de Agentes de IA de Apidog, el próximo agente que publiques tendrá un error que residirá entre el modelo y la herramienta. Pasarás una semana en ello. Escribirás una página de Notion de hipótesis fallidas. El error estará exactamente donde el depurador te lo habría mostrado el primer día.
Descarga Apidog y ábrelo en el próximo agente que te dé una respuesta incorrecta con una voz segura. Doce minutos. Cuarenta y siete milisegundos, no cuarenta y siete segundos.
La referencia completa de las funciones, incluida la configuración de transporte MCP y la disponibilidad del plan, se encuentra en Depurador de Agentes de IA de Apidog: disponibilidad, cobertura y configuración.