Co to jest ai-catalog.json?
Autor: Redakcja Domeny.ForSale Opublikowano Zaktualizowano
W skrócie: /.well-known/ai-catalog.json to wcześniejsza ścieżka publikowania manifestu zasobów dla agentów AI, opisana jako poprzedniczka /.well-known/ard.json w specyfikacji Agentic Resource Discovery (ARD). Taki manifest przedstawia dostępne narzędzia, agentów lub instrukcje ich użycia w uporządkowanym formacie JSON. Przy nowym wdrożeniu należy stosować ścieżkę ard.json oraz odnośnik HTML rel="ard".
Artykuł opiera się na specyfikacji ARD v0.91 z 26 sierpnia 2026 r., oznaczonej jako Proposal, czyli propozycja. Stan dokumentacji sprawdzono 3 października 2026 r.
Do czego służy katalog zasobów dla agentów?
Asystent potrzebujący zewnętrznego narzędzia musi najpierw ustalić, co ono robi i gdzie znaleźć jego opis. Manifest pozwala wydawcy przedstawić te informacje we wspólnej strukturze. Poszczególne wpisy mogą wskazywać między innymi opis serwera MCP, kartę agenta A2A albo plik z instrukcjami wykonania zadania, nazywany skill.
W ARD publikowanie manifestu jest statyczną częścią odkrywania zasobów. Osobną rolę pełni rejestr: pobiera wpisy, indeksuje je i udostępnia wyszukiwanie. Dzięki temu klient może zapytać o konkretną potrzebę i otrzymać pasujące zasoby. Sam plik JSON nie wykonuje narzędzi; sposób ich uruchamiania określa właściwy protokół lub instrukcja. Te warstwy opisują rozdziały 3 i 5 specyfikacji .
Dlaczego obecnie używa się ard.json?
W rozdziale 5.1 specyfikacja wskazuje jednoznaczne zasady odnajdywania manifestów:
| Mechanizm | Aktualna nazwa | Wcześniejsza nazwa |
|---|---|---|
| Plik w domenie | /.well-known/ard.json | /.well-known/ai-catalog.json |
| Odnośnik w HTML | rel="ard" | rel="ai-catalog" |
| Obsługa przez klienta ARD | Obowiązkowa przy odkrywaniu wpisów domeny | Opcjonalna zgodność wsteczna |
Klient zgodny ze specyfikacją, który odkrywa zasoby domeny, musi pobrać /.well-known/ard.json i respektować odnośnik rel="ard". Może dodatkowo sprawdzać wcześniejszą ścieżkę oraz relację ai-catalog; jeśli to robi, traktuje je jako równoważne źródła wpisów.
Oznacza to, że serwis udostępniający wyłącznie ai-catalog.json może zostać pominięty przez poprawnie działającego klienta ARD. Specyfikacja zaleca przejście na ard.json. Utrzymywanie starego adresu obok nowego pozostaje możliwością dla starszych integracji, a nie wymogiem nowego wdrożenia.
Jak wygląda poprawny manifest?
Dokument zawiera tablicę entries, a w niej opisy poszczególnych zasobów. Poniższy przykład jest skróconą wersją
manifestu Domeny.ForSale
:
{
"entries": [
{
"identifier": "urn:air:domeny.forsale:skill:domain-catalog-search",
"displayName": "Wyszukiwarka katalogu Domeny.ForSale",
"type": "text/markdown; profile=\"urn:air:agent-skills\"",
"url": "https://domeny.forsale/.well-known/agent-skills/domain-catalog-search/SKILL.md",
"capabilities": ["searchDomainCatalog"],
"representativeQueries": [
"znajdź domenę na sprzedaż dla sklepu internetowego",
"pokaż artykuły o wyborze i zakupie domeny"
]
}
]
}
Wpis wskazuje
instrukcję wyszukiwania w katalogu
. Instrukcja opisuje użycie narzędzia WebMCP searchDomainCatalog, a gdy nie jest ono dostępne — przeszukanie indeksu JSON serwisu. Adres w url prowadzi więc do dokumentu opisującego sposób działania.
Zgodnie z rozdziałami 4.2 i 4.3 :
identifier,displayNameitypesą wymagane. Określają identyfikator, czytelną nazwę i typ zasobu.- Wpis musi zawierać dokładnie jedno z pól:
url, wskazujące dokument, albodata, zawierające go bezpośrednio. representativeQueriespowinno zawierać 2–5 przykładowych zapytań. Pomagają one indeksować zasób pod kątem potrzeb użytkownika. Brak pola lub inna liczba przykładów powoduje ostrzeżenie narzędzia zgodności, a nie błąd walidacji schematu.capabilitiesjest opcjonalną listą krótkich nazw funkcji, przydatną przy filtrowaniu.
Manifest może zawierać także dodatkowe pola najwyższego poziomu, takie jak host czy specVersion. ARD nie nadaje im znaczenia w swoim modelu manifestu. Dlatego widoczne w naszym pliku "specVersion": "1.0" nie oznacza, że aktualna specyfikacja ARD ma wersję 1.0. Strukturę formalnie określa
schemat wpisu i manifestu
.
Jak przejść z ai-catalog.json na ard.json?
Migrację istniejącego katalogu można przeprowadzić w czterech krokach:
- Sprawdź wpisy względem aktualnego schematu ARD, w tym identyfikatory, adresy zasobów i przykładowe zapytania.
- Udostępnij manifest pod
/.well-known/ard.jsonwe własnej domenie. - Dodaj w sekcji
<head>stron odnośnik do tego dokumentu. - Sprawdź pobieranie manifestu i wskazanych zasobów oraz przeprowadź walidację. Jeżeli zachowujesz starą ścieżkę dla istniejących klientów, utrzymuj spójność obu wersji.
Odnośnik może wyglądać tak:
<link rel="ard" href="/.well-known/ard.json" type="application/json">
Specyfikacja udostępnia narzędzie do testowania zgodności . Pozwala ono sprawdzić manifest oraz odnajdywanie go w domenie.
Co daje publikacja takiego pliku?
Manifest ułatwia oprogramowaniu obsługującemu ARD rozpoznanie możliwości serwisu. W naszym przykładzie opisuje sposób wyszukiwania domen i artykułów. Aby zasób pojawił się w wynikach konkretnego rejestru, rejestr musi odnaleźć źródło i je zaindeksować.
Sama publikacja pliku nie gwarantuje obsługi przez dowolnego asystenta ani wyższej pozycji strony w Google. Praktyczny efekt należy sprawdzać w integracji, która rzeczywiście korzysta z ARD: czy pobiera manifest, rozpoznaje wpis i potrafi skorzystać ze wskazanego zasobu.
Zobacz też: Co to jest ARD?
Przeczytaj także
