Si construyes agentes de IA que se comunican con otros agentes de IA, ya te habrás topado con el mismo obstáculo que todos los demás: no hay una forma limpia de inspeccionar lo que un agente envía a otro. Los registros de la consola mienten, las pestañas de red ocultan los campos estructurados y los scripts de prueba a medida se vuelven obsoletos rápidamente. El depurador A2A de Apidog soluciona esto para el protocolo Agent2Agent (A2A). Pega la URL de una Tarjeta de Agente, haz clic en Conectar, envía un mensaje y lee la respuesta en tres vistas.
Esta guía explica qué hace el Depurador A2A, cómo configurar tu primer agente, cómo se ven la solicitud y la respuesta internamente, y cómo encaja junto a las herramientas existentes de Apidog para probar servidores MCP. Si necesitas primero el contexto del protocolo ascendente, Apidog ofrece una lectura más profunda sobre MCP vs A2A que combina bien con esta publicación.
Qué es A2A (en un párrafo)
A2A, abreviatura de Agent2Agent, es un protocolo abierto para la comunicación entre agentes. Define cómo un agente anuncia sus capacidades (la Tarjeta de Agente), cómo otro agente se conecta a él, cómo se intercambian mensajes y archivos adjuntos, y cómo se informa el estado de la tarea. Piénsalo como el HTTP para el tráfico de agente a agente: una especificación delgada e independiente del proveedor que permite a un agente LangGraph en tu tubería de datos hacer ping a un agente CrewAI propiedad de otro equipo sin que ninguna de las partes conozca los internos de la otra.
Es distinto del MCP (Model Context Protocol), que trata de dar a un solo agente acceso a herramientas y recursos. A2A trata de que los agentes hablen con otros agentes. El desglose de MCP vs A2A es la lectura más clara sobre la diferencia.
Qué te ofrece el Depurador A2A
El Depurador A2A se encuentra dentro de Apidog. Es un entorno de trabajo visual para probar puntos finales A2A antes de conectarlos a un flujo de trabajo de producción. Características clave:
- Conexión con la Tarjeta de Agente. Pega una URL, haz clic en Conectar, y verás el nombre del agente, la descripción, las capacidades, las habilidades declaradas y la versión del protocolo. Si la tarjeta está mal formada, la conexión fallará ruidosamente para que puedas corregir el manifiesto en lugar de perseguir fantasmas.
- Envío de mensajes. Redacta texto plano, adjunta archivos (cuando los tipos de entrada declarados por el agente los admitan) y añade pares clave-valor de metadatos personalizados.
- Tres vistas de respuesta. La vista Previa renderiza la salida estructurada, Contenido muestra la carga útil legible por humanos y Datos Brutos descarga el JSON completo para cuando necesites verificar nombres de campos o caracteres de escape.
- Autenticación. Token de portador, autenticación básica y clave API a través de encabezados personalizados, todo en la interfaz de usuario.
- Encabezados personalizados. Añade autenticación de puerta de enlace, parámetros de negocio o cualquier middleware que espere tu punto final A2A.
- Historial de sesión. Cada mensaje que envías permanece en un registro de sesión. Bórralo cuando inicies una nueva prueba.
No escribes ningún comando curl. Apidog maneja el sobre JSON-RPC, el streaming SSE (donde el agente lo soporte) y el análisis de la respuesta.
Paso 1: Conéctate a tu primer agente A2A
Necesitas tres cosas antes de abrir el depurador:
- Apidog instalado y actualizado. Se requiere la última versión del cliente; las versiones anteriores no incluyen el Depurador A2A. Descarga Apidog si aún no lo tienes.
- Una URL de Tarjeta de Agente. Este es el punto de entrada canónico para cualquier agente compatible con A2A. Para desarrollo local, generalmente se ve como
http://localhost:3000/.well-known/agent.json; para agentes alojados, tu proveedor de plataforma te dará la ruta. - Credenciales (si el agente las requiere). Token de portador, clave API o autenticación básica.
Abre Apidog, ve a la página del Depurador A2A y pega la URL de la Tarjeta de Agente en la parte superior. Haz clic en Conectar. Si el agente responde con una Tarjeta de Agente válida, el estado cambiará a Conectado y el panel se llenará con los metadatos del agente: nombre, descripción, capacidades, habilidades declaradas y versión del protocolo.
Si falla, las causas más comunes son:
- La URL es incorrecta o el agente no está funcionando. Abre la URL en un navegador para confirmar que se devuelve una carga útil JSON.
- La Tarjeta de Agente carece de campos obligatorios. Compárala con la especificación del protocolo A2A en GitHub.
- El agente espera autenticación en el punto final de descubrimiento. Añade la autenticación en Apidog antes de hacer clic en Conectar.
Paso 2: Envía un mensaje de prueba
Una vez conectado, abre la pestaña Mensajes. Escribe una solicitud como lo harías en cualquier interfaz de chat. Por ejemplo:
Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.
Adiciones opcionales antes de pulsar Enviar:
- Adjuntar archivo. Haz clic en el clip de papel y selecciona un archivo. El depurador verifica los tipos de entrada declarados por el agente y rechaza de antemano los tipos de archivo no compatibles, para que no desperdicies un viaje de ida y vuelta con un 415.
- Metadatos personalizados. Añade pares clave-valor como
priority: highotenant: acme-corp. Estos fluyen en el sobre de la solicitud A2A y son visibles para el agente si su manejador los lee.
Haz clic en Enviar. Apidog envuelve tu solicitud en la estructura de mensaje A2A, la envía al agente y espera la respuesta.
Paso 3: Lee la respuesta con tres vistas
Las respuestas A2A pueden ser cadenas de texto simples, JSON estructurado, referencias a archivos o una mezcla. El depurador te ofrece tres lentes sobre la misma carga útil:
- Vista previa. Apidog renderiza los campos estructurados como un árbol. Útil cuando el agente devuelve objetos anidados (ID de tarea, estado, artefactos, historial).
- Contenido. El cuerpo legible por humanos. Si el agente devolvió texto, esto es lo que le mostrarías a un usuario. Si devolvió un artefacto estructurado con una parte
text/plain, este es el texto extraído. - Datos Brutos. La carga útil JSON-RPC completa. Esto es lo que debes copiar en un informe de errores cuando algo no funciona, y lo que debes comparar con la especificación cuando verificas la conformidad.
Alterna entre las tres. Si la Vista previa parece correcta pero el Contenido está vacío, el agente probablemente está devolviendo un artefacto tipado que Apidog puede renderizar pero no sabe cómo aplanar. Si los Datos Brutos muestran un código de error, el agente rechazó la solicitud y el mensaje en error.message es tu punto de partida.
El historial de sesión se encuentra en el panel izquierdo. Cada envío se convierte en un turno al que puedes retroceder. Pulsa Borrar cuando inicies una nueva prueba y no quieras que el contexto antiguo confunda al agente.
Autenticación: tres patrones comunes
La mayoría de los puntos finales de producción A2A están detrás de algún tipo de autenticación. El depurador maneja tres patrones de inmediato:
Token de Portador
El patrón más común para agentes alojados. En el panel de autenticación, selecciona Token de Portador y pega el token. Apidog añade Authorization: Bearer <token> a cada solicitud.
Authorization: Bearer sk-agent-7f3e9a...
Autenticación Básica
Para agentes protegidos por un nombre de usuario y contraseña (común en sistemas internos/legados). Selecciona Autenticación Básica, introduce ambos valores, y Apidog calcula el encabezado Authorization: Basic ... codificado en base64.
Clave API vía encabezado personalizado
Cuando el agente espera un nombre de encabezado no estándar como X-Agent-Key, ve a la sección de Encabezados y añádelo manualmente. El mismo flujo para cualquier encabezado específico de la puerta de enlace (tokens CSRF, IDs de inquilinos, firmas de solicitudes).
Para una reflexión a largo plazo sobre la higiene de las credenciales de los agentes, la guía de credenciales de agentes de IA de Apidog cubre qué rotar, qué limitar y qué nunca comprometer.
Encabezados personalizados y metadatos: cuándo usar cada uno
Dos lugares contienen datos "extra" en una solicitud A2A. Suenan similares pero van a diferentes capas:
| Canal | Dónde vive | Úsalo para |
|---|---|---|
| Encabezados Personalizados | Encabezados de solicitud HTTP | Autenticación de puerta de enlace, observabilidad (X-Request-Id), indicadores de características |
| Metadatos | Carga útil del mensaje A2A | Contexto por mensaje que lee el agente (prioridad, inquilino, localidad) |
Regla general: si tu proxy inverso o API gateway necesita verlo, ponlo en los encabezados. Si el manejador de tareas del agente lo necesita, ponlo en los metadatos. Confundirlos es la principal causa de los errores de "¿por qué el agente ignoró mi pista?".
Depurador A2A vs. pruebas de servidor MCP en Apidog
Apidog ofrece tanto un Depurador A2A como un flujo de pruebas MCP. Son herramientas diferentes para protocolos diferentes:
| Herramienta | Protocolo | Pruebas | Úsalo cuando |
|---|---|---|---|
| Depurador A2A | Agent2Agent | Conectividad, intercambio de mensajes, estado de la tarea | Construyendo sistemas multi-agente donde los agentes llaman a otros agentes |
| Pruebas de servidor MCP | Model Context Protocol | Llamadas a herramientas, acceso a recursos, plantillas de indicaciones | Construyendo un servidor MCP que expone herramientas/recursos a un agente |
Si no estás seguro de cuál necesitas, la guía MCP vs A2A te ayuda a tomar la decisión. La versión corta: MCP es lo que un agente usa para acceder a sistemas externos. A2A es lo que un agente usa para hablar con otro agente.
Para el lado MCP del flujo de trabajo, el manual de pruebas de servidor MCP cubre rutas manuales y automatizadas en Apidog. Muchos equipos terminan usando ambas superficies porque los sistemas de agentes del mundo real combinan la coordinación A2A con el acceso a herramientas MCP.
Un patrón de depuración común: un viaje de ida y vuelta de una tarea
Cuando te encuentres atascado en "el agente no responde como espero", sigue este ciclo:
- Abre el Depurador A2A.
- Conéctate al agente. Confirma que la Tarjeta de Agente muestra la habilidad que esperas.
- Envía el mensaje más pequeño posible que debería activar esa habilidad. Usa texto plano primero; añade archivos y metadatos solo después de que la ruta de texto funcione.
- Lee los Datos Brutos, no la Vista previa, la primera vez. Quieres ver exactamente lo que emitió el agente.
- Si la respuesta carece de un campo que esperas, eso es un problema en el código del agente, no en el transporte.
- Si la respuesta está bien formada pero es incorrecta, eso es un problema de la instrucción o del modelo, y ya has aislado el transporte de la lógica.
Este es el mismo ciclo de aislamiento antes de culpar que el post Cómo probar agentes de IA que llaman a tus APIs aplica al lado de la API. Mismo principio: confirma el cableado primero, luego depura el cerebro.
Dónde encaja en tu flujo de trabajo de IA
Los sistemas multi-agente son cómo gran parte del trabajo serio de IA se envía en 2026. La publicación Los agentes de IA son los nuevos consumidores de API expone el argumento para tratar el tráfico de agentes como de primera clase. La continuación Diseño de APIs para agentes de IA cubre qué cambia en tu contrato de API cuando el consumidor es un agente impulsado por LLM en lugar de un desarrollador humano.
El Depurador A2A se sitúa en la misma capa que el depurador visual del Cliente MCP de Apidog. Ambos tienen como objetivo ofrecerte una ventana al tráfico que de otro modo estaría oculto dentro de los SDK de agentes. Conectas tu agente, puedes ver lo que hace, corriges los errores antes de que lleguen a producción.
Apidog se puede descargar gratis y el Depurador A2A viene con el cliente estándar; sin licencia separada, sin plan separado.
Preguntas frecuentes
¿El Depurador A2A es gratuito?
Sí. Viene incluido con el cliente estándar de Apidog. Descarga Apidog y el Depurador A2A aparecerá en el panel lateral una vez que tengas una versión lo suficientemente reciente.
¿Funciona con agentes escritos en cualquier framework?
Funciona con cualquier agente que 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 de Python o Go funcionan siempre que cumplan con la especificación A2A.
¿Puedo guardar sesiones para reproducirlas más tarde?
Las sesiones persisten mientras el depurador está abierto. Para almacenamiento a largo plazo, copia la salida de Datos Brutos y guárdala en tus artefactos de prueba; la exportación completa de sesiones está en la hoja de ruta.
¿Cómo maneja las respuestas en streaming?
Cuando el agente admite el streaming SSE (según la especificación A2A), el depurador lee los fragmentos a medida que llegan y actualiza la Vista previa y el Contenido en tiempo real. Los Datos Brutos muestran la respuesta ensamblada cuando se cierra la transmisión.
¿Cuál es la diferencia entre el campo de metadatos y la sección de encabezados?
Los encabezados son de la capa HTTP; los metadatos son de la capa de mensajes A2A. Los encabezados llegan a la puerta de enlace y al proxy inverso; los metadatos llegan al manejador de tareas del agente. Consulta la tabla anterior en esta publicación.
¿Apidog registra las respuestas del agente en sus servidores?
No. Apidog funciona como un cliente local. El tráfico entre tu máquina y el agente no pasa por la infraestructura de Apidog.
¿Puedo usar el Depurador A2A para probar contra un agente alojado en una red diferente?
Sí, siempre que la ruta de red esté abierta. El depurador realiza solicitudes HTTPS salientes como lo haría cualquier cliente HTTP. Si tu agente está detrás de una VPN, necesitarás que esa VPN esté activa.
¿Dónde reporto errores o solicito funciones?
El canal de comentarios de Apidog es la ruta principal; el repositorio de GitHub del protocolo A2A es donde evoluciona la especificación upstream, por lo que las solicitudes a nivel de especificación pertenecen allí.
Pruébalo ahora
Elige el agente A2A más simple al que tengas acceso. Si aún no tienes uno, las implementaciones de referencia A2A incluyen un servidor de ejemplo que puedes ejecutar localmente en menos de cinco minutos. Pega la URL de su Tarjeta de Agente en el Depurador A2A de Apidog, envía un mensaje de "hola" y observa cómo se llenan las tres vistas de respuesta. Ese es el bucle de extremo a extremo más pequeño, y a partir de ahí puedes escalar a indicaciones reales, archivos adjuntos y flujos de trabajo multi-agente.
Combina el depurador con Apidog para el resto de tu trabajo con API y MCP, y tendrás una única superficie para los tres protocolos sobre los que funcionan los sistemas de agentes: HTTP, MCP y A2A.