Progressiv avdekking: CLI-vinduer inn i agentsystemer

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

Agentsystemer er ugjennomsiktige av design. De tar beslutninger, påkaller verktøy, og koordinerer arbeid på tvers av dusinvis av spesialister. Men når noe går galt — eller når du bare vil forstå hva som skjer — hvor ser du da?

Svaret er progressiv avdekking: et lagdelt grensesnitt som avslører nøyaktig så mye kompleksitet som du trenger, nøyaktig når du trenger det.

Ugjennomsiktighetsproblemet

Et moderne orkestreringssystem for agenter kan ha:

• 40+ spesialistagenter, hver med distinkte kapabiliteter
• 700+ skills som spenner over intern automatisering og leverandørintegrasjoner
• 470+ arkitekturbeslutninger som former atferd
• Dusinvis av MCP-verktøyservere som tilbyr eksterne kapabiliteter

Denne kompleksiteten er tilsiktet. Agenter trenger tilgang til rik kontekst — domenekunnskap, kodeintelligens, databaseskjemaer — for å ta gode beslutninger. Men den samme rikdommen skaper et synlighetsproblem.

Hvordan vet du hvilken agent som håndterer databasemigrasjoner? Hvilke beslutninger formet søkesystemets rangeringsatferd? Hvilke verktøy har arkitekturrådgiveren tilgang til?

Uten strukturert tilgang blir du sittende igjen med å lese kildekode eller håpe at dokumentasjonen er oppdatert.

Progressiv avdekking som arkitektur

Progressiv avdekking er ikke bare et UI-mønster. Det er et arkitektonisk prinsipp: organiser informasjon i lag, hvert dypere enn det forrige, slik at brukere kan stoppe på nivået som svarer på spørsmålet deres.

For agentsystemer oversettes dette til CLI-kommandoer med økende dybde:

Nivå	Kommando	Spørsmål som besvares
1	orkestra system status	Er alt sunt?
2	orkestra agents list	Hvilke agenter finnes?
3	orkestra agents info <name>	Hva gjør denne agenten?
4	orkestra decisions search	Hvorfor fungerer det slik?
5	Maguyva MCP-verktøy	Vis meg koden.

Hvert nivå svarer på et naturlig oppfølgingsspørsmål. Du trenger sjelden å hoppe rett til nivå 5.

Nivå 1: Systemhelse

Det første spørsmålet er alltid: fungerer alt?

$ orkestra system status

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

Én kommando. Fire tall. Nok til å vite at systemet er konfigurert og registrene er fylt.

Hvis et agentantall faller uventet, eller skills ikke laster, ser du det her først. Ingen loggdykking nødvendig.

Nivå 2: Agentinventar

Når du vet at systemet er sunt, er det neste spørsmålet: hva er tilgjengelig?

$ orkestra agents list

Dette returnerer strukturerte data — agentnavn, beskrivelser, modellpreferanser, domenedekning. Resultatet er JSON som standard, noe som gjør det enkelt å pipe inn i jq for filtrering:

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

Vil du ha agenter som håndterer databasearbeid? Søkekommandoen snevrer det inn:

$ orkestra agents search "database"

Dette skanner navn, beskrivelser og kapabiliteter. Du finner riktig spesialist uten å lese 40 agentdefinisjoner.

Nivå 3: Dypdykk i agent

Fant du en agent som ser relevant ut? Kommandoen info avslører alt:

$ orkestra agents info architecture-advisor

Resultatet inkluderer:

• Metadata: Navn, kategori, modellpreferanse, beskrivelse
• Domener: Hvilke kunnskapsområder denne agenten dekker
• Identity: Karaktertrekk (architect, strategist, knowledge-architect)
• Verktøyguider: Hvilken verktøydokumentasjon som injiseres i konteksten
• Verktøy: Den fullstendige listen over MCP-verktøy tilgjengelig for denne agenten

Her er et utdrag av hva du 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",
      ...
    ]
  }
}

Dette forteller deg nøyaktig hva agenten kan gjøre. Ingen kildekode nødvendig.

Nivå 4: Beslutningsarkeologi

Agenter oppfører seg i henhold til dokumenterte beslutninger. Når du trenger å forstå hvorfor noe fungerer på en bestemt måte, er beslutningsregisteret sannhetskilden.

$ orkestra decisions search "agent"

Dette returnerer matchende arkitekturbeslutninger:

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

Hver beslutning har full herkomst — når den ble tatt, hvorfor, hvilke avveininger som ble vurdert, hvilke commits som implementerte den:

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

Dette er arkitekturdokumentasjon som forblir oppdatert fordi den er utvunnet fra commits, ikke manuelt vedlikeholdt.

Nivå 5: Direkte kodeintelligens

Når du trenger å se selve implementasjonen — ikke metadata om den — gir Maguyvas MCP-verktøy direkte tilgang.

Fra innsiden av en agentøkt:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Dette ruter automatisk på tvers av semantisk, tekst- og AST-søk for å finne relevant kode. For spesifikke symboler:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

For avhengighetsanalyse:

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

Dette er ikke bare grep-erstatninger. De er grafbevisste, semantisk indekserte, og integrert med den samme kodeintelligensen som driver agentene selv.

Samlet søk på tvers av registre

Noen ganger vet du ikke hvilket register som har svaret. Det samlede søket dekker alt:

$ orkestra search "database" --summary

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

254 treff på tvers av fem registre. Sammendraget forteller deg hvor du bør grave dypere. Fjern --summary for detaljerte resultater, eller legg til --limit 5 for å holde resultatet håndterlig.

Hvorfor dette betyr noe

Progressiv avdekking handler ikke bare om bekvemmelighet. Det endrer hvordan du samhandler med komplekse systemer.

Feilsøking blir håndterlig. Når en agent tar en uventet beslutning, grepper du ikke gjennom logger. Du sjekker hvilke verktøy den har tilgang til (agents info), hvilke beslutninger som former atferden (decisions search), og sporer implementasjonen om nødvendig (intelligent_search).

Onboarding går raskere. Nye teammedlemmer trenger ikke å lese hele kodebasen. De starter med system status, utforsker med agents list, og går dypere bare når de støter på noe de ikke forstår.

Dokumentasjonen forblir oppdatert. Fordi CLI-et leser fra de samme registrene som konfigurerer agentene, er resultatet alltid nøyaktig. Det er ingen drift mellom det dokumentasjonen sier, og det systemet faktisk gjør.

CLI-et som grensesnitt

Vi kunne ha bygget et webdashbord. Vi kunne ha skrevet omfattende dokumentasjon. I stedet bygde vi en CLI som leser fra sannhetskilden.

CLI-et har fordeler:

• Komponerbart: Pipe resultatet gjennom jq, integrer med skript
• Skriptbart: Automatiser sjekker, generer rapporter
• Raskt: Ingen sideinnlastinger, ingen autentiseringsflyt
• Nøyaktig: Leser den faktiske konfigurasjonen, ikke en mellomlagret representasjon

For systemer der korrekthet betyr mer enn estetikk, vinner CLI.

Bygg din egen progressive avdekking

Hvis du bygger agentsystemer, bør du vurdere hvordan brukere vil inspisere dem:

1. Start med helsesjekker. Én kommando som forteller deg om ting fungerer.
2. Tilby inventaroversikter. List opp hva som finnes før du forklarer hva det gjør.
3. Muliggjør målrettede spørringer. Søk slår nettlesing i stor skala.
4. Eksponer herkomst. La brukere spore beslutninger til deres opprinnelse.
5. Koble til kodeintelligens. Til slutt trenger brukere å se implementasjonen.

Hvert lag svarer på et oppfølgingsspørsmål. Bygg dem i frekvensrekkefølge — de fleste brukere stopper på nivå 2 eller 3. Bare avanserte brukere når nivå 5.

Målet er ikke å eksponere alt. Det er å eksponere nøyaktig det som trengs, nøyaktig når det trengs. Det er progressiv avdekking anvendt på agentarkitektur.