Sposób, w jaki agenci AI czytają dokumentację, radykalnie różni się od tego, jak robią to ludzie. Jeśli optymalizujesz treści tylko pod kątem człowieka, tracisz rosnący segment odbiorców — i nawet o tym nie wiesz.
Najważniejsze wnioski w pigułce
Problem z tradycyjną analityką:
- Agenty AI pomijają całą analitykę po stronie klienta (scroll depth, time-on-page, kliknięcia)
- Standardowe metryki pokazują zero aktywności, choć agent faktycznie przeczytał dokumentację
- Pojedyncze zapytanie HTTP zastępuje całą „podróż użytkownika"
Ekonomia tokenów:
- Większość agentów ma limity kontekstu między 100K–200K tokenów
- Zbyt długie dokumenty są po cichu pomijane lub obcinane
- Przykład: dokumentacja Cisco (193 217 tokenów) pochłania niemal cały dostępny kontekst
Co agenty sprawdzają najpierw:
- robots.txt — źle skonfigurowany może całkowicie zablokować dostęp
- llms.txt — plik indeksujący dokumentację (jak sitemap, ale dla AI)
- skill.md — deklaracja możliwości API (co można zrobić, nie tylko jak)
- Struktura Markdown — dramatycznie niższy koszt tokenowy niż HTML
Sygnały rozpoznawcze w logach:
- Axios, curl, got, Colly w nagłówkach User-Agent
- Pojedyncze żądania GET zamiast sesji nawigacyjnych
- Brak interakcji JavaScript
- Próby HEAD przed GET (np. Cursor)
Czym jest Agentic Engine Optimization
Agentic Engine Optimization (AEO) to praktyka strukturyzowania i serwowania treści technicznych tak, by agenty AI mogły je faktycznie wykorzystać — nie tylko ludzie.
Analogia do SEO jest tutaj trafna. Przez lata uczyliśmy się optymalizować pod crawlery wyszukiwarek i wzorce kliknięć użytkowników. AEO to ta sama filozofia, ale dla innego konsumenta: autonomicznych agentów AI, które pobierają, parsują i wnioskują na podstawie treści.
Kluczowe wymiary AEO obejmują:
Wykrywalność — czy agenty mogą znaleźć dokumentację bez renderowania JavaScript?
Parsowalność — czy treść jest czytelna maszynowo bez interpretacji layoutu wizualnego?
Efektywność tokenowa — czy treść mieści się w typowych oknach kontekstu bez obcięcia?
Sygnalizacja możliwości — czy dokumentacja mówi agentom, co API robi, nie tylko jak je wywołać?
Kontrola dostępu — czy robots.txt faktycznie przepuszcza ruch od AI?
Gdy którykolwiek z tych elementów zawodzi, agenty albo pomijają treść całkowicie, albo generują subtelnie błędne wyniki. Problem w tym, że prawdopodobnie nigdy się o tym nie dowiesz — żadne zdarzenie analityczne nie zostanie zarejestrowane.
Jak agenty faktycznie czytają dokumentację
Warto precyzyjnie określić różnicę behawioralną, bo jest większa niż początkowo zakładałem.
Wzorzec ludzki: programista ląduje na stronie głównej dokumentacji, nawiguje do odpowiedniej sekcji, skanuje nagłówki, czyta kilka akapitów, może uruchamia przykład kodu w interaktywnej konsoli, klika dwa-trzy linki wewnętrzne i spędza w sesji 4–8 minut. Analityka rejestruje wszystko.
Wzorzec agenta: badanie Developer Experience with AI Coding Agents przeanalizowało ruch HTTP od dziewięciu głównych agentów kodujących — w tym Claude Code, Cursor, Cline, Aider, VS Code i Junie — pobierających dokumentację deweloperską. Wyniki były zaskakujące.
Agenty zazwyczaj kompresują wielostronicową nawigację do jednego lub dwóch żądań HTTP. Tam gdzie człowiek spędziłby minuty klikając przez hierarchię dokumentacji, agent wysyła pojedyncze żądanie GET, otrzymuje pełną stronę i przechodzi dalej. Cała koncepcja „podróży użytkownika" załamuje się do pojedynczego zdarzenia po stronie serwera.
Praktyczna konsekwencja: każde zdarzenie analityczne po stronie klienta — scroll depth, time-on-page, kliknięcia przycisków, ukończenie tutoriali, śledzenie linków, interakcje z formularzami — staje się niewidzialne. Agent po prostu je omija.
Problem tokenów — dokumentacja niewidzialna dla agentów
To prawdopodobnie najbardziej niedoceniany aspekt całego obrazu: ekonomia tokenów.
Agenty nie mają nieskończonego kontekstu. Większość ma praktyczne limity między 100K–200K tokenów, a zarządzanie kontekstem jest aktywnym ograniczeniem w każdym zadaniu. Badanie podkreśla konkretny przykład: dokumentacja Cisco Secure Firewall Management Center REST API Quick Start Guide (wersja 10.0) ma 193 217 tokenów — prawie 718 000 znaków. Ten pojedynczy dokument grozi pochłonięciem lub przekroczeniem całego użytecznego okna kontekstu większości agentów.
Gdy agent trafia na zbyt długi dokument, może się zdarzyć kilka rzeczy — żadna nie jest dobra:
- Może po cichu obciąć treść, tracąc krytyczne informacje
- Może całkowicie pominąć dokument na rzecz czegoś krótszego
- Może próbować dzielenia na fragmenty, co dodaje opóźnienie i powierzchnię błędów
- Może wrócić do wiedzy parametrycznej — czyli wymyślić coś
Uważam, że liczba tokenów jest teraz pierwszorzędną metryką dokumentacji. Jeśli nie śledzisz liczby tokenów dla stron dokumentacji, tracisz sygnał, którego agenty faktycznie używają do decyzji, czy w ogóle próbować czytać treść.
Praktyczne cele tokenowe:
- Strony quick start / getting started: < 15 000 tokenów
- Pojedyncze strony referencji API: < 25 000 tokenów
- Pełna referencja API: dziel według zasobów/endpointów, nie według produktu
- Przewodniki koncepcyjne: < 20 000 tokenów; linkuj do szczegółów zamiast je osadzać
Stos AEO — co faktycznie zbudować
AEO to nie pojedyncza rzecz — to warstwowy zestaw sygnałów i standardów.
Warstwa 1: Kontrola dostępu (robots.txt)
To pierwszy przystanek agenta. Przed pobraniem treści wiele agentów sprawdza robots.txt, by określić, do czego mają dostęp.
Źle skonfigurowany robots.txt blokujący znane crawlery AI po cichu odmówi agentom dostępu do dokumentacji. Żadnego ruchu, żadnych błędów, żadnej wskazówki, że coś poszło nie tak.
Warstwa 2: Wykrywanie przez llms.txt
Nawet jeśli agent może uzyskać dostęp do treści, wciąż musi znaleźć właściwą treść. Tu wkracza llms.txt.
Myślę o llms.txt jak o mapie witryny dla agentów AI. To płaski plik w formacie Markdown hostowany pod domeną.com/llms.txt, który dostarcza uporządkowany katalog dokumentacji — z opisami, dzięki czemu agenty mogą ustalić, co jest istotne, bez konieczności crawlowania całej witryny.
Dobrze sformułowany llms.txt wygląda mniej więcej tak:
# Dokumentacja TwójProdukt
## Rozpoczęcie pracy
- [Szybki start](/docs/quickstart): Zainstaluj i wykonaj pierwsze wywołanie API w 5 minut
- [Uwierzytelnianie](/docs/auth): Wzorce OAuth 2.0 i klucze API
- [Kluczowe koncepcje](/docs/concepts): Model danych, encje, terminologia
## Referencja API
- [Przegląd REST API](/docs/api): Bazowe URL, wersjonowanie, paginacja, kody błędów
- [API Users](/docs/api/users): Operacje CRUD do zarządzania użytkownikami (12K tokenów)
- [API Events](/docs/api/events): Streaming zdarzeń i konfiguracja webhooków (8K tokenów)
Co tworzy dobry llms.txt:
- Opisy mówiące agentowi, co znajdzie, nie tylko jak nazywa się strona
- Liczby tokenów na stronę tam, gdzie przydatne (by agenty mogły podejmować świadome decyzje kontekstowe)
- Organizacja według zadań, nie hierarchii produktowej
- Utrzymany poniżej 5000 tokenów (sam indeks nie powinien wyczerpywać budżetu)
Warstwa 3: Sygnalizacja możliwości przez skill.md
llms.txt mówi agentom, gdzie są rzeczy. skill.md mówi im, co produkt faktycznie potrafi zrobić.
To rozróżnienie ma większe znaczenie, niż się na pierwszy rzut oka wydaje. Zamiast wnioskować możliwości z dokumentacji prozaicznej, skill.md przedstawia je deklaratywnie — mapując intencje na endpointy i zasoby.
Warstwa 4: Formatowanie treści do parsowania przez agenty
Nawet przy idealnym wykrywaniu i sygnalizacji możliwości, faktyczna treść musi być czytelna dla agentów. Kilka rzeczy, które odkryłem jako istotne:
- Serwuj Markdown, nie tylko HTML — dramatycznie niższy koszt tokenowy
- Strukturyzuj do skanowania, nie czytania — agenty parsują strukturę, nie czytają liniowo
- Eliminuj szum nawigacyjny — sidebary, breadcrumby i linki stopki to tylko szum
- Umieszczaj przydatne rzeczy na początku — pierwsze 500 tokenów powinno odpowiadać: czym to jest, co potrafi, czego potrzebuję na start
Warstwa 5: Eksponowanie liczby tokenów
To prostsze, niż brzmi, ale zaskakująco wysokodźwigniowe: pokazuj liczby tokenów na stronach dokumentacji. Idealnie zarówno w indeksie llms.txt, jak i na samych stronach (jako metadane lub nagłówek strony).
To daje agentom informacje potrzebne do podejmowania inteligentnych decyzji — czy włączyć treść całkowicie do kontekstu, czy pominąć na rzecz krótszego źródła.
Podsumowanie
Agenci AI stają się znaczącym konsumentem dokumentacji technicznej, ale zachowują się zupełnie inaczej niż ludzie. Tradycyjna analityka jest dla nich ślepa, a optymalizacja tylko pod ludzkie oczy oznacza utratę rosnącego segmentu odbiorców. AEO — przez kontrolę dostępu, strukturalne wykrywanie, świadomość tokenów i czytelne formatowanie — pozwala obsługiwać oba światy jednocześnie.
Źródło: Addy Osmani, „Agentic Engine Optimization (AEO)", addyosmani.com, kwiecień 2026
