From the field #08 - AX: agent experience, którego twoja strona nie ma

Część 3: dwadzieścia zielonych prób, pięć lekcji i pack

Część 1 postawiła tezę, że twoja strona ma UX i nie ma AX. Część 2 to był build - custom Agent Cards i MCP discovery manifesty na sześciu portalach, w siedemdziesiąt minut.

Ta część to połowa, którą wszyscy pomijają. Manifest, który zwraca 200, mówi ci, że plik się shipnął. Nie mówi nic o tym, czy agent faktycznie potrafi go przeczytać, sparsować i na nim działać. Więc sprawdzam, za każdym razem tak samo, i nie nazywam tego gotowym, dopóki próby nie są zielone.

Dwadzieścia prób, zielone

Warstwę agentową da się zweryfikować z linii poleceń, co jest całym powodem, dla którego warto jej ufać. Nie ma tu wyczucia. Albo manifest jest i jest poprawny, albo nie.

# A2A Agent Card obecny i poprawny JSON?
curl -s https://portfolio.sdet.it/.well-known/agent.json | jq .

# MCP discovery manifest obecny i poprawny?
curl -s https://portfolio.sdet.it/.well-known/mcp.json | jq .

# sitemap faktycznie pod ścieżką, którą agent sprawdza?
curl -s https://portfolio.sdet.it/sitemap-index.xml | xmllint --format - | head

# czy endpoint MCP odpowiada realnymi opisami toolów?
curl -s 'https://portfolio.sdet.it/mcp?tool=list_articles&language=pl' | jq .

Pierwsze trzy linie to próby, które liczę: Agent Card, manifest MCP, sitemap, odpalone na sześciu portalach - osiemnaście. Czwarta to głębszy spot-check, czy endpoint MCP faktycznie odpowiada realnymi opisami toolów, odpalany tam, gdzie ma znaczenie. Potem dwie na prywatnej bazie wiedzy, gdzie bearer-gated endpoint musi poprawnie odmówić nieuwierzytelnionemu wywołaniu, a dodatkowy llms-full.txt musi tam być. Dwadzieścia liczonych prób. Wszystkie dwadzieścia zielone po deployu.

Zielone nie znaczy tu “build przeszedł”. Znaczy, że każdy portal zwraca poprawny Agent Card, każdy manifest MCP wskazuje na żywy endpoint, publiczne odpowiadają, a bramkowany poprawnie odmawia. To różnica między shipnięciem pliku a shipnięciem rzeczy, której agent potrafi użyć.

Jedna próba nauczyła mnie pisać lepsze próby. Wcześniejszy audyt flagował brakujący sitemap na całej linii i był w błędzie - sprawdzał /sitemap.xml, gdy framework emituje /sitemap-index.xml. Sitemapy były tam cały czas. Lekcja nie była o sitemapach. Była o tym, że próba sprawdzająca złą ścieżkę raportuje fałszywą lukę z totalną pewnością, a fałszywa luka wysyła cię naprawiać coś, co nigdy nie było zepsute. Próba to też kod. Dostaje tę samą uważność co rzecz, którą sprawdza.

I jeden deploy stawiał opór. Cross-repo prywatny GitHub Action nie rozwiązał się na jednym self-hosted runnerze, więc ten portal poszedł manualnym SSH, gdy reszta deployowała się czysto. Bo portale są niezależne, sprint się nie zaciął. Root cause to wciąż otwarty follow-up, i nazywam go, bo taka jest umowa z From the Field: ten, który się psuje, też idzie do raportu.

Pięć lekcji

Warstwa jest prosta. Zrobienie jej dobrze na flocie to miejsce, gdzie idą godziny. Te pięć kosztowało mnie czas.

1. Custom na portal bije generyczny template, za każdym razem. Skille w Agent Card muszą zgadzać się z realnym tool surface /mcp dokładnie. Agent portfolio i agent dokumentacji to różni agenci z różnymi skillami, a skopiowana karta, która twierdzi skille, których portal nie ma, produkuje agenta wywołującego w nicość. Dowód, że moje są custom, jest taki, że są widocznie różne - siedem skilli na portfolio, pięć na stronie dokumentacji, nazwane po tym, co każdy realnie robi.

2. Prywatne API wciąż należy do warstwy discovery - bramkowane, nie ukryte. Instynkt przy prywatnym endpoincie to zostawić go poza. Źle. Właściwą odpowiedzią jest Agent Card, który deklaruje, że asset istnieje, i deklaruje, że jest zamknięty: auth bearer, skille opisane niejasno, realny tool surface niewyliczony. Agent dowiaduje się, że asset jest realny, i dowiaduje się, że potrzebuje poświadczeń. Obecny i uczciwy co do bycia zamkniętym.

3. Dynamiczny endpoint, nie statyczny plik. Cokolwiek dwujęzycznego budowanego z jednego źródła w dwa deploye wyśle zły URL ze statycznego public/.well-known/agent.json. Czytaj Astro.site build-time, a manifest jest poprawny na każdym deployu bez duplikacji. To ten sam wzorzec, którego endpoint llms.txt już używał, co jest sygnałem, że to był właściwy ruch.

4. /.well-known/ to pierwsze miejsce, w które patrzy agent, więc tam połóż manifesty. To nie dekoracja. RFC 8615 czyni /.well-known/ umówioną lokalizacją dokładnie dla tego rodzaju metadanych discovery, a narzędzia sprawdzają ją najpierw, zanim spadną na cokolwiek innego. Serwuj swój Agent Card i manifest MCP ze ścieżki well-known albo licz się z przeoczeniem przez agentów, którzy patrzą w standardowe miejsce.

5. Spec rusza się pod tobą, więc buduj z aliasami. Te karty shipnąłem w maju. Zanim spakowałem metodę w czerwcu, A2A osiągnął v1.0, przeniósł oficjalną ścieżkę karty z /.well-known/agent.json na /.well-known/agent-card.json, zmienił auth z authentication.schemes na securitySchemes i dodał signed cards jako trust model. Jakieś pięć tygodni, jedna przemianowana ścieżka i przebudowany blok auth. Lekcja to nie “goń każdą zmianę” - to buduj tak, żeby zmiana nie mogła cię zepsuć. Serwuj nową ścieżkę i trzymaj starą jako alias. Moje portale wciąż serwują kształt z maja; pack poniżej jest pod kształt v1.0 z aliasem na miejscu. Na tak młodym standardzie backward-compat to nie grzeczność, to sposób, w jaki nie znikasz w tygodniu, w którym ścieżka się zmienia.

Dokąd idzie AX i czego nie będę udawał, że jest shipnięte

Tu jest uczciwa linia, bo bycie precyzyjnym co do zbudowane-kontra-roadmapa to cały brand.

Co jest shipnięte, to read-only discovery. Sześć portali mówi agentowi, czym są i na co potrafią odpowiedzieć, a publiczne pozwalają mu czytać. To jest realne, jest żywe, możesz to scurlować.

Co nie jest shipnięte, to action layer. Następny front AX to agent, który robi coś transakcyjnego przez twoją stronę - umawia call, składa zapytanie, kończy zadanie - nie tylko czyta. To wymaga auth, rate limitów, ścieżek zapisu i bramki człowieka we właściwym miejscu, a nic z tego nie chodzi w moich portalach dzisiaj. Nie zamierzam rysować tego, jakby chodziło. To jest dokąd to idzie i to realny problem projektowy, nie feature, który po cichu serwuję.

Weź pack

Nie musisz odbudowywać warstwy discovery z tego artykułu. Spakowałem dokładnie to, co jest w tym odcinku - endpoint A2A Agent Card, backward-compat alias agent.json, MCP discovery manifest, wzorzec build-time origin, żeby jedno źródło serwowało każdą domenę - w clone-and-run pack. MIT, pod current A2A v1.0 spec, nie pod kształt z maja, który wciąż chodzi na moich portalach. Wrzuć do swojej strony, zmień nazwy i skille, i masz tę samą warstwę agent-discovery.

github.com/darco81/agent-ready-pack

Jeśli chcesz też drugą połowę bycia czytelnym dla AI - nie agent discovery, ale bycie cytowanym przez ChatGPT, Perplexity i Google AI Overview - to osobny pack na MIT, llms.txt, JSON-LD, OG i polityka robots dla crawlerów AI: github.com/darco81/ai-seo-pack.

Żadnego pitchu doczepionego do żadnego. Budujesz to sam, na swoim stacku, beze mnie w pokoju. Jeśli zbudujesz i chcesz porównać notatki, albo trafisz na pytanie o action layer i chcesz je przemyśleć z kimś, kto już je rozrysował - DM otwarte.

Domknięcie serii

Trzy części, jeden pomysł.

Twoja strona ma UX i prawie na pewno nie ma AX. Agentic web standaryzuje się na MCP dla agent-do-narzędzia i A2A dla agent-do-agenta, a za rok strona będzie oceniana nie tylko przez to, jak doświadcza jej człowiek, ale przez to, czy agent potrafi odkryć, co robi, i się podłączyć. Lekarstwem jest warstwa agent-discovery: custom Agent Card i manifest MCP na portal, uczciwy co do capabilities, bramkowany tam, gdzie API jest prywatne, serwowany ze ścieżki well-known, którą agent sprawdza najpierw.

Wszystko, o czym twierdzę, że jest zbudowane, jest żywe na sześciu portalach i zwraca zieloną próbę. Liczba siedemdziesięciu minut to prawdziwy sprint floty, trzymany dokładnie tak, jak się wydarzył. Ścieżka ruszyła się pod mną między shipnięciem a pisaniem tego, i to też ci powiedziałem, bo tak młody standard nagradza uczciwość ponad polish. Strona, której agent może zaufać, to taka, której manifest mówi mu dokładnie, co potrafi, a czego nie, a ten sam standard stosuje się do osoby opisującej, jak ją zbudowano.

From the Field to jest to, co realnie buduję, co się psuje i czego się uczę. Realne projekty, realne liczby, realne bugi. Bez tutoriali.