Walidator A2A Agent Card

Walidator Agent Card sprawdza wklejony JSON, przesłane pliki Agent Card, i publiczne URL agentów pod kątem wymagań wykrywania A2A v1.0.

Użyj modułu sprawdzania Agent Card agenta

Wklej JSON, adres URL agenta publicznego lub przeciągnij plik JSON do edytora.

Zakres Walidatora Agent Card

Co sprawdza Walidator Agent Card, zanim klienci odkryją Twojego agenta.

Walidator Agent Card jest przeznaczony dla deweloperów publikujących agentów A2A, wewnętrznych zespołów platformowych przeglądających metadane agentów, oraz operatorów marketplace sprawdzających, czy przesłana Agent Card zawiera wystarczające informacje do niezawodnego wywołania.

Wklej lokalny dokument JSON podczas rozwoju, prześlij Agent Card ze swojego repozytorium, lub użyj walidacji URL na żywo względem wdrożonej domeny, aby zweryfikować publiczne ścieżki wykrywania.

Zgodność ze schematem (A2A v1.0)

Sprawdza wymagane pola względem specyfikacji v1.0: name, description, version, supportedInterfaces z protocolBinding i protocolVersion dla każdego interfejsu, capabilities, tryby treści, i co najmniej jedną umiejętność z wymaganymi tagami.

Problemy semantyczne i migracyjne

Wykrywa struktury sprzed v1.0 — url na najwyższym poziomie, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — i dokładnie mówi, gdzie każde pole zostało przeniesione w v1.0.

Skanowanie bezpieczeństwa i sekretów

Weryfikuje, że securitySchemes i wymagania bezpieczeństwa są zadeklarowane dla niepublicznych endpointów, oznacza adresy URL bez HTTPS, i skanuje wartości wyglądające jak osadzone klucze API, JWT, lub tokeny bearer.

Gotowość do wykrywania

Pobiera /.well-known/agent-card.json i starszy /.well-known/agent.json z rzeczywistej domeny i potwierdza, że oba zwracają parsowalny JSON Agent Card.

Gdzie pasuje walidacja

Waliduj na każdym etapie: edytor, potok CI, rzeczywista domena.

Agent Card, która przeszła recenzję w zeszłym miesiącu, może nadal dziś zepsuć wykrywanie — endpoint się zmienia, umiejętność się zmienia, ponowne wdrożenie gubi trasę well-known. Zespoły platformowe i recenzenci marketplace traktują walidację jako powtarzalną bramkę, a nie jednorazowe sprawdzenie.

Najprostsza ochrona CI potrzebuje jedynie curl: potwierdź, że ścieżka well-known odpowiada parsowalnym JSON-em, zanim ruch przełączy się na nowe wdrożenie.

# deploy pipeline: fail if the published card breaks

curl -fsS https://your-domain/.well-known/agent-card.json \
  | python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'

Przewodnik napraw

Częste poprawki Agent Card

Użyj raportu Walidatora Agent Card, aby najpierw zająć się wymaganymi polami, a następnie popraw szczegóły wykrywania, zaufania, i migracji.

Zastąp zastępcze adresy URL endpointów wdrożonym adresem URL usługi A2A HTTPS.

Przenieś url i preferredTransport na najwyższym poziomie do uporządkowanej tablicy supportedInterfaces — pierwszy wpis to preferowany interfejs.

Dodaj wymagane pole version na najwyższym poziomie opisujące samego agenta, i dodaj tagi do każdej umiejętności.

Zmień nazwę provider.name na provider.organization i rozszerz krótkie opisy, aby klienci wiedzieli, kiedy wywołać agenta.

Deklaruj metadane bezpieczeństwa zawsze, gdy endpoint agenta nie jest w pełni publiczny — i nigdy nie osadzaj samych poświadczeń.

Opublikuj tę samą ważną Agent Card pod adresem /.well-known/agent-card.json (i pod starszą ścieżką agent.json, dopóki klienci wciąż sprawdzają obie).

FAQ

Pytania o Walidator Agent Card

Dopilnuj podstaw, zanim Twój agent dotrze do klienta A2A.

Porównaj poprawne przykłady

Na którą wersję A2A celuje walidator?

Kontrole podążają za strukturą Agent Card A2A v1.0 — supportedInterfaces, wersje protokołu dla każdego interfejsu, wymagane tagi umiejętności, provider.organization. Agent Card sprzed v1.0 nie są od razu odrzucane: pola dziedziczone pojawiają się jako ostrzeżenia z dokładnym zamiennikiem v1.0.

Dlaczego sprawdza oba adresy URL well-known?

Specyfikacja v1.0 rejestruje /.well-known/agent-card.json, ale wcześniejsze implementacje A2A używały /.well-known/agent.json. Sprawdzenie obu wykrywa luki w wykrywaniu, zanim klienci zawiodą.

Czy ostrzeżenia można zignorować?

Ostrzeżenia nie blokują jak błędy JSON, ale zwykle wskazują metadane, które ułatwiają wykrywanie, zaufanie, i wywoływanie agenta — lub pola sprzed v1.0, których nowsi klienci przestaną odczytywać.

Kiedy powinna być uruchamiana walidacja?

Trzy momenty: podczas edycji Agent Card w trakcie rozwoju, jako bramka CI przed wdrożeniem, i po publikacji — wklej adres URL rzeczywistej usługi, aby potwierdzić, co klienci faktycznie otrzymują z obu ścieżek wykrywania.

Gotowe do walidacji

Zwaliduj swoją Agent Card, zanim klienci ją odkryją.

Wklej JSON, upuść plik Agent Card, lub sprawdź publiczny adres URL z ujednoliconego obszaru roboczego walidatora.

Otwórz Walidator Agent Card Wygeneruj Agent Card