Herramienta de descubrimiento · A2A v1.0

Comprueba las URL de descubrimiento de A2A Agent Card

Los clientes A2A descubren un agente obteniendo su Agent Card en JSON desde una URL well-known. Prueba ambas convenciones de nomenclatura en un dominio real y observa exactamente lo que reciben los clientes.

Construye ambas URL de descubrimiento candidatas a partir del mismo dominio base.

Obtiene el JSON devuelto e informa del código de estado y el tipo de contenido.

Analiza la respuesta como JSON de Agent Card cuando es posible.

Ejecuta comprobaciones de preparación para interfaces, skills, proveedor, modos, capacidades y metadatos de seguridad.

Comprobar un dominio de agente público

Introduce un dominio base. El comprobador obtiene ambas rutas de descubrimiento, analiza el JSON devuelto y ejecuta comprobaciones de preparación del Agent Card.

Cómo funciona el descubrimiento

Una única URL well-known inicia cada integración A2A.

Antes de que otro agente pueda llamar al tuyo, obtiene el Agent Card desde una URI well-known (RFC 8615) en tu dominio, evalúa las skills y los requisitos de seguridad, y luego llama a la interfaz preferida. Si la Agent Card falta, está desactualizada u oculta tras una redirección, la integración termina antes de empezar.

Este sitio predica con el ejemplo: AgentCard.net publica su propia Agent Card en ambas rutas, y el ejemplo de la derecha es el documento real.

Ver nuestro Agent Card en vivo
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

Rutas de descubrimiento

Dos convenciones, una sola Agent Card.

Abrir el validador completo
Estándar A2A v1.0

/.well-known/agent-card.json

La URI well-known registrada por la especificación A2A v1.0. Los clientes nuevos obtienen primero esta ruta; sírvela con el tipo de contenido application/a2a+json.

Legado (anterior a v1.0)

/.well-known/agent.json

Usada por implementaciones A2A tempranas y ejemplos de codelabs. Muchos clientes desplegados aún comprueban solo esta ruta, así que servir la misma Agent Card aquí es una estrategia de transición segura.

Patrón de publicación

Haz que el descubrimiento de Agent Card sea resiliente.

Los fallos de descubrimiento rara vez son exóticos: una redirección, una página de error en caché, o una ruta desplegada y la otra olvidada. Esta rutina de publicación mantiene ambas convenciones sirviendo la misma Agent Card actualizada.

  1. 1

    Publica en la ruta estándar

    Sirve el Agent Card revisado en /.well-known/agent-card.json por HTTPS en el mismo dominio que el servicio A2A, con el tipo de contenido application/a2a+json.

  2. 2

    Refleja la ruta legada

    Devuelve el mismo documento en /.well-known/agent.json mientras los clientes antiguos sigan en circulación; Agent Cards divergentes en las dos rutas confunden el enrutamiento.

  3. 3

    Mantén la Agent Card sincronizada

    Cuando cambien los endpoints, skills, capacidades o autenticación, actualiza la Agent Card, incrementa su campo version y vuelve a desplegar ambas rutas juntas.

  4. 4

    Vuelve a comprobar tras cada cambio

    Ejecuta este comprobador tras despliegues, cambios de DNS, migraciones de gateway o ediciones en marketplaces. Los fallos suelen deberse a redirecciones, páginas de error HTML o una ruta olvidada.

Preguntas frecuentes

Preguntas frecuentes sobre Well-known Agent JSON

Qué publicar, dónde publicarlo y cómo mantener funcionando a los clientes de ambas convenciones.

¿Qué ruta de Agent Card well-known debería usar?

A2A v1.0 registra /.well-known/agent-card.json como la ruta de descubrimiento estándar. La ruta legada /.well-known/agent.json es anterior a v1.0 pero muchos clientes desplegados aún la comprueban, así que publicar la misma Agent Card en ambas rutas es la opción pragmática durante la transición.

¿Deben ambas rutas devolver el mismo JSON?

Sí. Devolver el mismo Agent Card público desde ambas rutas mantiene la coherencia para los clientes que solo soportan una convención. Documentos divergentes hacen que el agente parezca distinto según qué ruta obtenga el cliente.

¿Con qué tipo de contenido debería servirse el Agent Card?

La especificación registra application/a2a+json para los Agent Cards. El application/json simple es ampliamente aceptado en la práctica, pero un tipo de contenido HTML es una señal fiable de que la ruta está devolviendo una página de error en lugar de la Agent Card.

¿Puede el Agent Card público ocultar capacidades privadas?

Sí. Publica solo metadatos seguros para el descubrimiento en la Agent Card pública, establece capabilities.extendedAgentCard en true, y expón las skills sensibles mediante la operación autenticada GetExtendedAgentCard.

¿Por qué fallan las comprobaciones de descubrimiento tras un despliegue?

Las causas habituales son redirecciones a una página de inicio de sesión o marketing, páginas HTML 404 devueltas con estado 200, JSON obsoleto en caché de un CDN, o que solo se haya desplegado una de las dos rutas well-known. El comprobador informa del código de estado y el tipo de contenido de cada ruta, así que el fallo se hace visible de inmediato.

Antes de publicar

Valida la Agent Card y luego comprueba las URL.

Pasa primero el JSON por el validador completo, publícalo en ambas rutas well-known y confirma el descubrimiento con este comprobador.

Abrir el validadorGenerar una Agent Card