Narzędzie wykrywania · A2A v1.0

Sprawdź adresy URL wykrywania A2A Agent Card

Klienci A2A odkrywają agenta, pobierając jego Agent Card w formacie JSON z adresu well-known URL. Przetestuj obie konwencje nazewnictwa na rzeczywistej domenie i zobacz dokładnie, co otrzymują klienci.

Buduje obie kandydujące adresy URL wykrywania z tej samej domeny bazowej.

Pobiera zwrócony JSON i raportuje kod statusu oraz typ treści.

Parsuje odpowiedź jako JSON Agent Card, gdy to możliwe.

Uruchamia kontrole gotowości dla interfejsów, umiejętności, dostawcy, trybów, możliwości i metadanych bezpieczeństwa.

Sprawdź publiczną domenę agenta

Wprowadź domenę bazową. Weryfikator pobiera obie ścieżki wykrywania, parsuje zwrócony JSON i uruchamia kontrole gotowości Agent Card.

Jak działa wykrywanie

Jeden adres well-known URL uruchamia każdą integrację A2A.

Zanim inny agent będzie mógł wywołać Twoją usługę, pobiera Agent Card z adresu well-known URI (RFC 8615) na Twojej domenie, ocenia umiejętności i wymagania bezpieczeństwa, a następnie wywołuje preferowany interfejs. Jeśli Agent Card jest brakująca, nieaktualna lub ukryta za przekierowaniem, integracja kończy się niepowodzeniem, zanim się zacznie.

Ta strona stosuje to, co sprawdza: AgentCard.net publikuje własną Agent Card pod obiema ścieżkami, a przykład po prawej to rzeczywisty dokument.

Zobacz naszą aktualną 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", ... }
  ]
}

Ścieżki wykrywania

Dwie konwencje, jedna Agent Card.

Otwórz pełny walidator
Standard A2A v1.0

/.well-known/agent-card.json

Adres well-known URI zarejestrowany przez specyfikację A2A v1.0. Nowi klienci pobierają najpierw tę ścieżkę; serwuj ją z typem treści application/a2a+json.

Starsza (sprzed v1.0)

/.well-known/agent.json

Używana przez wczesne implementacje A2A i przykłady codelab. Wielu wdrożonych klientów nadal sprawdza tylko tę ścieżkę, więc serwowanie tu tej samej Agent Card jest bezpieczną strategią przejściową.

Wzorzec publikacji

Uczyń wykrywanie Agent Card odpornym.

Błędy wykrywania rzadko są nietypowe: przekierowanie, zbuforowana strona błędu, albo jedna ścieżka wdrożona, a druga zapomniana. Ta rutyna publikacji sprawia, że obie konwencje zawsze serwują tę samą, aktualną Agent Card.

  1. 1

    Publikuj na standardowej ścieżce

    Serwuj zweryfikowaną Agent Card pod adresem /.well-known/agent-card.json przez HTTPS na tej samej domenie co usługa A2A, z typem treści application/a2a+json.

  2. 2

    Odzwierciedlaj starszą ścieżkę

    Zwracaj identyczny dokument z /.well-known/agent.json, dopóki starsi klienci wciąż są w użyciu — rozbieżne Agent Card na dwóch ścieżkach mylą routing.

  3. 3

    Utrzymuj Agent Card zsynchronizowaną

    Za każdym razem, gdy zmieniają się punkty końcowe, umiejętności, możliwości lub uwierzytelnianie, aktualizuj Agent Card, zwiększaj pole version i wdrażaj ponownie obie ścieżki razem.

  4. 4

    Sprawdzaj ponownie po każdej zmianie

    Uruchamiaj ten weryfikator po wdrożeniach, zmianach DNS, migracjach bramy lub edycjach na marketplace. Błędy zwykle wynikają z przekierowań, stron błędów HTML lub zapomnianej ścieżki.

FAQ

Najczęstsze pytania o Well-known Agent JSON

Co publikować, gdzie to publikować i jak utrzymać działanie klientów obu konwencji.

Której ścieżki well-known Agent Card powinienem użyć?

A2A v1.0 rejestruje /.well-known/agent-card.json jako standardową ścieżkę wykrywania. Starsza ścieżka /.well-known/agent.json poprzedza v1.0, ale wciąż jest sprawdzana przez wielu wdrożonych klientów, więc publikowanie tej samej Agent Card na obu ścieżkach jest pragmatycznym wyborem podczas przejścia.

Czy obie ścieżki powinny zwracać identyczny JSON?

Tak. Zwracanie tej samej publicznej Agent Card z obu ścieżek utrzymuje spójność dla klientów obsługujących tylko jedną konwencję. Rozbieżne dokumenty sprawiają, że agent wygląda inaczej w zależności od tego, którą ścieżkę pobierze klient.

Z jakim typem treści powinna być serwowana Agent Card?

Specyfikacja rejestruje application/a2a+json dla Agent Cards. Zwykły application/json jest szeroko akceptowany w praktyce, ale typ treści HTML to wiarygodny sygnał, że ścieżka zwraca stronę błędu zamiast Agent Card.

Czy publiczna Agent Card może ukrywać prywatne możliwości?

Tak. Publikuj w publicznej Agent Card tylko metadane bezpieczne dla wykrywania, ustaw capabilities.extendedAgentCard na true i udostępniaj wrażliwe umiejętności przez uwierzytelnioną operację GetExtendedAgentCard.

Dlaczego kontrole wykrywania zawodzą po wdrożeniu?

Typowe przyczyny to przekierowania do strony logowania lub marketingowej, strony HTML 404 zwracane ze statusem 200, nieaktualny JSON zbuforowany w CDN, lub wdrożenie tylko jednej z dwóch ścieżek well-known. Weryfikator raportuje kod statusu i typ treści dla każdej ścieżki, więc błąd jest natychmiast widoczny.

Przed publikacją

Zweryfikuj Agent Card, a potem sprawdź adresy URL.

Najpierw przepuść JSON przez pełny walidator, opublikuj go na obu ścieżkach well-known i potwierdź wykrywanie tym weryfikatorem.

Otwórz walidatorWygeneruj Agent Card