Progressive Disclosure: Jendela CLI ke Dalam Sistem Agen

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Sistem agen memang opak secara desain. Mereka membuat keputusan, memanggil tool, dan mengoordinasikan pekerjaan lintas puluhan spesialis. Tetapi ketika sesuatu berjalan salah — atau ketika Anda sekadar ingin memahami apa yang terjadi — ke mana Anda harus melihat?

Jawabannya adalah progressive disclosure: sebuah interface berlapis yang mengungkap kompleksitas tepat sebanyak yang Anda butuhkan, tepat pada saat Anda membutuhkannya.

Masalah Opasitas

Sebuah sistem orkestrasi agen modern mungkin punya:

• 40+ agen spesialis, masing-masing dengan kapabilitas yang berbeda
• 700+ skill yang merentang dari otomasi internal hingga integrasi vendor
• 470+ architectural decision yang membentuk perilaku
• Lusinan server tool MCP yang menyediakan kapabilitas eksternal

Kompleksitas ini disengaja. Agen butuh akses ke konteks yang kaya — pengetahuan domain, kecerdasan kode, skema database — untuk membuat keputusan yang baik. Tetapi kekayaan yang sama itu menciptakan masalah visibilitas.

Bagaimana Anda tahu agen mana yang menangani migrasi database? Decision apa yang membentuk perilaku peringkat sistem pencarian? Tool apa yang bisa diakses oleh architecture advisor?

Tanpa akses yang terstruktur, Anda hanya bisa membaca kode sumber atau berharap dokumentasinya masih relevan.

Progressive Disclosure sebagai Arsitektur

Progressive disclosure bukan sekadar pola UI. Ini prinsip arsitektural: organisasikan informasi dalam lapisan-lapisan, masing-masing lebih dalam dari sebelumnya, sehingga pengguna bisa berhenti pada level yang menjawab pertanyaan mereka.

Untuk sistem agen, ini diterjemahkan menjadi perintah CLI dengan kedalaman yang meningkat:

Level	Perintah	Pertanyaan yang Dijawab
1	orkestra system status	Apakah semuanya sehat?
2	orkestra agents list	Agen apa saja yang ada?
3	orkestra agents info <name>	Apa yang dilakukan agen ini?
4	orkestra decisions search	Mengapa ia bekerja dengan cara ini?
5	Tool MCP Maguyva	Tunjukkan kodenya kepada saya.

Setiap level menjawab pertanyaan lanjutan yang alami. Anda jarang perlu langsung melompat ke level 5.

Level 1: Kesehatan Sistem

Pertanyaan pertama selalu: apakah semuanya bekerja?

$ orkestra system status

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

Satu perintah. Empat angka. Cukup untuk tahu sistemnya terkonfigurasi dan registry-nya terisi.

Jika jumlah agen tiba-tiba turun atau skill gagal dimuat, Anda melihatnya di sini terlebih dahulu. Tidak perlu menyelami log.

Level 2: Inventaris Agen

Setelah Anda tahu sistemnya sehat, pertanyaan berikutnya adalah: apa saja yang tersedia?

$ orkestra agents list

Ini mengembalikan data terstruktur — nama agen, deskripsi, preferensi model, cakupan domain. Output-nya JSON secara default, sehingga mudah di-pipe ke jq untuk penyaringan:

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

Ingin agen yang menangani pekerjaan database? Perintah pencariannya mempersempit itu:

$ orkestra agents search "database"

Ini memindai nama, deskripsi, dan kapabilitas. Anda menemukan spesialis yang tepat tanpa membaca 40 definisi agen.

Level 3: Menyelami Agen Secara Mendalam

Menemukan agen yang terlihat relevan? Perintah info mengungkap segalanya:

$ orkestra agents info architecture-advisor

Output-nya mencakup:

• Metadata: Nama, kategori, preferensi model, deskripsi
• Domain: Area pengetahuan mana yang dicakup agen ini
• Identity: Sifat karakter (architect, strategist, knowledge-architect)
• Tool guide: Dokumentasi tool mana yang disuntikkan ke dalam konteks
• Tool: Daftar lengkap tool MCP yang tersedia untuk agen ini

Berikut contoh apa yang Anda lihat:

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

Ini memberi tahu Anda persis apa yang bisa dilakukan agennya. Tidak perlu kode sumber.

Level 4: Arkeologi Decision

Agen berperilaku sesuai decision yang terdokumentasi. Ketika Anda perlu memahami mengapa sesuatu bekerja dengan cara tertentu, registry decision adalah sumber kebenarannya.

$ orkestra decisions search "agent"

Ini mengembalikan architectural decision yang cocok:

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

Setiap decision punya provenance lengkap — kapan dibuat, mengapa, trade-off apa yang dipertimbangkan, commit mana yang mengimplementasikannya:

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

Ini adalah dokumentasi arsitektural yang tetap relevan karena ditambang dari commit, bukan dipelihara secara manual.

Level 5: Kecerdasan Kode Langsung

Ketika Anda perlu melihat implementasi sesungguhnya — bukan metadata tentangnya — tool MCP Maguyva menyediakan akses langsung.

Dari dalam sebuah sesi agen:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Ini secara otomatis merutekan lintas pencarian semantik, teks, dan AST untuk menemukan kode yang relevan. Untuk simbol spesifik:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Untuk analisis dependensi:

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

Ini bukan sekadar pengganti grep. Mereka sadar graf, terindeks secara semantik, dan terintegrasi dengan kecerdasan kode yang sama yang menggerakkan agen-agen itu sendiri.

Pencarian Terpadu Lintas Registry

Kadang Anda tidak tahu registry mana yang menyimpan jawabannya. Pencarian terpadu merentang ke segalanya:

$ orkestra search "database" --summary

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

254 kecocokan di lima registry. Ringkasannya memberi tahu Anda ke mana harus menyelam lebih dalam. Hapus --summary untuk hasil detail, atau tambahkan --limit 5 untuk menjaga output tetap ringkas.

Mengapa Ini Penting

Progressive disclosure bukan sekadar soal kenyamanan. Ini mengubah bagaimana Anda berinteraksi dengan sistem yang kompleks.

Debugging menjadi bisa dikelola. Ketika sebuah agen membuat keputusan yang tidak terduga, Anda tidak meng-grep lewat log. Anda memeriksa tool apa yang bisa diaksesnya (agents info), decision apa yang membentuk perilakunya (decisions search), dan menelusuri implementasinya jika perlu (intelligent_search).

Onboarding jadi lebih cepat. Anggota tim baru tidak perlu membaca seluruh basis kode. Mereka mulai dengan system status, menjelajah dengan agents list, dan menyelam lebih dalam hanya ketika mereka menjumpai sesuatu yang tidak mereka pahami.

Dokumentasi tetap relevan. Karena CLI-nya membaca dari registry yang sama yang mengonfigurasi agen-agennya, output-nya selalu akurat. Tidak ada kesenjangan antara apa yang dikatakan dokumentasi dan apa yang dilakukan sistemnya.

CLI sebagai Interface

Kami bisa saja membangun dashboard web. Kami bisa saja menulis dokumentasi yang panjang. Sebagai gantinya, kami membangun sebuah CLI yang membaca dari sumber kebenarannya.

CLI-nya punya beberapa keunggulan:

• Composable: Pipe output-nya lewat jq, integrasikan dengan script
• Scriptable: Otomasikan pemeriksaan, hasilkan laporan
• Cepat: Tidak ada page load, tidak ada alur autentikasi
• Akurat: Membaca konfigurasi sesungguhnya, bukan representasi yang di-cache

Untuk sistem tempat kebenaran lebih penting daripada estetika, CLI menang.

Membangun Progressive Disclosure Anda Sendiri

Jika Anda membangun sistem agen, pertimbangkan bagaimana pengguna akan memeriksanya:

1. Mulai dengan pemeriksaan kesehatan. Satu perintah yang memberi tahu Anda apakah semuanya bekerja.
2. Sediakan tampilan inventaris. Daftar apa yang ada sebelum menjelaskan apa yang dilakukannya.
3. Aktifkan kueri yang ditargetkan. Pencarian mengalahkan penjelajahan pada skala besar.
4. Ekspos provenance. Biarkan pengguna menelusuri decision hingga ke asalnya.
5. Sambungkan ke kecerdasan kode. Pada akhirnya, pengguna perlu melihat implementasinya.

Setiap lapisan menjawab pertanyaan lanjutan. Bangun mereka berdasarkan urutan frekuensi — sebagian besar pengguna berhenti di layer 2 atau 3. Hanya power user yang mencapai layer 5.

Tujuannya bukan mengekspos segalanya. Ini soal mengekspos tepat apa yang dibutuhkan, tepat ketika dibutuhkan. Itulah progressive disclosure yang diterapkan pada arsitektur agen.