Internet ma wiele konwencji które działają przez to że wszyscy się ich trzymają bez formalnego wymuszenia. robots.txtzawsze jest pod /robots.txt. sitemap.xml zawsze pod /sitemap.xml. Każdy crawler wie gdzie szukać.
.well-known to rozszerzenie tej samej logiki — ale dla całej klasy zasobów które strona chce ujawnić systemom automatycznym. Nie jeden plik, ale przewidywalny katalog gdzie można szukać metadanych o dowolnej usłudze czy możliwości strony.
Skąd pochodzi .well-known
Standard jest stary jak na internet — RFC 8615 opublikowane przez IETF w 2019 roku. Autorem jest Mark Nottingham, pracownik Cloudflare i długoletni contributor IETF. Ironicznie — ta sama firma która teraz najbardziej agresywnie używa .well-known do budowania standardów agentowych.
RFC 8615 definiuje /.well-known/ jako zarezerwowany katalog URI na serwerach WWW przeznaczony do publikowania metadanych o serwisie. Każdy standard który chce korzystać z tego mechanizmu rejestruje własną nazwę podkalogu w IANA Well-Known URI Registry.
Przykłady które istniały przed erą agentów: /.well-known/security.txt — kontakt dla badaczy bezpieczeństwa, /.well-known/openid-configuration — konfiguracja OpenID Connect, /.well-known/acme-challenge/ — weryfikacja domeny przez Let’s Encrypt.
Wspólny mianownik: przewidywalne miejsce gdzie system automatyczny może znaleźć konkretną informację bez konieczności parsowania strony głównej.
Dlaczego .well-known stało się centrum ekosystemu agentowego
Gdy pojawiły się agenty AI które muszą odkrywać możliwości stron — .well-known było gotowym rozwiązaniem. Zamiast wymyślać nowy mechanizm discovery — każdy nowy standard agentowy po prostu rejestruje własny podkatalog.
Dziś pod .well-known znajdziesz cały ekosystem:
/.well-known/ucp — profil merchantu dla Universal Commerce Protocol. Agent który chce kupić przez UCP najpierw odpytuje ten endpoint i dostaje JSON z możliwościami sklepu: jakie metody płatności obsługuje, czy może przeprowadzić pełny checkout, jakie ma capabilities.
/.well-known/agent-skills/index.json — indeks Agent Skills proponowany przez Cloudflare. Lista plików SKILL.md które opisują co agent może zrobić na tej stronie — wyszukiwać, kupować, rezerwować, odpytywać API.
/.well-known/mcp.json — manifest MCP servera. Agent który szuka MCP serverów wie gdzie sprawdzić.
/.well-known/http-message-signatures-directory — Web Bot Auth, standard który pozwala botom podpisywać żądania HTTP i stronom weryfikować ich tożsamość. Część rozwiązania problemu tożsamości agenta.
/.well-known/openid-configuration — OAuth discovery. WebMCP i Cloudflare Access używają tego do autoryzacji agentów przez OAuth flow.
Jak działa w praktyce — przykład UCP
Wyobraź sobie że agent AI ma za zadanie kupić produkt. Wchodzi na domenę sklepu i zanim zrobi cokolwiek — wysyła GET na /.well-known/ucp:
{
"ucp.version": "2026-01-11",
"capabilities": ["checkout", "fulfillment", "discount"],
"payment.handlers": ["google_pay", "stripe", "paypal"],
"identity.linking": true
}W ciągu jednego zapytania agent wie: sklep obsługuje UCP, może przeprowadzić pełny checkout, akceptuje Google Pay i Stripe, obsługuje Identity Linking dla programów lojalnościowych. Żadnego parsowania HTML, żadnego zgadywania.
To jest siła .well-known — przewidywalność. Agent nie musi odkrywać możliwości strony przez eksplorację. Strona aktywnie deklaruje co potrafi w standardowym miejscu.
.well-known a llms.txt — różnica
Te dwa mechanizmy są często wymieniane razem i warto je rozdzielić.
llms.txt — plik tekstowy w katalogu głównym, nie w .well-known. Format Markdown. Przeznaczony dla modeli językowych które chcą zrozumieć zawartość serwisu — co tu jest, jak to jest zorganizowane, gdzie szukać konkretnych treści. To jest mapa dla czytelnika.
.well-known/ — katalog z plikami JSON i innymi formatami maszynowymi. Przeznaczony dla agentów które chcą wykonać konkretne działania — kupić, zarezerwować, wywołać API, zweryfikować tożsamość. To jest instrukcja dla wykonawcy.
Upraszczając: llms.txt mówi „to jest treść mojej strony”. .well-known mówi „oto co możesz ze mną zrobić i jak”.
.well-known a agent-readiness
.well-known jest sercem filara 3 — odkrywalności w modelu agent-readiness webflux.pl. Strona która wystawia właściwe endpointy pod .well-known aktywnie informuje agenty o swoich możliwościach zamiast czekać aż agent je odkryje przez eksplorację.
Jak opisuje artykuł Sygnały dla agentów — zmiana pierwszego pytania z „jak być widocznym” na „kogo wpuścić i na jakich warunkach” przekłada się bezpośrednio na .well-known. Tu strona deklaruje swoje możliwości i swoje warunki.
Co warto wdrożyć teraz
Nie każda strona potrzebuje wszystkich endpointów. Priorytety zależą od tego czym jest strona.
Dla każdej strony: /.well-known/security.txt — to jest standard który istnieje od lat i nadal ma znaczenie. Kontakt dla badaczy bezpieczeństwa.
Dla sklepu: /.well-known/ucp jeśli chcesz być widoczny dla agentów zakupowych w ekosystemie Google/UCP.
Dla serwisu z treściami: /.well-known/agent-skills/index.json z SKILL.md opisującym jak korzystać z treści — szczególnie jeśli masz API lub endpoint JSON jak webflux.pl.
Dla serwisu z autoryzacją: /.well-known/openid-configuration jeśli obsługujesz OAuth — agenty które chcą działać w imieniu zalogowanego użytkownika będą tego szukać.
Następny naturalny krok dla webflux.pl — /.well-known/agent-skills/index.json który wskazuje na SKILL.md opisujący słownik i MCP server. Agent który trafi na webflux.pl i sprawdzi .well-known dostanie kompletną instrukcję obsługi.
Pojęcia powiązane w słowniku: Agent Skills, UCP, MCP, WebMCP, llms.txt, Agent discovery, Tożsamość agenta, Filar 3 — odkrywalność
Powiązane artykuły na webflux.pl: Sygnały dla agentów — filar trzeci, Jak agent AI robi zakupy — mechanika UCP