Progressiivinen paljastaminen: CLI-ikkunat agenttijärjestelmiin

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Agenttijärjestelmät ovat suunnittelultaan läpinäkymättömiä. Ne tekevät päätöksiä, kutsuvat työkaluja ja koordinoivat työtä kymmenien erikoisosaajien yli. Mutta kun jokin menee pieleen — tai kun haluat yksinkertaisesti ymmärtää, mitä tapahtuu — mistä katsot?

Vastaus on progressiivinen paljastaminen: kerroksellinen rajapinta, joka paljastaa juuri sen verran monimutkaisuutta kuin tarvitset, juuri silloin kun tarvitset sitä.

Läpinäkymättömyysongelma

Modernissa agenttien orkestrointijärjestelmässä saattaa olla:

• 40+ erikoisosaaja-agenttia, kullakin omat kyvykkyytensä
• 700+ taitoa, jotka kattavat sisäistä automaatiota ja vendori-integraatioita
• 470+ arkkitehtonista päätöstä, jotka muokkaavat käyttäytymistä
• kymmeniä MCP-työkalupalvelimia, jotka tarjoavat ulkoisia kyvykkyyksiä

Tämä monimutkaisuus on tarkoituksellista. Agentit tarvitsevat pääsyn runsaaseen kontekstiin — toimialuetietämykseen, koodiälyyn, tietokantaskeemoihin — tehdäkseen hyviä päätöksiä. Mutta sama runsaus luo näkyvyysongelman.

Mistä tiedät, mikä agentti käsittelee tietokantamigraatioita? Mitkä päätökset muokkasivat hakujärjestelmän järjestyskäyttäytymistä? Mihin työkaluihin arkkitehtuurineuvonantajalla on pääsy?

Ilman jäsenneltyä pääsyä jäät lukemaan lähdekoodia tai toivomaan, että dokumentaatio on ajan tasalla.

Progressiivinen paljastaminen arkkitehtuurina

Progressiivinen paljastaminen ei ole pelkkä käyttöliittymämalli. Se on arkkitehtoninen periaate: järjestä tieto kerroksiin, joista jokainen on syvempi kuin edellinen, jotta käyttäjät voivat pysähtyä tasolle, joka vastaa heidän kysymykseensä.

Agenttijärjestelmille tämä tarkoittaa CLI-komentoja kasvavilla syvyystasoilla:

Taso	Komento	Kysymys, johon vastataan
1	orkestra system status	Onko kaikki kunnossa?
2	orkestra agents list	Mitä agentteja on olemassa?
3	orkestra agents info <name>	Mitä tämä agentti tekee?
4	orkestra decisions search	Miksi se toimii näin?
5	Maguyva MCP -työkalut	Näytä minulle koodi.

Jokainen taso vastaa luonnolliseen jatkokysymykseen. Harvoin tarvitsee hypätä suoraan tasolle 5.

Taso 1: järjestelmän terveys

Ensimmäinen kysymys on aina: toimiiko kaikki?

$ orkestra system status

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

Yksi komento. Neljä lukua. Tarpeeksi tietääkseen, että järjestelmä on konfiguroitu ja rekisterit täytettyjä.

Jos agenttimäärä putoaa odottamatta tai taidot eivät lataudu, näet sen täällä ensin. Ei tarvetta sukeltaa lokeihin.

Taso 2: agenttien inventaario

Kun tiedät, että järjestelmä on terve, seuraava kysymys on: mitä on saatavilla?

$ orkestra agents list

Tämä palauttaa jäsenneltyä dataa — agenttien nimet, kuvaukset, mallimieltymykset, toimialuekattavuuden. Tuloste on oletuksena JSON, mikä helpottaa sen putkittamista jq:ään suodatusta varten:

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

Haluatko agentteja, jotka käsittelevät tietokantatyötä? Hakukomento kaventaa sitä:

$ orkestra agents search "database"

Tämä skannaa nimet, kuvaukset ja kyvykkyydet. Löydät oikean erikoisosaajan lukematta 40 agenttimäärittelyä.

Taso 3: agentin syväsukellus

Löysitkö agentin, joka näyttää relevantilta? Komento info paljastaa kaiken:

$ orkestra agents info architecture-advisor

Tuloste sisältää:

• Metadata: nimi, kategoria, mallimieltymys, kuvaus
• Toimialueet: mitkä tietämysalueet tämä agentti kattaa
• Identiteetti: hahmopiirteet (arkkitehti, strategisti, tietämysarkkitehti)
• Työkaluoppaat: mikä työkaludokumentaatio ruiskutetaan kontekstiin
• Työkalut: täydellinen luettelo tälle agentille saatavilla olevista MCP-työkaluista

Tässä on näyte siitä, mitä näet:

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

Tämä kertoo tarkalleen, mitä agentti pystyy tekemään. Ei lähdekoodia tarvita.

Taso 4: päätösten arkeologia

Agentit käyttäytyvät dokumentoitujen päätösten mukaisesti. Kun sinun täytyy ymmärtää, miksi jokin toimii tietyllä tavalla, päätösrekisteri on totuuden lähde.

$ orkestra decisions search "agent"

Tämä palauttaa täsmääviä arkkitehtonisia päätöksiä:

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

Jokaisella päätöksellä on täysi alkuperä — milloin se tehtiin, miksi, mitä kompromisseja harkittiin, mitkä commitit toteuttivat sen:

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

Tämä on arkkitehtonista dokumentaatiota, joka pysyy ajan tasalla, koska se on louhittu commiteista, ei käsin ylläpidetty.

Taso 5: suora koodiäly

Kun sinun täytyy nähdä varsinainen toteutus — ei metadataa siitä — Maguyvan MCP-työkalut tarjoavat suoran pääsyn.

Agenttiistunnon sisältä:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Tämä reitittää automaattisesti semanttisen, teksti- ja AST-haun yli löytääkseen relevantin koodin. Tietyille symboleille:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Riippuvuusanalyysille:

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

Nämä eivät ole vain grep-korvikkeita. Ne ovat graafitietoisia, semanttisesti indeksoituja ja integroituja samaan koodiälyyn, joka tehostaa itse agentteja.

Yhtenäinen haku rekisterien yli

Joskus et tiedä, missä rekisterissä vastaus on. Yhtenäinen haku kattaa kaiken:

$ orkestra search "database" --summary

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

254 osumaa viiden rekisterin yli. Yhteenveto kertoo, mihin porautua. Poista --summary yksityiskohtaisia tuloksia varten, tai lisää --limit 5 pitääksesi tulosteen hallittavana.

Miksi tämä merkitsee

Progressiivinen paljastaminen ei ole vain mukavuudesta. Se muuttaa tapaa, jolla vuorovaikutat monimutkaisten järjestelmien kanssa.

Vianetsinnästä tulee hallittavaa. Kun agentti tekee odottamattoman päätöksen, et grep-hae lokeja. Tarkistat, mihin työkaluihin sillä on pääsy (agents info), mitkä päätökset muokkaavat sen käyttäytymistä (decisions search), ja jäljität toteutuksen tarvittaessa (intelligent_search).

Perehdytys nopeutuu. Uusien tiimin jäsenten ei tarvitse lukea koko koodikantaa. He aloittavat komennosta system status, tutkivat komennolla agents list ja menevät syvemmälle vasta, kun kohtaavat jotain, mitä eivät ymmärrä.

Dokumentaatio pysyy ajan tasalla. Koska CLI lukee samoista rekistereistä, jotka konfiguroivat agentit, tuloste on aina tarkka. Dokumentaation ja järjestelmän todellisen toiminnan välillä ei ole ajautumaa.

CLI rajapintana

Olisimme voineet rakentaa web-kojelaudan. Olisimme voineet kirjoittaa laajan dokumentaation. Sen sijaan rakensimme CLI:n, joka lukee totuuden lähteestä.

CLI:llä on etuja:

• Koosteltava: putkita tulostetta jq:n läpi, integroi skripteihin
• Skriptattava: automatisoi tarkistuksia, generoi raportteja
• Nopea: ei sivulatauksia, ei todennuskulkuja
• Tarkka: lukee todellisen konfiguraation, ei välimuistiin tallennettua esitystä

Järjestelmille, joissa oikeellisuus merkitsee enemmän kuin estetiikka, CLI voittaa.

Oman progressiivisen paljastamisen rakentaminen

Jos rakennat agenttijärjestelmiä, harkitse, miten käyttäjät tarkastelevat niitä:

1. Aloita terveystarkistuksista. Yksi komento, joka kertoo, toimivatko asiat.
2. Tarjoa inventaarionäkymät. Listaa, mitä on olemassa, ennen kuin selität, mitä se tekee.
3. Mahdollista kohdennetut kyselyt. Haku voittaa selailun laajassa mittakaavassa.
4. Paljasta alkuperä. Anna käyttäjien jäljittää päätökset alkuperäänsä.
5. Yhdistä koodiälyyn. Lopulta käyttäjien täytyy nähdä toteutus.

Jokainen kerros vastaa jatkokysymykseen. Rakenna ne yleisyysjärjestyksessä — useimmat käyttäjät pysähtyvät tasolle 2 tai 3. Vain tehokäyttäjät saavuttavat tason 5.

Tavoite ei ole paljastaa kaikkea. Se on paljastaa juuri se, mitä tarvitaan, juuri silloin kun sitä tarvitaan. Se on progressiivinen paljastaminen sovellettuna agenttiarkkitehtuuriin.