Cómo Depurar Protocolo Agente a Agente (A2A) con el Depurador A2A de Apidog

Si construyes agentes de IA que se comunican con otros agentes, necesitas una forma fiable de inspeccionar el tráfico A2A. Los logs de consola suelen ocultar contexto, las pestañas de red no siempre muestran bien las cargas estructuradas y los scripts de prueba se rompen rápido. El Depurador A2A de Apidog te permite pegar la URL de una Tarjeta de Agente, conectarte, enviar mensajes y revisar la respuesta en tres vistas: previa, contenido y datos brutos.

Prueba Apidog hoy

Esta guía muestra cómo usar el Depurador A2A paso a paso: conectar tu primer agente, enviar mensajes de prueba, revisar solicitudes y respuestas, añadir autenticación y decidir cuándo usar encabezados o metadatos. También verás cómo encaja junto a las herramientas de Apidog para probar servidores MCP. Si necesitas contexto previo sobre los protocolos, revisa esta guía de Apidog sobre MCP vs A2A.

Qué es A2A

A2A, abreviatura de Agent2Agent, es un protocolo abierto para comunicación entre agentes. Define cómo un agente publica sus capacidades mediante una Tarjeta de Agente, cómo otro agente se conecta, cómo se intercambian mensajes y archivos adjuntos, y cómo se reporta el estado de una tarea.

Piensa en A2A como una capa de transporte para tráfico agente-a-agente. Por ejemplo, un agente LangGraph en una tubería de datos puede comunicarse con un agente CrewAI mantenido por otro equipo sin conocer sus detalles internos.

A2A es distinto de MCP, Model Context Protocol. MCP permite que un agente acceda a herramientas y recursos. A2A permite que un agente hable con otros agentes. Para ver la diferencia completa, consulta el desglose MCP vs A2A.

Qué puedes hacer con el Depurador A2A

El Depurador A2A está integrado en Apidog. Sirve para probar endpoints A2A antes de conectarlos a flujos de producción.

Funciones principales:

• Conectarte mediante Tarjeta de Agente. Pega la URL, haz clic en Conectar y revisa nombre, descripción, capacidades, habilidades declaradas y versión del protocolo.
• Validar errores de manifiesto. Si la Tarjeta de Agente está mal formada, la conexión falla de forma visible para que puedas corregir el manifiesto.
• Enviar mensajes. Escribe texto plano, adjunta archivos cuando el agente los soporte y añade metadatos personalizados.
• Inspeccionar respuestas en tres vistas. Usa Vista previa, Contenido y Datos Brutos según el nivel de detalle que necesites.
• Configurar autenticación. Usa token de portador, autenticación básica o clave API mediante encabezados personalizados.
• Añadir encabezados personalizados. Incluye autenticación de gateway, parámetros de negocio o datos esperados por middleware.
• Revisar historial de sesión. Cada mensaje queda en el registro de sesión hasta que lo borres.

No necesitas escribir comandos curl. Apidog maneja el sobre JSON-RPC, el streaming SSE cuando el agente lo soporta y el análisis de la respuesta.

Paso 1: Conéctate a tu primer agente A2A

Antes de abrir el depurador, prepara lo siguiente:

1. Apidog instalado y actualizado. El Depurador A2A requiere una versión reciente del cliente. Si no lo tienes, descarga Apidog.
2. Una URL de Tarjeta de Agente. En desarrollo local suele verse así:

   http://localhost:3000/.well-known/agent.json

Para agentes alojados, tu plataforma o proveedor debe darte la ruta.

1. Credenciales, si el agente las requiere. Puede ser token de portador, clave API o usuario y contraseña.

Luego:

1. Abre Apidog.
2. Ve al Depurador A2A.
3. Pega la URL de la Tarjeta de Agente.
4. Configura autenticación si aplica.
5. Haz clic en Conectar.

Si la tarjeta es válida, el estado cambia a Conectado y el panel muestra los metadatos del agente: nombre, descripción, capacidades, habilidades declaradas y versión del protocolo.

Si falla, revisa estas causas comunes:

• URL incorrecta o agente apagado. Abre la URL en el navegador y confirma que devuelve JSON.
• Tarjeta de Agente incompleta. Compárala con la especificación del protocolo A2A en GitHub.
• Autenticación requerida en el endpoint de descubrimiento. Añade las credenciales antes de hacer clic en Conectar.

Paso 2: Envía un mensaje de prueba

Cuando el agente esté conectado, abre la pestaña Mensajes y escribe una solicitud mínima. Por ejemplo:

Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.

Antes de pulsar Enviar, puedes añadir:

• Archivo adjunto. Haz clic en el clip de papel y selecciona un archivo. El depurador valida los tipos de entrada declarados por el agente y rechaza archivos incompatibles antes de enviar la solicitud.
• Metadatos personalizados. Añade pares clave-valor como:

  priority: high
  tenant: acme-corp

Estos metadatos viajan dentro del mensaje A2A y quedan disponibles para el agente si su manejador los lee.

Haz clic en Enviar. Apidog envuelve tu entrada en la estructura de mensaje A2A, la envía al agente y espera la respuesta.

Paso 3: Lee la respuesta en tres vistas

Una respuesta A2A puede incluir texto, JSON estructurado, referencias a archivos o una combinación. El depurador muestra la misma respuesta desde tres ángulos:

• Vista previa. Renderiza campos estructurados como árbol. Úsala para revisar IDs de tarea, estado, artefactos e historial.
• Contenido. Muestra el cuerpo legible por humanos. Si el agente devuelve texto, esta es la salida que normalmente mostrarías al usuario.
• Datos Brutos. Muestra la carga JSON-RPC completa. Úsala para depurar nombres de campos, códigos de error, caracteres escapados o compatibilidad con la especificación.

Flujo recomendado:

1. Envía una solicitud mínima.
2. Abre Datos Brutos primero.
3. Verifica que el agente devolvió una respuesta A2A bien formada.
4. Cambia a Vista previa para leer la estructura.
5. Usa Contenido para revisar la salida final.

Casos típicos:

• Si Vista previa se ve bien pero Contenido está vacío, el agente puede estar devolviendo un artefacto tipado que Apidog puede renderizar, pero no aplanar como texto.
• Si Datos Brutos muestra un error, empieza por error.message.
• Si la respuesta está bien formada pero el contenido es incorrecto, probablemente el problema está en la instrucción, el modelo o la lógica del agente, no en el transporte.

El historial de sesión aparece en el panel izquierdo. Cada envío queda registrado como un turno. Usa Borrar cuando empieces una prueba nueva y no quieras que el contexto anterior afecte al agente.

Autenticación: tres patrones comunes

Muchos endpoints A2A de producción están protegidos. El depurador cubre tres configuraciones frecuentes.

Token de Portador

Úsalo cuando el agente espera un encabezado Authorization con Bearer token.

En Apidog:

1. Abre el panel de autenticación.
2. Selecciona Token de Portador.
3. Pega el token.

Apidog añadirá este encabezado en cada solicitud:

Authorization: Bearer sk-agent-7f3e9a...

Autenticación Básica

Úsala para agentes internos o sistemas heredados protegidos por usuario y contraseña.

En Apidog:

1. Selecciona Autenticación Básica.
2. Introduce usuario y contraseña.
3. Apidog genera el encabezado Authorization: Basic ... codificado en base64.

Clave API vía encabezado personalizado

Úsala cuando el agente espera un encabezado no estándar, por ejemplo:

X-Agent-Key: your-api-key

En Apidog:

1. Ve a Encabezados.
2. Añade el nombre del encabezado.
3. Añade el valor esperado.

El mismo patrón aplica para encabezados de gateway, tokens CSRF, IDs de inquilino o firmas de solicitud.

Para una guía más amplia sobre higiene de credenciales, consulta la guía de credenciales de agentes de IA de Apidog.

Encabezados personalizados vs metadatos

En una solicitud A2A puedes enviar datos extra en dos lugares. No son equivalentes.

Canal	Dónde vive	Úsalo para
Encabezados personalizados	Encabezados HTTP	Autenticación de gateway, observabilidad como X-Request-Id, feature flags
Metadatos	Carga útil del mensaje A2A	Contexto por mensaje leído por el agente: prioridad, inquilino, localidad

Regla práctica:

• Si lo necesita un proxy inverso, API gateway o middleware HTTP, ponlo en encabezados.
• Si lo necesita el manejador de tareas del agente, ponlo en metadatos.

Confundir estas capas suele causar errores del tipo: “el agente ignoró mi pista”.

Depurador A2A vs pruebas de servidor MCP en Apidog

Apidog incluye tanto el Depurador A2A como flujos de prueba MCP, pero sirven para protocolos distintos.

Herramienta	Protocolo	Qué prueba	Úsalo cuando
Depurador A2A	Agent2Agent	Conectividad, intercambio de mensajes, estado de tarea	Construyes sistemas multi-agente donde agentes llaman a otros agentes
Pruebas de servidor MCP	Model Context Protocol	Llamadas a herramientas, acceso a recursos, plantillas de indicaciones	Construyes un servidor MCP que expone herramientas o recursos a un agente

Versión corta:

• MCP: un agente accede a sistemas externos.
• A2A: un agente habla con otro agente.

Si necesitas decidir cuál usar, revisa la guía MCP vs A2A. Para el lado MCP, el manual de pruebas de servidor MCP cubre rutas manuales y automatizadas en Apidog.

Muchos equipos usan ambas superficies porque los sistemas de agentes reales combinan coordinación A2A con acceso a herramientas MCP.

Patrón de depuración: una tarea de ida y vuelta

Cuando el agente no responde como esperas, usa este ciclo:

1. Abre el Depurador A2A.
2. Conéctate al agente.
3. Confirma que la Tarjeta de Agente declara la habilidad que quieres probar.
4. Envía el mensaje más pequeño posible que active esa habilidad.
5. Empieza con texto plano.
6. Añade archivos y metadatos solo después de validar la ruta básica.
7. Lee primero Datos Brutos.
8. Verifica si la respuesta está bien formada.
9. Si falta un campo esperado, revisa el código del agente.
10. Si la estructura es correcta pero la salida es mala, revisa la instrucción, el modelo o la lógica.

La idea es aislar el problema antes de culpar al modelo. Es el mismo principio usado al probar agentes de IA que llaman a tus APIs: valida primero el cableado, luego depura el comportamiento.

Dónde encaja en tu flujo de trabajo de IA

Los sistemas multi-agente están convirtiendo el tráfico de agentes en tráfico de API de primera clase. La publicación Los agentes de IA son los nuevos consumidores de API explica este cambio. La continuación sobre diseño de APIs para agentes de IA cubre cómo cambia tu contrato de API cuando el consumidor es un agente impulsado por LLM en vez de un desarrollador humano.

El Depurador A2A se sitúa en la misma capa que el depurador visual del Cliente MCP de Apidog. Ambos te dan visibilidad sobre tráfico que normalmente queda oculto dentro de SDKs de agentes.

El flujo es simple:

1. Conecta el agente.
2. Observa qué envía y qué recibe.
3. Corrige errores antes de producción.

Apidog se puede descargar gratis y el Depurador A2A viene con el cliente estándar, sin licencia separada ni 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 cuando tengas una versión 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 agentes personalizados en Python o Go funcionan siempre que cumplan 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 streaming SSE según la especificación A2A, el depurador lee los fragmentos a medida que llegan y actualiza Vista previa y Contenido en tiempo real. Datos Brutos muestra la respuesta ensamblada cuando se cierra la transmisión.

¿Cuál es la diferencia entre metadatos y encabezados?

Los encabezados pertenecen a la capa HTTP. Los metadatos pertenecen a la capa de mensajes A2A. Los encabezados llegan al gateway y al proxy inverso; los metadatos llegan al manejador de tareas del agente.

¿Apidog registra las respuestas del agente en sus servidores?

No. Apidog funciona como cliente local. El tráfico entre tu máquina y el agente no pasa por la infraestructura de Apidog.

¿Puedo usar el Depurador A2A contra un agente en otra red?

Sí, siempre que la ruta de red esté abierta. El depurador realiza solicitudes HTTPS salientes como cualquier cliente HTTP. Si tu agente está detrás de una VPN, necesitas tener esa VPN activa.

¿Dónde reporto errores o solicito funciones?

El canal de comentarios de Apidog es la ruta principal. Para cambios en la especificación, usa el repositorio de GitHub del protocolo A2A, donde evoluciona la especificación upstream.

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 pocos minutos.

Prueba este flujo mínimo:

1. Ejecuta el agente de ejemplo.
2. Copia la URL de su Tarjeta de Agente.
3. Pégala en el Depurador A2A de Apidog.
4. Envía un mensaje como hola.
5. Revisa Vista previa, Contenido y Datos Brutos.

Ese es el bucle A2A de extremo a extremo más pequeño. Desde ahí puedes avanzar a indicaciones reales, archivos adjuntos, metadatos y flujos multi-agente.

Combina el depurador con Apidog para el resto de tu trabajo con API y MCP, y tendrás una sola superficie para los tres protocolos sobre los que funcionan muchos sistemas de agentes: HTTP, MCP y A2A.