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 importantes enterrados varios niveles dentro del payload. No puedes saber si el fallo está en el transporte, en la autenticación, en el formato del mensaje o en la lógica del agente. Esa es la brecha que cubre un depurador Agent2Agent A2A.
Este artículo explica qué es un depurador A2A, por qué depurar tráfico agente-a-agente es difícil sin uno, qué debe hacer una buena herramienta y cómo usarla en un ciclo de depuración práctico. Si primero necesitas contexto del protocolo, empieza con qué es Agent2Agent A2A.
¿Qué es un depurador A2A?
Un depurador A2A es una herramienta que te permite conectarte a un agente Agent2Agent, enviar mensajes de prueba e inspeccionar la solicitud y la respuesta completas sin escribir código de cliente.
Funciona de forma parecida a un cliente REST para APIs:
- Pegas la URL de la Tarjeta de Agente.
- El depurador descubre las capacidades del agente.
- Envías un mensaje de prueba.
- Inspeccionas el payload A2A y la envoltura JSON-RPC.
- Identificas el campo, encabezado, artefacto o metadata que está fallando.
A2A es el protocolo abierto para la comunicación entre agentes de IA. Define la Tarjeta de Agente, el ciclo de vida de la tarea y el formato de mensajes y artefactos que intercambian los agentes. Un depurador A2A es el banco de pruebas para validar todo eso manualmente antes de integrarlo en un flujo de producción.
La pregunta que debe responder es concreta:
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 suele quedar oculto detrás de SDKs, abstracciones y payloads anidados.
Los logs de consola omiten datos críticos
Un SDK de agente registra lo que sus autores decidieron registrar. Puede que veas algo como:
Task completed
Pero no necesariamente verás:
taskId- partes del mensaje
- artefactos generados
- metadatos por mensaje
- errores JSON-RPC
- referencias a archivos
- estado real de la tarea
Si el campo defectuoso no se imprime en stdout, los logs no bastan.
La pestaña de red no entiende A2A
El panel de red del navegador muestra cuerpos HTTP, pero A2A usa estructuras JSON-RPC anidadas. Puedes terminar inspeccionando algo como esto:
{
"jsonrpc": "2.0",
"id": "req-1",
"result": {
"task": {
"id": "task-123",
"status": {
"state": "completed"
},
"artifacts": [
{
"parts": [
{
"kind": "text",
"text": "Resultado generado por el agente"
}
]
}
]
}
}
}
El dato importante puede estar varios niveles dentro de result.task.artifacts[].parts[].
Los scripts temporales se rompen rápido
La alternativa habitual es escribir un curl, un script en Python o un cliente desechable.
Ejemplo:
curl -X POST http://localhost:3000/a2a \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "test-1",
"method": "message/send",
"params": {
"message": {
"parts": [
{
"kind": "text",
"text": "Resume este documento"
}
]
}
}
}'
Funciona un día. Luego cambia la Tarjeta de Agente, cambia la autenticación o se añade metadata obligatoria, y el script queda desactualizado.
Los errores de transporte y lógica se ven iguales
Cuando un agente devuelve una respuesta incorrecta, la causa puede ser:
- una solicitud mal formada
- una conexión rota
- un fallo de autenticación
- un encabezado faltante
- metadata enviada en el lugar equivocado
- razonamiento incorrecto del modelo
- lógica defectuosa del agente
Sin ver la conexión completa, todo se resume en “el agente está roto”.
Un depurador A2A reduce esa ambigüedad: ves exactamente qué enviaste, qué recibió el agente y qué respondió.
Qué hace un depurador A2A
Un depurador A2A útil debe cubrir cuatro áreas: descubrimiento, pruebas de mensajes, inspección de respuestas y autenticación.
1. Conexión y descubrimiento
El primer paso es conectarte a la Tarjeta de Agente.
En desarrollo local, una URL típica puede ser:
http://localhost:3000/.well-known/agent.json
El depurador debe obtener esa tarjeta, validarla y mostrar información como:
- nombre del agente
- descripción
- versión del protocolo
- capacidades anunciadas
- habilidades declaradas
- tipos de entrada soportados
- endpoints disponibles
Si la tarjeta está mal formada, la herramienta debe fallar de forma explícita y señalar el campo problemático.
Ejemplo de diagnóstico útil:
Agent Card validation failed:
missing required field: capabilities
Eso es mucho mejor que un error genérico como:
Connection failed
2. Pruebas de mensajes
Una vez conectado, deberías poder enviar mensajes sin construir manualmente el JSON-RPC.
El flujo práctico debería ser:
- Escribir un prompt.
- Añadir archivos si el agente los soporta.
- Añadir metadata por mensaje si aplica.
- Configurar autenticación o encabezados.
- Enviar.
- Revisar la respuesta.
Ejemplo de mensaje mínimo:
Resume el contenido del archivo adjunto en tres puntos.
Ejemplo de metadata que podrías enviar junto al mensaje:
{
"tenantId": "acme",
"traceId": "debug-run-001",
"priority": "low"
}
El depurador debe encargarse de envolver esa entrada en la estructura A2A correcta y en JSON-RPC. Tú no deberías tener que escribir el cliente desde cero para cada prueba.
3. Inspección de respuestas
Este es el valor principal.
Las respuestas A2A pueden incluir:
- texto plano
- artefactos estructurados
- referencias a archivos
- partes múltiples
- errores JSON-RPC
- estados de tarea
- respuestas parciales en streaming
Un buen depurador debe mostrar el mismo resultado desde varios ángulos.
El depurador A2A de Apidog, por ejemplo, ofrece tres vistas:
- Vista previa: renderiza campos estructurados como un árbol legible.
- Contenido: muestra el cuerpo legible para humanos.
- Datos sin procesar: muestra el payload JSON-RPC completo.
Esto permite diagnosticar rápido casos como:
| Síntoma | Diagnóstico probable |
|---|---|
| La Vista previa tiene datos, pero Contenido está vacío | El agente devolvió un artefacto estructurado que no se puede aplanar como texto |
| Contenido muestra texto, pero faltan metadatos | El agente generó salida, pero no adjuntó contexto esperado |
| Datos sin procesar muestra error JSON-RPC | El fallo está antes de la lógica final del agente |
| La respuesta está bien formada, pero semánticamente incorrecta | El problema probablemente está en el prompt, herramientas o razonamiento del agente |
Sin esas vistas, el diagnóstico puede convertirse en una revisión manual larga de JSON anidado.
4. Autenticación y encabezados
Los agentes de producción rara vez están abiertos. Suelen estar detrás de:
- Bearer Token
- Autenticación Básica
- clave de API
- encabezados personalizados
- gateways internos
- proxies reversos
- identificadores de tenant
Un depurador A2A debe permitir configurar esos valores desde la interfaz.
Ejemplo de encabezados:
Authorization: Bearer <token>
X-Tenant-ID: acme
X-Request-ID: debug-001
También debe diferenciar claramente entre:
- Encabezados HTTP: llegan a gateways, proxies y middleware.
- Metadatos A2A: llegan al manejador de tareas del agente.
Este error es común:
X-User-Intent: summarize
Si el agente espera esa información dentro de metadata A2A y no en un encabezado HTTP, nunca la leerá.
El Depurador A2A de Apidog
Apidog incluye un Depurador A2A dentro de su cliente estándar.
El flujo básico es:
- Abre el Depurador A2A.
- Pega la URL de la Tarjeta de Agente.
- Haz clic en Conectar.
- Revisa los metadatos del agente.
- Abre la pestaña Mensajes.
- Escribe un prompt.
- Opcionalmente adjunta un archivo o añade metadata.
- Haz clic en Enviar.
- Revisa la respuesta en Vista previa, Contenido y Datos sin procesar.
Para desarrollo local, puedes probar con una URL como:
http://localhost:3000/.well-known/agent.json
Apidog maneja:
- envoltura JSON-RPC
- análisis de respuestas
- historial de sesión
- archivos adjuntos
- metadata
- encabezados personalizados
- streaming con eventos enviados por el servidor cuando el agente lo soporta
El historial de sesión permite repetir pruebas y comparar respuestas sin reconstruir cada mensaje.
También cubre una diferencia importante: encabezados HTTP frente a metadata A2A. Ver ambos canales lado a lado ayuda a detectar errores como enviar contexto de tarea en un encabezado que el agente nunca lee.
Para una guía paso a paso completa, consulta la guía del Depurador A2A de Apidog. Apidog también tiene un depurador de agentes de IA para el flujo más amplio de pruebas de agentes.
Qué buscar en un depurador A2A
Cuando compares herramientas, usa esta lista.
Validación clara de la Tarjeta de Agente
Debe decirte por qué falla una tarjeta, no solo que falló.
Bueno:
missing required field: skills[0].name
Malo:
invalid agent card
Múltiples vistas de respuesta
Necesitas al menos:
- una vista legible
- una vista estructurada
- el JSON sin procesar
Solo ver JSON bruto no es suficiente cuando trabajas con artefactos, partes y tareas.
Cobertura de autenticación
Debe soportar:
- Bearer Token
- Basic Auth
- API Key
- encabezados personalizados
Sin tener que codificar base64 manualmente ni modificar scripts.
Archivos y metadata
El tráfico A2A real no siempre es texto. Un depurador solo de texto deja fuera una parte importante de la superficie de prueba.
Busca soporte para:
- archivos adjuntos
- metadata por mensaje
- tipos de entrada declarados por el agente
- artefactos estructurados en la respuesta
Soporte de streaming
Si el agente usa eventos enviados por el servidor, el depurador debe mostrar fragmentos a medida que llegan y luego mostrar el payload ensamblado al cerrar la transmisión.
Historial de sesión
Durante la depuración enviarás variaciones del mismo mensaje muchas veces. El historial ayuda a:
- repetir pruebas
- comparar respuestas
- volver a una ejecución anterior
- aislar cuándo cambió el comportamiento
Tráfico local o directo
Para desarrollo y debugging, es importante que la herramienta pueda comunicarse directamente con tu agente, sin redirigir tus payloads por servidores de terceros.
Un depurador que cubre estos puntos convierte la depuración A2A en una rutina de verificación, no en una suposición. La misma disciplina que se aplica en cómo probar agentes de IA que llaman a tus APIs también aplica a la capa A2A. Si además 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, usa este ciclo.
1. Verifica la Tarjeta de Agente
Conéctate al agente y confirma que la tarjeta anuncia la habilidad esperada.
Comprueba:
- nombre correcto
- versión correcta
- endpoint correcto
- habilidad esperada
- tipos de entrada soportados
- capacidades necesarias
Si la habilidad no aparece en la tarjeta, no empieces por el prompt. Arregla primero el manifiesto.
2. Envía el mensaje mínimo
Empieza con texto plano.
Hola, responde con "ok".
Luego prueba la habilidad real:
Resume este texto en una frase: Agent2Agent permite comunicación entre agentes.
Añade archivos y metadata solo cuando el caso mínimo funcione.
3. Lee primero los datos sin procesar
Antes de mirar la vista bonita, revisa el JSON-RPC completo.
Busca:
idresulterrortaskstatusartifactsparts- campos de metadata
Si el campo esperado no existe en el payload bruto, el problema está en el agente o en la solicitud, no en el renderizador.
4. Separa transporte de lógica
Usa esta regla:
| Resultado | Conclusión |
|---|---|
| No conecta | problema de URL, red, TLS, gateway o autenticación |
| Conecta, pero falla JSON-RPC | problema de formato, método o payload |
| Responde bien formado, pero con datos faltantes | problema de implementación del agente |
| Responde bien formado, pero semánticamente mal | problema de prompt, herramientas, modelo o lógica |
| Funciona sin metadata, falla con metadata | problema en el canal de metadata o parsing del agente |
| Funciona sin archivo, falla con archivo | problema en adjuntos o tipo de entrada |
5. Repite con una sola variable por prueba
No cambies prompt, metadata, archivos y encabezados al mismo tiempo.
Orden recomendado:
- Texto mínimo.
- Texto real.
- Metadata.
- Archivo.
- Autenticación real.
- Streaming.
- Caso completo.
Así puedes identificar qué cambio introduce el fallo.
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 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. Un depurador A2A entiende la capa Agent2Agent: Tarjetas de Agente, ciclo de vida de tareas, partes de mensajes y artefactos. Analiza y renderiza esas estructuras en lugar de mostrar solo un cuerpo HTTP en bruto.
¿Necesito un depurador A2A si tengo logs?
Sí, si necesitas ver el tráfico real. Los logs muestran lo que el autor del agente decidió registrar. Un depurador muestra la solicitud y respuesta completas, lo que permite distinguir errores de transporte de errores de lógica. Para contexto del protocolo, consulta qué es Agent2Agent A2A.
¿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 puede usarse con agentes implementados en LangGraph, CrewAI, AutoGen o frameworks personalizados.
¿Maneja un depurador A2A respuestas de streaming?
Uno bueno sí. Cuando el agente soporta eventos enviados por el servidor, el depurador lee los fragmentos a medida que llegan, actualiza sus vistas en tiempo real y muestra el payload ensamblado cuando la transmisión termina.
Top comments (0)