Kademeli Açığa Çıkarma: Ajan Sistemlerine CLI Pencereleri

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Ajan sistemleri tasarım gereği opaktır. Karar verirler, araçları çağırırlar ve düzinelerce uzman genelinde işi koordine ederler. Ama bir şeyler ters gittiğinde — ya da sadece neler olduğunu anlamak istediğinizde — nereye bakarsınız?

Yanıt kademeli açığa çıkarmadır: tam olarak ihtiyacınız kadar karmaşıklığı, tam olarak ihtiyaç duyduğunuz anda ortaya çıkaran katmanlı bir arayüz.

Opaklık Sorunu

Modern bir ajan orkestrasyon sistemi şunlara sahip olabilir:

• Her biri farklı yeteneklere sahip 40’tan fazla uzman ajan
• İç otomasyonu ve tedarikçi entegrasyonlarını kapsayan 700’den fazla beceri
• Davranışı şekillendiren 470’ten fazla mimari karar
• Dış yetenekler sağlayan düzinelerce MCP araç sunucusu

Bu karmaşıklık kasıtlıdır. Ajanların iyi kararlar vermek için zengin bağlama — alan bilgisi, kod zekâsı, veritabanı şemaları — erişmesi gerekir. Ama aynı zenginlik bir görünürlük sorunu yaratır.

Hangi ajanın veritabanı geçişlerini ele aldığını nasıl bilirsiniz? Hangi kararlar arama sisteminin sıralama davranışını şekillendirdi? Mimari danışmanının hangi araçlara erişimi var?

Yapılandırılmış erişim olmadan, ya kaynak kodu okumak zorunda kalırsınız ya da dokümantasyonun güncel olmasını ummak zorunda kalırsınız.

Mimari Olarak Kademeli Açığa Çıkarma

Kademeli açığa çıkarma sadece bir arayüz deseni değildir. Bir mimari ilkedir: bilgiyi katmanlar hâlinde, her biri bir öncekinden daha derin olacak şekilde düzenleyin, böylece kullanıcılar sorularını yanıtlayan seviyede durabilir.

Ajan sistemleri için bu, artan derinliklerdeki CLI komutlarına dönüşür:

Seviye	Komut	Yanıtlanan Soru
1	orkestra system status	Her şey sağlıklı mı?
2	orkestra agents list	Hangi ajanlar var?
3	orkestra agents info <name>	Bu ajan ne yapıyor?
4	orkestra decisions search	Neden bu şekilde çalışıyor?
5	Maguyva MCP araçları	Bana kodu göster.

Her seviye doğal bir takip sorusunu yanıtlar. Nadiren doğrudan 5. seviyeye atlamanız gerekir.

Seviye 1: Sistem Sağlığı

İlk soru her zaman şudur: her şey çalışıyor mu?

$ orkestra system status

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

Tek bir komut. Dört sayı. Sistemin yapılandırıldığını ve kayıt defterlerinin doldurulduğunu bilmek için yeterli.

Bir ajan sayısı beklenmedik şekilde düşerse veya beceriler yüklenemezse, bunu önce burada görürsünüz. Günlüklere dalmak gerekmez.

Seviye 2: Ajan Envanteri

Sistemin sağlıklı olduğunu bildikten sonra, bir sonraki soru şudur: neler mevcut?

$ orkestra agents list

Bu, yapılandırılmış veri döndürür — ajan adları, açıklamalar, model tercihleri, alan kapsamı. Çıktı varsayılan olarak JSON’dur, bu da filtreleme için jq’e yönlendirmeyi kolaylaştırır:

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

Veritabanı işini ele alan ajanlar mı istiyorsunuz? Arama komutu bunu daraltır:

$ orkestra agents search "database"

Bu, adları, açıklamaları ve yetenekleri tarar. 40 ajan tanımını okumadan doğru uzmanı bulursunuz.

Seviye 3: Ajan Derinlemesine İnceleme

İlgili görünen bir ajan mı buldunuz? info komutu her şeyi ortaya çıkarır:

$ orkestra agents info architecture-advisor

Çıktı şunları içerir:

• Meta veri: Ad, kategori, model tercihi, açıklama
• Alanlar: Bu ajanın hangi bilgi alanlarını kapsadığı
• Kimlik: Karakter özellikleri (mimar, stratejist, bilgi mimarı)
• Araç kılavuzları: Bağlama hangi araç dokümantasyonunun enjekte edildiği
• Araçlar: Bu ajana açık olan MCP araçlarının tam listesi

İşte gördüklerinizin bir örneği:

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

Bu, ajanın tam olarak ne yapabileceğini size söyler. Kaynak kod gerekmez.

Seviye 4: Karar Arkeolojisi

Ajanlar, belgelenmiş kararlara göre davranır. Bir şeyin belirli bir şekilde neden çalıştığını anlamanız gerektiğinde, kararlar kayıt defteri gerçek kaynaktır.

$ orkestra decisions search "agent"

Bu, eşleşen mimari kararları döndürür:

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

Her kararın tam bir kökeni vardır — ne zaman alındığı, nedeni, hangi ödünleşimlerin göz önünde bulundurulduğu, hangi commit’lerin onu uyguladığı:

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

Bu, commit’lerden madenlendiği için güncel kalan, elle sürdürülmeyen mimari dokümantasyondur.

Seviye 5: Doğrudan Kod Zekâsı

Gerçek uygulamayı — hakkındaki meta veriyi değil — görmeniz gerektiğinde, Maguyva’nın MCP araçları doğrudan erişim sağlar.

Bir ajan oturumu içinden:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Bu, ilgili kodu bulmak için semantik, metin ve AST araması genelinde otomatik yönlendirme yapar. Belirli semboller için:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Bağımlılık analizi için:

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

Bunlar sadece grep yerine geçenler değildir. Graf bilincine sahiptirler, semantik olarak indekslenmişlerdir ve ajanların kendisine güç veren aynı kod zekâsıyla entegredirler.

Kayıt Defterleri Genelinde Birleşik Arama

Bazen hangi kayıt defterinin yanıtı tuttuğunu bilmezsiniz. Birleşik arama her şeyi kapsar:

$ orkestra search "database" --summary

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

Beş kayıt defteri genelinde 254 eşleşme. Özet size nereye derinlemesine ineceğinizi söyler. Ayrıntılı sonuçlar için --summary’yı kaldırın, ya da çıktıyı yönetilebilir tutmak için --limit 5 ekleyin.

Bunun Neden Önemli Olduğu

Kademeli açığa çıkarma sadece kolaylıkla ilgili değildir. Karmaşık sistemlerle nasıl etkileşim kurduğunuzu değiştirir.

Hata ayıklama yönetilebilir hâle gelir. Bir ajan beklenmedik bir karar verdiğinde, günlüklerde grep yapmazsınız. Hangi araçlara erişimi olduğunu (agents info), hangi kararların davranışını şekillendirdiğini (decisions search) kontrol edersiniz ve gerekirse uygulamayı izlersiniz (intelligent_search).

Katılım hızlanır. Yeni ekip üyelerinin tüm kod tabanını okumasına gerek yoktur. system status ile başlarlar, agents list ile keşfederler ve yalnızca anlamadıkları bir şeyle karşılaştıklarında daha derine inerler.

Dokümantasyon güncel kalır. CLI, ajanları yapılandıran aynı kayıt defterlerinden okuduğu için, çıktı her zaman doğrudur. Dokümanların söylediği ile sistemin yaptığı arasında sapma olmaz.

Arayüz Olarak CLI

Bir web gösterge paneli inşa edebilirdik. Kapsamlı dokümantasyon yazabilirdik. Bunun yerine, gerçek kaynaktan okuyan bir CLI inşa ettik.

CLI’nin avantajları vardır:

• Bileşilebilir: Çıktıyı jq üzerinden aktarın, betiklerle entegre edin
• Betiklenebilir: Kontrolleri otomatikleştirin, raporlar üretin
• Hızlı: Sayfa yüklemesi yok, kimlik doğrulama akışı yok
• Doğru: Önbelleğe alınmış bir temsili değil, gerçek yapılandırmayı okur

Doğruluğun estetikten daha önemli olduğu sistemler için CLI kazanır.

Kendi Kademeli Açığa Çıkarmanızı İnşa Etmek

Ajan sistemleri inşa ediyorsanız, kullanıcıların bunları nasıl inceleyeceğini düşünün:

1. Sağlık kontrolleriyle başlayın. Her şeyin çalışıp çalışmadığını söyleyen tek bir komut.
2. Envanter görünümleri sağlayın. Ne yaptığını açıklamadan önce nelerin var olduğunu listeleyin.
3. Hedeflenmiş sorguları etkinleştirin. Ölçekte arama, göz atmayı yener.
4. Kökeni açığa çıkarın. Kullanıcıların kararları kökenlerine kadar izlemesine izin verin.
5. Kod zekâsına bağlanın. Sonunda, kullanıcıların uygulamayı görmesi gerekir.

Her katman bir takip sorusunu yanıtlar. Bunları sıklık sırasına göre inşa edin — çoğu kullanıcı 2. veya 3. katmanda durur. Yalnızca güçlü kullanıcılar 5. katmana ulaşır.

Amaç her şeyi açığa çıkarmak değildir. Amaç, tam olarak ihtiyaç duyulanı, tam olarak ihtiyaç duyulduğu anda açığa çıkarmaktır. Ajan mimarisine uygulanan kademeli açığa çıkarma budur.