Construiste un agente A2A. Se conecta, funciona, y a veces devuelve algo incorrecto. ¿Y ahora qué? Abres la consola y ves un flujo de envolturas JSON-RPC con los campos que realmente te interesan enterrados a tres niveles de profundidad. No puedes saber si el error está en el transporte o en el agente. Esta es precisamente la brecha que un Depurador Agent2Agent (A2A) llena.
Este artículo explica qué es un depurador A2A, por qué depurar el tráfico agente-a-agente es difícil sin uno, qué hace un buen depurador y qué buscar al elegir uno. Si primero necesitas los antecedentes del protocolo, comienza con qué es Agent2Agent (A2A).
¿Qué es un depurador A2A?
Un depurador A2A es una herramienta que te permite conectarte a un agente Agent2Agent, enviarle mensajes de prueba e inspeccionar la solicitud y respuesta completas sin escribir código de cliente. Se sitúa entre tú y el agente de la misma manera que un cliente REST se sitúa entre tú y una API: controlas el agente manualmente, ves exactamente lo que cruza la conexión y encuentras el campo incorrecto rápidamente.
A2A es el protocolo abierto para la comunicación entre agentes de IA. Define la Tarjeta de Agente que un agente utiliza para anunciarse, el ciclo de vida de la tarea y el formato de mensaje y artefacto que intercambian los agentes. Un depurador A2A es el banco de trabajo para ejercitar todo eso manualmente antes de confiarlo en un flujo de trabajo de producción.
El trabajo es específico y útil. El depurador no construye tu agente ni ejecuta tu flujo de trabajo. Responde una pregunta de manera fiable: dada esta Tarjeta de Agente, ¿qué hace realmente el agente cuando le envío este mensaje?
Por qué depurar A2A es difícil sin uno
El tráfico agente-a-agente se esconde en lugares a los que las herramientas de depuración normales no llegan.
Los registros de consola mienten por omisión. Un SDK de agente registra lo que sus autores decidieron registrar. El ID de tarea estructurado, las partes del artefacto, los metadatos que adjuntaste; a menudo, esos nunca llegan a la salida estándar. Ves "tarea completada" y nada sobre el payload.
La pestaña de red aplana la estructura. Un panel de red del navegador muestra el cuerpo HTTP en bruto, pero los payloads A2A son JSON-RPC anidados. Averiguar si el agente devolvió una parte `text` o una parte `file` significa desplazarse por una pared de JSON escapado.
Los scripts de prueba personalizados se deterioran. El recurso habitual es un comando curl o un cliente Python desechable. Funciona por un día. Luego, la Tarjeta de Agente cambia, el esquema de autenticación se mueve y el script falla silenciosamente. Nadie lo actualiza.
Los errores de transporte y los errores de lógica son idénticos. Cuando un agente devuelve la respuesta incorrecta, la causa es una solicitud mal formada, una conexión rota, un fallo de autenticación o un razonamiento del agente genuinamente incorrecto. Sin ver la conexión, los cuatro parecen lo mismo: "el agente está roto".
Un depurador A2A elimina esa ambigüedad. Ves la solicitud que enviaste, la respuesta que recibiste y el campo exacto que está mal. Eso por sí solo te dice qué lado arreglar.
Qué hace un depurador A2A
Un depurador A2A capaz cubre cuatro áreas.
Conexión y descubrimiento
Pegas la URL de la Tarjeta de Agente y el depurador la obtiene, la valida y muestra lo que el agente anuncia: nombre, descripción, capacidades, habilidades declaradas, tipos de entrada soportados y versión del protocolo. Si la tarjeta está mal formada, un buen depurador falla ruidosamente y señala el campo faltante, para que arregles el manifiesto en lugar de perseguir un fantasma.
Pruebas de mensajes
Redactas un mensaje como lo harías en cualquier cuadro de chat; texto sin formato, archivos adjuntos, pares clave-valor de metadatos personalizados; y lo envías. El depurador envuelve tu entrada en la estructura de mensaje A2A correcta y la envoltura JSON-RPC. No escribes código de cliente ni creas payloads manualmente.
Inspección de respuestas
Este es el valor principal. Las respuestas A2A pueden ser cadenas simples, artefactos estructurados, referencias de archivos o una mezcla. Un buen depurador muestra el mismo payload a través de más de un lente. El depurador A2A de Apidog, por ejemplo, ofrece tres vistas:
- Vista previa renderiza los campos estructurados como un árbol legible.
- Contenido muestra el cuerpo legible para humanos de la manera en que un usuario lo vería.
- Datos sin procesar descarga el payload JSON-RPC completo para la verificación a nivel de campo.
Cuando la Vista previa se ve bien pero el Contenido está vacío, sabes instantáneamente que el agente devolvió un artefacto tipificado que el renderizador no puede aplanar. Ese diagnóstico toma segundos con tres vistas y una tarde sin ellas.
Autenticación y encabezados
Los agentes de producción se encuentran detrás de una autenticación. Un depurador que valga la pena usar maneja los patrones comunes en la interfaz de usuario: Token Bearer, Autenticación Básica y clave de API a través de un encabezado personalizado. También te permite añadir encabezados arbitrarios para pasarelas, ID de inquilino o firmas de solicitud. Sin codificación base64 manual, sin errores tipográficos en los encabezados.
El Depurador A2A de Apidog
Apidog incluye un Depurador A2A dentro de su cliente estándar, para que puedas ver un ejemplo concreto de la categoría.
El flujo es corto. Abre la página del Depurador A2A, pega una URL de Tarjeta de Agente (para desarrollo local, a menudo http://localhost:3000/.well-known/agent.json) y haz clic en Conectar. El estado cambia a Conectado y el panel se llena con los metadatos del agente. Abre la pestaña Mensajes, escribe un prompt, opcionalmente adjunta un archivo o añade metadatos, y haz clic en Enviar. La respuesta aparece en las tres vistas anteriores.
Apidog maneja la envoltura JSON-RPC, el streaming de eventos enviados por el servidor donde el agente lo soporta, y el análisis de respuestas. El historial de sesión guarda cada mensaje que envías para que puedas desplazarte hacia atrás a través de una ejecución de prueba. El depurador se ejecuta como un cliente local; el tráfico va directamente entre tu máquina y el agente, no a través de los servidores de Apidog.
También cubre una distinción útil en la que muchos equipos tropiezan: encabezados HTTP versus metadatos A2A. Los encabezados llegan a tu pasarela y proxy inverso. Los metadatos llegan al manejador de tareas del agente. Poner una pista por mensaje en un encabezado (donde el agente nunca lo lee) es el error número uno de "¿por qué el agente me ignoró?", y ver ambos canales uno al lado del otro lo hace obvio.
Para una guía paso a paso completa, la guía del Depurador A2A de Apidog cubre la conexión, el envío y la lectura de respuestas en detalle. Apidog también tiene un depurador de agentes de IA para el flujo de trabajo más amplio de pruebas de agentes.
Qué buscar en un depurador A2A
Cuando compares herramientas, busca esto:
- Validación de la Tarjeta de Agente. Debe decirte por qué una tarjeta falló, no solo que falló.
- Múltiples vistas de respuesta. Solo el JSON en bruto no es suficiente; quieres una vista legible y el payload en bruto juntos.
- Cobertura completa de autenticación. Bearer, Básica, clave de API y encabezados personalizados, todo sin scripting.
- Soporte de archivos y metadatos. El tráfico A2A real incluye archivos adjuntos y contexto por mensaje. Un depurador solo de texto pierde la mitad de la superficie.
- Soporte de streaming. Si el agente utiliza eventos enviados por el servidor, el depurador debe renderizar los fragmentos a medida que llegan.
- Historial de sesión. Enviarás el mismo mensaje muchas veces durante la depuración; la reproducción y el historial ahorran un esfuerzo real.
- Tráfico prioritario local. El depurador debe comunicarse directamente con tu agente, no redirigir tus payloads a través de un tercero.
Un depurador que maneja todo esto convierte la depuración A2A de una suposición a una rutina de confirmación de la conexión; la misma disciplina que la publicación cómo probar agentes de IA que llaman a tus APIs aplica a la capa API. Si también ejecutas servidores MCP, la guía servidor MCP vs A2A explica por qué a menudo necesitas un depurador para cada protocolo.
Un ciclo de depuración práctico
Cuando un agente A2A se comporta mal, ejecuta este ciclo en el depurador:
- Conéctate al agente y confirma que la Tarjeta de Agente muestra la habilidad que esperas.
- Envía el mensaje más pequeño que debería activar esa habilidad. Primero texto sin formato; añade archivos y metadatos solo una vez que el texto funcione.
- Lee primero los Datos sin procesar, no la Vista previa. Quieres exactamente lo que el agente emitió.
- Si falta un campo que esperas, el error está en el código del agente, no en el transporte.
- Si la respuesta está bien formada pero es incorrecta, el error está en el prompt o el modelo; ya has descartado el transporte.
Esa secuencia aísla el transporte de la lógica en cada ocasión, que es la razón principal por la que existe un depurador A2A.
Preguntas frecuentes
¿Qué es un depurador A2A en una frase?
Es una herramienta que se conecta a un agente Agent2Agent, le envía mensajes de prueba y muestra la solicitud y respuesta completas para que puedas depurar integraciones de agentes sin escribir código de cliente.
¿En qué se diferencia un depurador A2A de un cliente API?
Un cliente API prueba endpoints HTTP simples. Un depurador A2A entiende la capa A2A superior: Tarjetas de Agente, el ciclo de vida de la tarea, partes de mensajes y artefactos. Analiza y renderiza esas estructuras en lugar de dejarte un cuerpo en bruto.
¿Necesito un depurador A2A si tengo registros?
Los registros muestran lo que el autor del agente decidió registrar, lo que generalmente omite los campos de payload estructurados. Un depurador muestra el tráfico exacto de la conexión, para que puedas distinguir un error de transporte de un error de lógica del agente. Consulta qué es Agent2Agent (A2A) para el contexto del protocolo.
¿Es gratuito el Depurador A2A de Apidog?
Sí. Viene incluido con el cliente estándar de Apidog. Descarga Apidog y el Depurador A2A aparecerá en el panel lateral en una versión reciente.
¿Puede un depurador A2A probar agentes en cualquier framework?
Sí, siempre que el agente exponga una Tarjeta de Agente A2A válida. El protocolo es agnóstico al framework, por lo que LangGraph, CrewAI, AutoGen y los agentes personalizados funcionan.
¿Maneja un depurador A2A las respuestas de streaming?
Uno bueno sí. Cuando el agente soporta eventos enviados por el servidor, el depurador lee los fragmentos a medida que llegan y actualiza sus vistas en tiempo real, luego muestra el payload ensamblado una vez que la transmisión se cierra.