Discovery-tool · A2A v1.0

Controleer A2A Agent Card discovery-URL's

A2A-clients ontdekken een agent door de JSON Agent Card op te halen via een well-known URL. Test beide naamconventies op een live domein en zie precies wat clients daadwerkelijk ontvangen.

Bouwt beide kandidaat-discovery-URL's op vanuit hetzelfde basisdomein.

Haalt de geretourneerde JSON op en rapporteert statuscode en content type.

Parseert de respons waar mogelijk als Agent Card JSON.

Voert gereedheidscontroles uit voor interfaces, skills, provider, modi, capabilities en beveiligingsmetadata.

Controleer een publiek agentdomein

Voer een basisdomein in. De controle haalt beide discovery-paden op, parseert de geretourneerde JSON, en voert Agent Card-gereedheidscontroles uit.

Hoe discovery werkt

Eén well-known URL start elke A2A-integratie.

Voordat een andere agent de jouwe kan aanroepen, haalt deze de Agent Card op van een well-known URI (RFC 8615) op jouw domein, evalueert de skills en beveiligingseisen, en roept vervolgens de voorkeursinterface aan. Als de Agent Card ontbreekt, verouderd is, of verborgen zit achter een redirect, mislukt de integratie voordat ze begint.

Deze site praktiseert wat ze controleert: AgentCard.net publiceert zijn eigen Agent Card op beide paden, en het voorbeeld rechts is het echte document.

Bekijk onze live Agent Card
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", ... }
  ]
}

Discovery-paden

Twee conventies, één Agent Card.

Open de volledige validator
A2A v1.0-standaard

/.well-known/agent-card.json

De well-known URI geregistreerd door de A2A v1.0-specificatie. Nieuwe clients halen dit pad eerst op; serveer het met content type application/a2a+json.

Verouderd (vóór v1.0)

/.well-known/agent.json

Gebruikt door vroege A2A-implementaties en codelab-voorbeelden. Veel geïmplementeerde clients controleren nog steeds alleen dit pad, dus dezelfde Agent Card hier serveren is een veilige overgangsstrategie.

Publicatiepatroon

Maak Agent Card discovery veerkrachtig.

Discovery-fouten zijn zelden exotisch: een redirect, een gecachete foutpagina, of één pad geïmplementeerd terwijl het andere vergeten is. Deze publicatieroutine zorgt dat beide conventies altijd dezelfde actuele Agent Card serveren.

  1. 1

    Publiceer op het standaardpad

    Serveer de gecontroleerde Agent Card op /.well-known/agent-card.json via HTTPS op hetzelfde domein als de A2A-service, met content type application/a2a+json.

  2. 2

    Spiegel het verouderde pad

    Retourneer hetzelfde document vanaf /.well-known/agent.json zolang oudere clients nog in omloop zijn — afwijkende Agent Card op de twee paden verwarren de routering.

  3. 3

    Houd de Agent Card gesynchroniseerd

    Werk de Agent Card bij, verhoog het version-veld en implementeer beide paden samen opnieuw wanneer endpoints, skills, capabilities of authenticatie veranderen.

  4. 4

    Controleer opnieuw na elke wijziging

    Voer deze controle uit na implementaties, DNS-wijzigingen, gateway-migraties of marketplace-bewerkingen. Fouten zijn meestal terug te voeren op redirects, HTML-foutpagina's, of een vergeten pad.

Veelgestelde vragen

Veelgestelde vragen over Well-known Agent JSON

Wat te publiceren, waar te publiceren, en hoe clients van beide conventies aan het werk te houden.

Welk well-known Agent Card-pad moet ik gebruiken?

A2A v1.0 registreert /.well-known/agent-card.json als het standaard discovery-pad. Het verouderde /.well-known/agent.json dateert van vóór v1.0 maar wordt nog steeds door veel geïmplementeerde clients gecontroleerd, dus dezelfde Agent Card op beide paden publiceren is de pragmatische keuze tijdens de overgang.

Moeten beide paden identieke JSON retourneren?

Ja. Dezelfde publieke Agent Card vanaf beide paden retourneren houdt clients die slechts één conventie ondersteunen consistent. Afwijkende documenten laten de agent er anders uitzien afhankelijk van welk pad een client ophaalt.

Met welk content type moet de Agent Card worden geserveerd?

De specificatie registreert application/a2a+json voor Agent Cards. Gewoon application/json wordt in de praktijk breed geaccepteerd, maar een HTML content type is een betrouwbaar teken dat het pad een foutpagina retourneert in plaats van de Agent Card.

Kan de publieke Agent Card private capabilities verbergen?

Ja. Publiceer in de publieke Agent Card alleen metadata die veilig is voor discovery, zet capabilities.extendedAgentCard op true, en stel gevoelige skills bloot via de geauthenticeerde GetExtendedAgentCard-operatie.

Waarom mislukken discovery-controles na een implementatie?

Veelvoorkomende oorzaken zijn redirects naar een login- of marketingpagina, HTML 404-pagina's die met status 200 worden geretourneerd, verouderde JSON gecachet in een CDN, of slechts één van de twee well-known paden geïmplementeerd. De controle rapporteert statuscode en content type voor elk pad, zodat de fout direct zichtbaar wordt.

Voor je publiceert

Valideer de Agent Card, controleer dan de URL's.

Laat de JSON eerst door de volledige validator gaan, publiceer het op beide well-known paden, en bevestig de discovery met deze controle.

Open de validatorGenereer een Agent Card