Stopniowe ujawnianie: okna CLI do systemów agentowych

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Systemy agentowe są nieprzejrzyste z założenia. Podejmują decyzje, wywołują narzędzia i koordynują pracę wśród dziesiątek specjalistów. Ale gdy coś idzie nie tak — albo gdy po prostu chcesz zrozumieć, co się dzieje — gdzie szukasz?

Odpowiedzią jest stopniowe ujawnianie: warstwowy interfejs, który odsłania dokładnie tyle złożoności, ile potrzebujesz, dokładnie wtedy, gdy tego potrzebujesz.

Problem nieprzejrzystości

Nowoczesny system orkiestracji agentów może mieć:

• 40+ agentów specjalistycznych, każdy z odrębnymi zdolnościami
• 700+ skilli obejmujących wewnętrzną automatyzację i integracje z dostawcami
• 470+ decyzji architektonicznych kształtujących zachowanie
• Dziesiątki serwerów narzędzi MCP dostarczających zdolności zewnętrzne

Ta złożoność jest zamierzona. Agenci potrzebują dostępu do bogatego kontekstu — wiedzy domenowej, inteligencji kodu, schematów baz danych — żeby podejmować dobre decyzje. Ale to samo bogactwo tworzy problem widoczności.

Skąd wiesz, który agent obsługuje migracje baz danych? Jakie decyzje ukształtowały zachowanie rankingowe systemu wyszukiwania? Do jakich narzędzi ma dostęp doradca architektury?

Bez ustrukturyzowanego dostępu zostajesz z czytaniem kodu źródłowego albo z nadzieją, że dokumentacja jest aktualna.

Stopniowe ujawnianie jako architektura

Stopniowe ujawnianie to nie tylko wzorzec UI. To zasada architektoniczna: organizuj informacje w warstwach, każdą głębszą od poprzedniej, tak by użytkownicy mogli zatrzymać się na poziomie, który odpowiada na ich pytanie.

Dla systemów agentowych przekłada się to na polecenia CLI o rosnącej głębokości:

Poziom	Polecenie	Pytanie, na które odpowiada
1	orkestra system status	Czy wszystko jest zdrowe?
2	orkestra agents list	Jakie agenty istnieją?
3	orkestra agents info <name>	Co robi ten agent?
4	orkestra decisions search	Dlaczego działa w ten sposób?
5	Narzędzia MCP Maguyva	Pokaż mi kod.

Każdy poziom odpowiada na naturalne pytanie uzupełniające. Rzadko musisz skakać od razu do poziomu 5.

Poziom 1: zdrowie systemu

Pierwsze pytanie jest zawsze takie: czy wszystko działa?

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Jedno polecenie. Cztery liczby. Wystarczająco, żeby wiedzieć, że system jest skonfigurowany, a rejestry wypełnione.

Jeśli liczba agentów nieoczekiwanie spada albo skille nie wczytują się, widzisz to tutaj najpierw. Bez konieczności przekopywania się przez logi.

Poziom 2: inwentarz agentów

Gdy już wiesz, że system jest zdrowy, kolejne pytanie brzmi: co jest dostępne?

$ orkestra agents list

To zwraca ustrukturyzowane dane — nazwy agentów, opisy, preferencje modeli, pokrycie domenowe. Wyjście jest domyślnie w JSON, co ułatwia przepuszczenie go przez jq do filtrowania:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Chcesz agentów, którzy obsługują pracę z bazami danych? Polecenie wyszukiwania zawęża to:

$ orkestra agents search "database"

To skanuje nazwy, opisy i zdolności. Znajdujesz właściwego specjalistę bez czytania 40 definicji agentów.

Poziom 3: głębokie zanurzenie w agenta

Znalazłeś agenta, który wygląda na odpowiedni? Polecenie info odsłania wszystko:

$ orkestra agents info architecture-advisor

Wyjście zawiera:

• Metadane: nazwa, kategoria, preferencja modelu, opis
• Domeny: które obszary wiedzy obejmuje ten agent
• Tożsamość: cechy charakteru (architekt, strateg, knowledge-architect)
• Przewodniki narzędzi: która dokumentacja narzędzi jest wstrzykiwana do kontekstu
• Narzędzia: pełna lista narzędzi MCP dostępnych dla tego agenta

Oto próbka tego, co widzisz:

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

To mówi Ci dokładnie, co agent potrafi zrobić. Bez potrzeby sięgania po kod źródłowy.

Poziom 4: archeologia decyzji

Agenci zachowują się zgodnie z udokumentowanymi decyzjami. Gdy musisz zrozumieć dlaczego coś działa w konkretny sposób, rejestr decyzji jest źródłem prawdy.

$ orkestra decisions search "agent"

To zwraca pasujące decyzje architektoniczne:

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Każda decyzja ma pełne pochodzenie — kiedy została podjęta, dlaczego, jakie kompromisy rozważano, które commity ją zaimplementowały:

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

To dokumentacja architektoniczna, która pozostaje aktualna, ponieważ jest wydobywana z commitów, nie utrzymywana ręcznie.

Poziom 5: bezpośrednia inteligencja kodu

Gdy musisz zobaczyć rzeczywistą implementację — nie metadane o niej — narzędzia MCP Maguyva dostarczają bezpośredniego dostępu.

Z poziomu sesji agenta:

mcp__maguyva__intelligent_search
  query: "agent context loading"

To automatycznie trasuje przez wyszukiwanie semantyczne, tekstowe i AST, żeby znaleźć odpowiedni kod. Dla konkretnych symboli:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Dla analizy zależności:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

To nie są tylko zamienniki grep. Są świadome grafu, semantycznie zaindeksowane i zintegrowane z tą samą inteligencją kodu, która napędza samych agentów.

Ujednolicone wyszukiwanie w rejestrach

Czasem nie wiesz, który rejestr zawiera odpowiedź. Ujednolicone wyszukiwanie obejmuje wszystko:

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 dopasowania w pięciu rejestrach. Podsumowanie mówi Ci, gdzie wejść głębiej. Usuń --summary, żeby uzyskać szczegółowe wyniki, albo dodaj --limit 5, żeby utrzymać wyjście w ryzach.

Dlaczego to ma znaczenie

Stopniowe ujawnianie to nie tylko wygoda. Zmienia sposób, w jaki wchodzisz w interakcję ze złożonymi systemami.

Debugowanie staje się wykonalne. Gdy agent podejmuje nieoczekiwaną decyzję, nie grepujesz przez logi. Sprawdzasz, do jakich narzędzi ma dostęp (agents info), jakie decyzje kształtują jego zachowanie (decisions search), i śledzisz implementację, jeśli to konieczne (intelligent_search).

Onboarding przyspiesza. Nowi członkowie zespołu nie muszą czytać całej bazy kodu. Zaczynają od system status, eksplorują za pomocą agents list i idą głębiej dopiero, gdy trafią na coś, czego nie rozumieją.

Dokumentacja pozostaje aktualna. Ponieważ CLI czyta z tych samych rejestrów, które konfigurują agentów, wyjście jest zawsze dokładne. Nie ma rozjazdu między tym, co mówi dokumentacja, a tym, co robi system.

CLI jako interfejs

Mogliśmy zbudować dashboard webowy. Mogliśmy napisać obszerną dokumentację. Zamiast tego zbudowaliśmy CLI, które czyta ze źródła prawdy.

CLI ma przewagi:

• Komponowalne: przepuszczaj wyjście przez jq, integruj ze skryptami
• Skryptowalne: automatyzuj sprawdzenia, generuj raporty
• Szybkie: bez ładowania stron, bez przepływów uwierzytelniania
• Dokładne: czyta faktyczną konfigurację, nie zbuforowaną reprezentację

Dla systemów, w których poprawność liczy się bardziej niż estetyka, CLI wygrywa.

Budowanie własnego stopniowego ujawniania

Jeśli budujesz systemy agentowe, rozważ, jak użytkownicy będą je sprawdzać:

1. Zacznij od sprawdzeń zdrowia. Jedno polecenie, które mówi Ci, czy rzeczy działają.
2. Dostarcz widoki inwentarza. Wypisz, co istnieje, zanim wyjaśnisz, co to robi.
3. Umożliw celowane zapytania. Wyszukiwanie bije przeglądanie na dużą skalę.
4. Odsłoń pochodzenie. Pozwól użytkownikom śledzić decyzje do ich źródeł.
5. Połącz z inteligencją kodu. Ostatecznie użytkownicy muszą zobaczyć implementację.

Każda warstwa odpowiada na pytanie uzupełniające. Buduj je w kolejności częstotliwości — większość użytkowników zatrzymuje się na warstwie 2 lub 3. Tylko zaawansowani użytkownicy sięgają warstwy 5.

Celem nie jest odsłonięcie wszystkiego. Celem jest odsłonięcie dokładnie tego, co potrzebne, dokładnie wtedy, gdy jest potrzebne. To właśnie jest stopniowe ujawnianie zastosowane do architektury agentowej.