Progresivní odkrývání: okna CLI do agentních systémů

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

Agentní systémy jsou neprůhledné záměrně. Dělají rozhodnutí, volají nástroje a koordinují práci napříč desítkami specialistů. Ale když se něco pokazí — nebo když si prostě chcete ujasnit, co se děje — kam se podíváte?

Odpověď je progresivní odkrývání: vrstvené rozhraní, které odkryje přesně tolik složitosti, kolik potřebujete, přesně ve chvíli, kdy to potřebujete.

Problém neprůhlednosti

Moderní systém orchestrace agentů může mít:

• 40+ specializovaných agentů, každý s odlišnými schopnostmi
• 700+ skillů rozprostřených napříč interní automatizací a integracemi dodavatelů
• 470+ architektonických rozhodnutí, která formují chování
• desítky serverů nástrojů MCP poskytujících externí schopnosti

Tahle složitost je záměrná. Agenti potřebují přístup k bohatému kontextu — doménovým znalostem, inteligenci nad kódem, databázovým schématům —, aby se dobře rozhodovali. Ale právě tahle bohatost vytváří problém s viditelností.

Jak poznáte, který agent má na starosti databázové migrace? Jaká rozhodnutí utvářela chování řazení výsledků ve vyhledávacím systému? Ke kterým nástrojům má přístup poradce pro architekturu?

Bez strukturovaného přístupu vám zbývá číst zdrojový kód nebo doufat, že dokumentace je aktuální.

Progresivní odkrývání jako architektura

Progresivní odkrývání není jen vzorec UI. Je to architektonický princip: organizujte informace do vrstev, každou hlubší než tu předchozí, aby uživatelé mohli zastavit na úrovni, která zodpoví jejich otázku.

Pro agentní systémy se to překládá do CLI příkazů rostoucí hloubky:

Úroveň	Příkaz	Zodpovězená otázka
1	orkestra system status	Je všechno zdravé?
2	orkestra agents list	Jací agenti existují?
3	orkestra agents info <name>	Co tenhle agent dělá?
4	orkestra decisions search	Proč to funguje takhle?
5	Nástroje Maguyva MCP	Ukaž mi kód.

Každá úroveň zodpoví přirozenou navazující otázku. Zřídkakdy potřebujete skočit rovnou na úroveň 5.

Úroveň 1: Zdraví systému

První otázka je vždy: funguje všechno?

$ orkestra system status

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

Jeden příkaz. Čtyři čísla. Dost na to, abyste věděli, že systém je nakonfigurovaný a registry jsou naplněné.

Pokud počet agentů neočekávaně klesne, nebo se skilly nenačtou, uvidíte to tady jako první. Žádné hrabání se v lozích.

Úroveň 2: Inventář agentů

Jakmile víte, že je systém zdravý, další otázka zní: co je k dispozici?

$ orkestra agents list

Vrátí strukturovaná data — jména agentů, popisy, preference modelu, pokrytí domén. Výstup je ve výchozím stavu JSON, takže se snadno pipe-uje do jq pro filtrování:

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

Chcete agenty, kteří zvládají databázovou práci? Příkaz pro vyhledávání to zúží:

$ orkestra agents search "database"

Prochází jména, popisy a schopnosti. Najdete správného specialistu, aniž byste museli číst 40 definic agentů.

Úroveň 3: Hluboký ponor do agenta

Našli jste agenta, který vypadá relevantně? Příkaz info odhalí všechno:

$ orkestra agents info architecture-advisor

Výstup obsahuje:

• Metadata: jméno, kategorii, preferenci modelu, popis
• Domény: které znalostní oblasti tento agent pokrývá
• Identitu: charakterové rysy (architect, strategist, knowledge-architect)
• Průvodce nástroji: která dokumentace nástrojů se vkládá do kontextu
• Nástroje: úplný seznam MCP nástrojů dostupných tomuto agentovi

Tady je ukázka toho, co uvidíte:

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 vám přesně řekne, co agent umí. Žádný zdrojový kód není potřeba.

Úroveň 4: Archeologie rozhodnutí

Agenti se chovají podle zdokumentovaných rozhodnutí. Když potřebujete pochopit proč něco funguje určitým způsobem, registr rozhodnutí je zdroj pravdy.

$ orkestra decisions search "agent"

Vrátí odpovídající architektonická rozhodnutí:

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

Každé rozhodnutí má plnou provenienci — kdy bylo učiněno, proč, jaké kompromisy byly zvažovány, které commity ho implementovaly:

$ 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..."
    }
  ]
}

Tohle je architektonická dokumentace, která zůstává aktuální, protože se těží z commitů, ne udržuje ručně.

Úroveň 5: Přímá inteligence nad kódem

Když potřebujete vidět skutečnou implementaci — ne metadata o ní —, nástroje MCP od Maguyvy poskytují přímý přístup.

Zevnitř session agenta:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Tohle automaticky routuje napříč sémantickým, textovým a AST vyhledáváním, aby našlo relevantní kód. Pro konkrétní symboly:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Pro analýzu závislostí:

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

Tohle nejsou jen náhrady za grep. Jsou vědomé grafu, sémanticky indexované a integrované se stejnou inteligencí nad kódem, která pohání samotné agenty.

Sjednocené vyhledávání napříč registry

Někdy nevíte, který registr obsahuje odpověď. Sjednocené vyhledávání pokrývá všechno:

$ orkestra search "database" --summary

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

254 shod napříč pěti registry. Souhrn vám řekne, kam se ponořit hlouběji. Odeberte --summary pro podrobné výsledky, nebo přidejte --limit 5, aby výstup zůstal přehledný.

Proč na tom záleží

Progresivní odkrývání není jen o pohodlí. Mění to, jak interagujete se složitými systémy.

Debugování se stává zvladatelným. Když agent udělá neočekávané rozhodnutí, nehrabete se v lozích. Zkontrolujete, ke kterým nástrojům má přístup (agents info), jaká rozhodnutí formují jeho chování (decisions search), a v případě potřeby vysledujete implementaci (intelligent_search).

Onboarding se zrychluje. Noví členové týmu nemusí číst celou kódovou základnu. Začnou s system status, prozkoumají s agents list a ponoří se hlouběji, jen když narazí na něco, čemu nerozumí.

Dokumentace zůstává aktuální. Protože CLI čte ze stejných registrů, které konfigurují agenty, výstup je vždy přesný. Neexistuje rozestup mezi tím, co říká dokumentace, a tím, co systém skutečně dělá.

CLI jako rozhraní

Mohli jsme postavit webový dashboard. Mohli jsme napsat rozsáhlou dokumentaci. Místo toho jsme postavili CLI, které čte ze zdroje pravdy.

CLI má výhody:

• Kompozovatelné: pipe-ujte výstup skrz jq, integrujte se se skripty
• Skriptovatelné: automatizujte kontroly, generujte reporty
• Rychlé: žádné načítání stránek, žádné autentizační toky
• Přesné: čte skutečnou konfiguraci, ne cachovanou reprezentaci

Pro systémy, kde na správnosti záleží víc než na estetice, vyhrává CLI.

Postavte si vlastní progresivní odkrývání

Pokud stavíte agentní systémy, zvažte, jak je budou uživatelé zkoumat:

1. Začněte kontrolami zdraví. Jeden příkaz, který vám řekne, jestli věci fungují.
2. Poskytněte pohledy na inventář. Vypište, co existuje, dřív než vysvětlíte, co to dělá.
3. Umožněte cílené dotazy. Vyhledávání v měřítku poráží procházení.
4. Vystavte provenienci. Nechte uživatele vysledovat rozhodnutí k jejich původu.
5. Napojte se na inteligenci nad kódem. Nakonec uživatelé potřebují vidět implementaci.

Každá vrstva zodpoví navazující otázku. Stavte je v pořadí podle frekvence — většina uživatelů zastaví na vrstvě 2 nebo 3. Jen power useři dosáhnou vrstvy 5.

Cílem není vystavit všechno. Je to vystavit přesně to, co je potřeba, přesně ve chvíli, kdy je to potřeba. To je progresivní odkrývání aplikované na architekturu agentů.