Progressive Disclosure: CLI-Fenster in Agent-Systeme

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Werte findest du auf unserer Team-Seite.

Agentensysteme sind von Natur aus undurchsichtig. Sie treffen Entscheidungen, rufen Tools auf und koordinieren Arbeit über Dutzende Spezialisten hinweg. Aber wenn etwas schiefgeht – oder du einfach verstehen willst, was gerade passiert – wo schaust du dann nach?

Die Antwort lautet Progressive Disclosure: eine geschichtete Oberfläche, die genau so viel Komplexität offenlegt, wie du brauchst, genau dann, wenn du sie brauchst.

Das Undurchsichtigkeits-Problem

Ein modernes Agenten-Orchestrierungssystem kann Folgendes umfassen:

• 40+ Spezialagenten, jeder mit eigenen Fähigkeiten
• 700+ Skills, die interne Automatisierung und Drittanbieter-Integrationen abdecken
• 470+ Architekturentscheidungen, die das Verhalten prägen
• Dutzende MCP-Tool-Server, die externe Fähigkeiten bereitstellen

Diese Komplexität ist beabsichtigt. Agenten brauchen Zugriff auf reichhaltigen Kontext – Fachwissen, Code Intelligence, Datenbankschemata –, um gute Entscheidungen zu treffen. Aber genau dieser Reichtum schafft ein Sichtbarkeitsproblem.

Woher weißt du, welcher Agent Datenbankmigrationen übernimmt? Welche Entscheidungen haben das Ranking-Verhalten des Suchsystems geprägt? Auf welche Tools hat der Architektur-Advisor Zugriff?

Ohne strukturierten Zugriff bleibt dir nur, den Quellcode zu lesen oder zu hoffen, dass die Dokumentation aktuell ist.

Progressive Disclosure als Architektur

Progressive Disclosure ist nicht nur ein UI-Muster. Es ist ein Architekturprinzip: Informationen in Schichten organisieren, jede tiefer als die vorherige, sodass Nutzer auf der Ebene stehen bleiben können, die ihre Frage beantwortet.

Für Agentensysteme übersetzt sich das in CLI-Befehle mit zunehmender Tiefe:

Ebene	Befehl	Beantwortete Frage
1	orkestra system status	Ist alles gesund?
2	orkestra agents list	Welche Agenten gibt es?
3	orkestra agents info <name>	Was macht dieser Agent?
4	orkestra decisions search	Warum funktioniert es so?
5	MCP-Tools von Maguyva	Zeig mir den Code.

Jede Ebene beantwortet eine natürliche Anschlussfrage. Du musst nur selten direkt zu Ebene 5 springen.

Ebene 1: Systemzustand

Die erste Frage lautet immer: Läuft alles?

$ orkestra system status

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

Ein Befehl. Vier Zahlen. Genug, um zu wissen, dass das System konfiguriert und die Registries befüllt sind.

Wenn eine Agentenzahl unerwartet sinkt oder Skills nicht laden, siehst du das hier zuerst. Keine Log-Wühlerei nötig.

Ebene 2: Agenten-Inventar

Sobald du weißt, dass das System gesund ist, lautet die nächste Frage: Was ist verfügbar?

$ orkestra agents list

Das liefert strukturierte Daten – Agentennamen, Beschreibungen, Modellpräferenzen, Domänenabdeckung. Die Ausgabe ist standardmäßig JSON, sodass sie sich leicht in jq zum Filtern weiterleiten lässt:

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

Du suchst Agenten, die Datenbankarbeit übernehmen? Der Suchbefehl grenzt das ein:

$ orkestra agents search "database"

Das durchsucht Namen, Beschreibungen und Fähigkeiten. Du findest den richtigen Spezialisten, ohne 40 Agentendefinitionen zu lesen.

Ebene 3: Agenten im Detail

Einen Agenten gefunden, der relevant aussieht? Der Befehl info zeigt alles:

$ orkestra agents info architecture-advisor

Die Ausgabe umfasst:

• Metadaten: Name, Kategorie, Modellpräferenz, Beschreibung
• Domänen: Welche Wissensbereiche dieser Agent abdeckt
• Identität: Charaktereigenschaften (Architekt, Stratege, Knowledge-Architect)
• Werkzeugleitfäden: Welche Tool-Dokumentation in den Kontext eingespeist wird
• Tools: Die vollständige Liste der MCP-Tools, auf die dieser Agent Zugriff hat

Hier ein Ausschnitt dessen, was du siehst:

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

Das sagt dir genau, was der Agent kann. Kein Quellcode nötig.

Ebene 4: Entscheidungsarchäologie

Agenten verhalten sich gemäß dokumentierten Entscheidungen. Wenn du verstehen willst, warum etwas auf eine bestimmte Weise funktioniert, ist die Decisions-Registry die maßgebliche Quelle.

$ orkestra decisions search "agent"

Das liefert passende Architekturentscheidungen:

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

Jede Entscheidung hat eine vollständige Herkunftsangabe – wann sie getroffen wurde, warum, welche Kompromisse abgewogen wurden, welche Commits sie umgesetzt haben:

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

Das ist Architekturdokumentation, die aktuell bleibt, weil sie aus Commits gewonnen wird, nicht manuell gepflegt.

Ebene 5: Direkte Code Intelligence

Wenn du die tatsächliche Implementierung sehen musst – nicht nur Metadaten darüber –, liefern die MCP-Tools von Maguyva direkten Zugriff.

Aus einer Agenten-Session heraus:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Das routet automatisch über semantische, textbasierte und AST-Suche, um relevanten Code zu finden. Für konkrete Symbole:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Für Abhängigkeitsanalysen:

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

Das sind nicht einfach nur grep-Ersatzwerkzeuge. Sie sind graphbewusst, semantisch indiziert und in dieselbe Code Intelligence eingebunden, die auch die Agenten selbst antreibt.

Einheitliche Suche über alle Registries

Manchmal weißt du nicht, welche Registry die Antwort enthält. Die einheitliche Suche deckt alles ab:

$ orkestra search "database" --summary

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

254 Treffer über fünf Registries hinweg. Die Zusammenfassung zeigt dir, wo du tiefer einsteigen solltest. Entferne --summary für detaillierte Ergebnisse, oder füge --limit 5 hinzu, um die Ausgabe überschaubar zu halten.

Warum das wichtig ist

Progressive Disclosure ist nicht nur eine Frage der Bequemlichkeit. Es verändert, wie du mit komplexen Systemen umgehst.

Debugging wird handhabbar. Wenn ein Agent eine unerwartete Entscheidung trifft, durchsuchst du nicht Logs mit grep. Du prüfst, auf welche Tools er Zugriff hat (agents info), welche Entscheidungen sein Verhalten prägen (decisions search), und verfolgst bei Bedarf die Implementierung (intelligent_search).

Onboarding wird schneller. Neue Teammitglieder müssen nicht die gesamte Codebasis lesen. Sie starten mit system status, erkunden mit agents list und gehen erst tiefer, wenn sie auf etwas stoßen, das sie nicht verstehen.

Dokumentation bleibt aktuell. Weil die CLI aus denselben Registries liest, die auch die Agenten konfigurieren, ist die Ausgabe immer korrekt. Es gibt keine Diskrepanz zwischen dem, was die Dokumentation sagt, und dem, was das System tut.

Die CLI als Schnittstelle

Wir hätten ein Web-Dashboard bauen können. Wir hätten ausführliche Dokumentation schreiben können. Stattdessen haben wir eine CLI gebaut, die aus der maßgeblichen Quelle liest.

Die CLI hat Vorteile:

• Composable: Ausgabe durch jq leiten, in Skripte integrieren
• Scriptbar: Prüfungen automatisieren, Berichte erzeugen
• Schnell: Keine Seitenaufrufe, keine Authentifizierungs-Umwege
• Präzise: Liest die tatsächliche Konfiguration, keine zwischengespeicherte Darstellung

Für Systeme, bei denen Korrektheit wichtiger ist als Ästhetik, gewinnt die CLI.

Deine eigene Progressive Disclosure bauen

Wenn du Agentensysteme baust, überlege dir, wie Nutzer sie inspizieren werden:

1. Mit Health-Checks beginnen. Ein Befehl, der dir sagt, ob alles läuft.
2. Inventaransichten bereitstellen. Zeige, was existiert, bevor du erklärst, was es tut.
3. Gezielte Abfragen ermöglichen. Suche schlägt Durchblättern im großen Maßstab.
4. Herkunft offenlegen. Lass Nutzer Entscheidungen zu ihrem Ursprung zurückverfolgen.
5. Mit Code Intelligence verbinden. Irgendwann müssen Nutzer die Implementierung sehen.

Jede Schicht beantwortet eine Anschlussfrage. Baue sie in der Reihenfolge ihrer Häufigkeit auf – die meisten Nutzer bleiben bei Ebene 2 oder 3 stehen. Nur Power-User erreichen Ebene 5.

Das Ziel ist nicht, alles offenzulegen. Es geht darum, genau das offenzulegen, was gebraucht wird, genau dann, wenn es gebraucht wird. Das ist Progressive Disclosure, angewendet auf Agentenarchitektur.