Progressive disclosure w AI: spadek tokenów o 91%

Przeładowanie okna kontekstowego (tzw. context rot) powoduje spadek jakości odpowiedzi agentów programistycznych i drastyczny wzrost kosztów infrastruktury LLM. Wdrożenie wzorca progressive disclosure w narzędziach takich jak Claude Code czy agentgateway pozwala ograniczyć zużycie tokenów promptu z 10 877 do zaledwie 970 na jedno zapytanie MCP. Daje to architektom i CTO przewagę techniczną: wydłużenie sesji z 13 do około 2000 eksploracji pliku bez utraty precyzji.

Architektura progressive disclosure i zjawisko context rot

Tradycyjne podejście do konfiguracji agentów AI polega na wstępnym ładowaniu wszystkich instrukcji, schematów API i reguł projektowych do okna kontekstowego. Działanie to wywołuje zjawisko znane jako context rot, w którym rozproszenie uwagi modelu obniża jakość generowanego kodu oraz zwielokrotnia koszty tokenowe. Wzorzec progressive disclosure rozwiązuje ten problem poprzez dynamiczne dostarczanie wiedzy według zasady just-in-time.

Przeładowane okno kontekstowe wywołuje spadek rozdzielczości uwagi LLM (tzw. lost in the middle), gdzie instrukcje umieszczone w środku długiego promptu są ignorowane przez model. Dodatkowo każdy niewykorzystany token nagłówka opłacany jest wielokrotnie w każdej pętli konwersacyjnej. Analiza kodu źródłowego Claude Code (obejmująca około 1884 pliki i 512 tysięcy linii kodu TypeScript) wskazuje, że właściwa logika decyzyjna AI stanowi zaledwie 1,6% kodu, podczas gdy pozostałe 98,4% to deterministyczna infrastruktura wykonawcza i zarządzanie kontekstem.

W nowoczesnych harnessach agentowych koszt kontekstowy jest usystematyzowany hierarchicznie w zależności od punktu rozszerzenia:

• Hooks (0 tokenów kontekstu): uruchamiane zdarzeniowo skrypty przechwytujące pętlę agenta, bez stałego obciążania okna.
• Skills (niski koszt kontekstu): ładowane wstępnie tylko nagłówki YAML (frontmatter) z polem description, właściwa treść pliku SKILL.md trafia do promptu dopiero po dopasowaniu zadania.
• Plugins (średni koszt kontekstu): pakiety dystrybucyjne łączące umiejętności i reguły.
• MCP Servers (wysoki koszt kontekstu): bezpośrednie ładowanie pełnych schematów narzędziowych JSON Schema.

Zamiast przekazywać agentowi cały podręcznik architektury w pliku AGENTS.md lub CLAUDE.md, infrastruktura przekazuje jedynie zwięzłe wskaźniki kontekstowe (context pointers). Agent odczytuje szczegółowe wytyczne dla bazy danych, interfejsu czy testów wyłącznie wtedy, gdy wykonuje operacje na konkretnych plikach w danym katalogu.

Jak ograniczyć koszty kontekstu agenta w MCP?

Integracja narzędzi zewnętrznych poprzez Model Context Protocol generuje ogromne narzuty kontekstowe w bramkach AI, sięgające nawet 100 000 tokenów przed wysłaniem pierwszego zapytania. Agent wywołujący serwery MCP musi za każdym razem przetwarzać pełne definicje struktur JSON Schema dla dziesiątek funkcji. Zastosowanie filtra wyszukiwania dynamicznego w agentgateway pozwala na natychmiastową eliminację nieużywanych schematów narzędziowych.

W tradycyjnym trybie pracy serwera MCP (Standard Mode) bramka przekazuje pełną listę definicji narzędzi przy każdym wywołaniu modelu. Przełączenie zasobu EnterpriseAgentgatewayBackend w środowisku Kubernetes na tryb wyszukiwania (toolMode: Search) wdraża wzorzec progressive disclosure. Model otrzymuje jedynie lekki interfejs trasujący, a pełny schemat konkretnego narzędzia jest dostarczany dopiero po zgłoszeniu zapotrzebowania przez agenta.

Praktyczny pomiar zużycia tokenów promptu wykazuje drastyczną różnicę wydajnościową:

• Tryb Standard (bez progressive disclosure): 10 877 tokenów promptu.
• Tryb Search (z progressive disclosure): 970 tokenów promptu.
• Oszczędność: 91,1% mniej tokenów przy identycznym wyniku biznesowym.

Podobne rezultaty osiągane są na poziomie analizy kodu źródłowego przy użyciu narzędzi celowanych (np. interfejsu CLI reveal). Odczytanie całego pliku modułu autoryzacji o długości 2400 linii konsumuje 7 500 tokenów, podczas gdy odczyt struktury pliku (50 tokenów) oraz wyodrębnienie jednej funkcji (45 tokenów) wymaga 95 tokenów. Przekłada się to na 150-krotną redukcję tokenów, zmniejszenie kosztu eksploracji z 0,15 USD do 0,001 USD oraz podniesienie limitu bezpiecznych eksploracji w oknie 100K z 13 plików do około 2000 operacji.

Wydajność agentów przy skalowaniu bibliotek skills i repozytoriów

Wraz ze wzrostem liczby umiejętności w bibliotece agenta tradycyjne ładowanie bezwarunkowe doprowadza do przepełnienia kontekstu oraz całkowitej awarii systemu. Testy w środowiskach korporacyjnych i na dużych zbiorach dokumentów wykazują, że bez odpowiedniego filtrowania precyzja wyszukiwania wiedzy gwałtownie spada. Wdrożenie jednopoziomowego indeksowania pozwala utrzymać stabilną dokładność odpowiedzi przy drastycznym ograniczeniu nakładów finansowych.

Badania przeprowadzone przez Workday AI Research na grupie 5500 przedsiębiorstw wykazują bariery skalowalności tradycyjnego ładowania bezwarunkowego (eager loading):

• Przepełnienie kontekstu przy N=100: przy bibliotece 100 umiejętności bezwarunkowe ładowanie wywołuje 100% awarii (context overflow / crash) we wszystkich testowanych modelach (Qwen2.5-7B, Qwen3-8B, Qwen3-14B).
• Wskaźnik sukcesu wyszukiwania przy N=50: dla modelu Qwen3-14B bezwarunkowe ładowanie osiąga zaledwie 13% skuteczności (zużywając 14 875 tokenów/zadanie), podczas gdy progressive disclosure osiąga 72% skuteczności przy zużyciu 2 719 tokenów/zadanie (81,7% oszczędności tokenów).
• Narzut opóźnienia: progressive disclosure wymaga dodatkowego wywołania LLM do wyboru umiejętności, co podnosi średnie opóźnienie o 15% (np. z 1,75 s do 2,01 s przy N=50 na Qwen3-8B).

W przypadku skalowania bazy wiedzy do rozmiarów biblioteki (benchmark ∞Bench / LOONGDOC przy skali K=20 książek) nawigacja po surowych dokumentach ulega całkowitemu załamaniu:

• Nawigacja surowa (raw navigation): precyzja odpowiedzi na otwarte pytania (English Open QA) spada do 25,7%, zużywając 68,3 mln tokenów na zapytanie (niebuforowany koszt 52 USD).
• Płaskie progressive disclosure (flat skill pack): utrzymuje precyzję na poziomie 46,2%, zużywając 32,5 mln tokenów (koszt 25 USD).

Z kolei badania ablacyjne nad bazy wiedzy w formacie wiki (709 stron markdown, system Claude Opus 4.8) wykazały, że dodanie jednostronicowych podsumowań oraz narzędzia wyszukiwania słów kluczowych (wiki_query.py) redukuje całkowity koszt zapytania o 30% w trybie wymuszonym, 34% w trybie swobodnym oraz 58% przy wstępnym ładowaniu katalogu. Wynika to ze zmniejszenia średniej liczby cytowanych stron z 6,10 do 4,22.

Porównanie wzorców ładowania kontekstu i bilans ryzyka

Wybór optymalnej architektury ładowania wiedzy wymaga zbilansowania zużycia tokenów, poziomu opóźnień oraz ryzyka błędnego trasowania zapytań przez model. Zbyt głęboka hierarchia struktur instruktażowych wprowadza dodatkowy szum informacyjny, wywołując degradację wyników przy braku korzyści wydajnościowych. Dodatkowo rozszerzenia wywołań zewnętrznych stwarzają nowe podatności w obszarze bezpieczeństwa i kontroli uprawnień.

Zestawienie głównych wzorców zarządzania kontekstem w agentach AI przedstawia poniższa tabela:

Wdrożenie progressive disclosure wiąże się z konkretnymi ryzykami technicznymi i bezpieczeństwa:

• Ryzyko zbyt głębokiej hierarchii (hierarchical disclosure): dodanie drugiego poziomu trasowania (meta-routera z nagłówkami pod-skilli) nie poprawia wyników, a w wielu przypadkach obniża precyzję (np. spadek dokładności na zadaniu En.MC z 91,3% do 64,0% w modelu Pi gpt-5.4-mini). Jednoetapowy płaski indeks jest optymalnym standardem.
• Podatności wywołań MCP: dynamiczne ładowanie serwerów MCP stwarza ryzyko tool poisoning, rug pulls oraz shadowing (przesłaniania narzędzi wbudowanych przez zewnętrzne serwery).
• Luki w weryfikacji uprawnień: w Claude Code reguły odmowy (deny rules) i klasyfikatory ML działają w pętli wykonawczej, ale niepoprawna kolejność inicjalizacji rozszerzeń może umożliwić uruchomienie skryptów przed weryfikacją polityki bezpieczeństwa.

Wnioski praktyczne i rekomendacje

• Skonfiguruj bramki agentowe (np. agentgateway w klastrze Kubernetes) w trybie wyszukiwania dynamicznego (toolMode: Search) dla wszystkich produkcyjnych serwerów MCP, aby zredukować narzut tokenowy o 91%.
• Zmierz udział kosztów okna kontekstowego w sesjach programistycznych, weryfikując częstotliwość występowania pętli compaction oraz stopień nasycenia promptu instrukcjami statycznymi.
• Zweryfikuj strukturę repozytorium pod kątem plików AGENTS.md i CLAUDE.md, usuwając z nich pełne procedury operacyjne i zastępując je zwięzłymi wskaźnikami kontekstowymi do plików w katalogach .claude/skills/ lub .agents/skills/.
• Wdróż płaski wzorzec jednopoziomowy (flat disclosure) dla bibliotek umiejętności i dokumentacji technicznej, unukając tworzenia wielopoziomowych drzew trasujących, które generują zbędny narzut opóźnień i obniżają precyzję odpowiedzi.

Źródła

• Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems – Zhiqiang Shen
• Is Progressive Disclosure All You Need for Long-Context Agents? – arXiv
• MCP Progressive Disclosure: Cut Token Usage 91% with agentgateway | Solo.io
• Progressive Disclosure for AI Agents – Semantic Infrastructure Lab
• Progressive Disclosure for LLM-Maintained Wiki Knowledge Bases: a Preregistered Ablation – arXiv
• Progressive Disclosure in AI Agents: How to Load Context Without Killing Output Quality
• Progressive context disclosure | Technology Radar – Thoughtworks
• Progressive disclosure | AI Coding Dictionary – AI Hero