Progressiv exponering: CLI-fönster in i agentsystem

Siffrorna i det här inlägget speglar systemet vid publicering (januari 2026). Se vår teamsida för aktuella siffror.

Agentsystem är ogenomskinliga med avsikt. De fattar beslut, anropar verktyg och koordinerar arbete över dussintals specialister. Men när något går fel — eller när man helt enkelt vill förstå vad som händer — var tittar man då?

Svaret är progressiv exponering: ett skiktat gränssnitt som avslöjar exakt så mycket komplexitet som man behöver, exakt när man behöver det.

Ogenomskinlighetsproblemet

Ett modernt agentorkestreringssystem kan ha:

• 40+ specialistagenter, var och en med distinkta förmågor
• 700+ skills som spänner över intern automation och leverantörsintegrationer
• 470+ arkitektoniska beslut som formar beteende
• Dussintals MCP-verktygsservrar som tillhandahåller externa förmågor

Den här komplexiteten är avsiktlig. Agenter behöver tillgång till rik kontext — domänkunskap, kodintelligens, databasscheman — för att fatta bra beslut. Men samma rikedom skapar ett synlighetsproblem.

Hur vet man vilken agent som hanterar databasmigreringar? Vilka beslut formade söksystemets rankningsbeteende? Vilka verktyg har arkitekturrådgivaren tillgång till?

Utan strukturerad åtkomst är man hänvisad till att läsa källkod eller hoppas att dokumentationen är aktuell.

Progressiv exponering som arkitektur

Progressiv exponering är inte bara ett UI-mönster. Det är en arkitektonisk princip: organisera information i lager, vart och ett djupare än det förra, så att användare kan stanna på den nivå som besvarar deras fråga.

För agentsystem översätts det här till CLI-kommandon på stigande djup:

Nivå	Kommando	Fråga som besvaras
1	orkestra system status	Är allt friskt?
2	orkestra agents list	Vilka agenter finns?
3	orkestra agents info <name>	Vad gör den här agenten?
4	orkestra decisions search	Varför fungerar det på det här sättet?
5	MCP-verktyg i Maguyva	Visa mig koden.

Varje nivå besvarar en naturlig följdfråga. Man behöver sällan hoppa direkt till nivå 5.

Nivå 1: Systemhälsa

Den första frågan är alltid: fungerar allt?

$ orkestra system status

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

Ett kommando. Fyra siffror. Tillräckligt för att veta att systemet är konfigurerat och registren är befolkade.

Om ett agentantal sjunker oväntat eller skills misslyckas med att laddas ser man det här först. Ingen loggdykning krävs.

Nivå 2: Agentinventering

När man väl vet att systemet är friskt är nästa fråga: vad finns tillgängligt?

$ orkestra agents list

Det här returnerar strukturerad data — agentnamn, beskrivningar, modellpreferenser, domäntäckning. Utdatan är JSON som standard, vilket gör det enkelt att leda vidare till jq för filtrering:

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

Vill man ha agenter som hanterar databasarbete? Sökkommandot smalnar av det:

$ orkestra agents search "database"

Det här skannar namn, beskrivningar och förmågor. Man hittar rätt specialist utan att läsa 40 agentdefinitioner.

Nivå 3: Djupdykning i agenten

Har man hittat en agent som verkar relevant? Kommandot info avslöjar allt:

$ orkestra agents info architecture-advisor

Utdatan innehåller:

• Metadata: Namn, kategori, modellpreferens, beskrivning
• Domäner: Vilka kunskapsområden agenten täcker
• Identitet: Karaktärsdrag (arkitekt, strateg, kunskapsarkitekt)
• Verktygsguider: Vilken verktygsdokumentation som injiceras i kontexten
• Verktyg: Den fullständiga listan av MCP-verktyg agenten har tillgång till

Här är ett smakprov på vad man ser:

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

Det här berättar exakt vad agenten kan göra. Ingen källkod krävs.

Nivå 4: Beslutsarkeologi

Agenter beter sig enligt dokumenterade beslut. När man behöver förstå varför något fungerar på ett visst sätt är beslutsregistret sanningskällan.

$ orkestra decisions search "agent"

Det här returnerar matchande arkitektoniska beslut:

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

Varje beslut har full proveniens — när det fattades, varför, vilka avvägningar som övervägdes, vilka commits som implementerade det:

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

Det här är arkitektonisk dokumentation som förblir aktuell eftersom den bryts ut ur commits, inte underhålls manuellt.

Nivå 5: Direkt kodintelligens

När man behöver se den faktiska implementationen — inte metadata om den — ger MCP-verktygen i Maguyva direkt åtkomst.

Inifrån en agentsession:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Det här dirigerar automatiskt över semantisk, text- och AST-sökning för att hitta relevant kod. För specifika symboler:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

För beroendeanalys:

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

Det här är inte bara grep-ersättningar. De är grafmedvetna, semantiskt indexerade, och integrerade med samma kodintelligens som driver agenterna själva.

Enhetlig sökning över register

Ibland vet man inte vilket register som har svaret. Den enhetliga sökningen spänner över allt:

$ orkestra search "database" --summary

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

254 träffar över fem register. Sammanfattningen berättar var man ska gräva djupare. Ta bort --summary för detaljerade resultat, eller lägg till --limit 5 för att hålla utdatan hanterbar.

Varför det här spelar roll

Progressiv exponering handlar inte bara om bekvämlighet. Det förändrar hur man interagerar med komplexa system.

Felsökning blir hanterbar. När en agent fattar ett oväntat beslut behöver man inte grepa genom loggar. Man kontrollerar vilka verktyg den har tillgång till (agents info), vilka beslut som formar dess beteende (decisions search), och spårar implementationen om det behövs (intelligent_search).

Onboarding går snabbare. Nya teammedlemmar behöver inte läsa hela kodbasen. De börjar med system status, utforskar med agents list, och går djupare bara när de stöter på något de inte förstår.

Dokumentationen förblir aktuell. Eftersom CLI:t läser från samma register som konfigurerar agenterna är utdatan alltid korrekt. Det finns ingen glidning mellan vad dokumentationen säger och vad systemet gör.

CLI:t som gränssnitt

Vi kunde ha byggt en webbaserad instrumentpanel. Vi kunde ha skrivit omfattande dokumentation. Istället byggde vi ett CLI som läser från sanningskällan.

CLI:t har fördelar:

• Komponerbart: Led utdata genom jq, integrera med skript
• Skriptbart: Automatisera kontroller, generera rapporter
• Snabbt: Inga sidladdningar, inga autentiseringsflöden
• Korrekt: Läser den faktiska konfigurationen, inte en cachad representation

För system där korrekthet spelar större roll än estetik vinner CLI:t.

Att bygga sin egen progressiva exponering

Om man bygger agentsystem, fundera på hur användare kommer att inspektera dem:

1. Börja med hälsokontroller. Ett kommando som berättar om saker fungerar.
2. Erbjud inventeringsvyer. Lista vad som finns innan man förklarar vad det gör.
3. Möjliggör riktade sökningar. Sökning slår bläddring i stor skala.
4. Exponera proveniens. Låt användare spåra beslut till deras ursprung.
5. Koppla till kodintelligens. Till slut behöver användare se implementationen.

Varje lager besvarar en följdfråga. Bygg dem i frekvensordning — de flesta användare stannar på lager 2 eller 3. Bara superanvändare når lager 5.

Målet är inte att exponera allt. Det är att exponera exakt det som behövs, exakt när det behövs. Det är progressiv exponering tillämpad på agentarkitektur.