OpenClaw ile Çoklu Aracı Düzenleme Desenleri

Tek bir yapay zeka aracısı bir süreci otomatikleştirebilir. İyi organize edilmiş bir temsilci sistemi, bir iş fonksiyonunu otomatikleştirebilir. Aradaki fark, temsilcilerin sınırlar ötesindeki hataları nasıl koordine ettiği, iletişim kurduğu ve ele aldığında yatmaktadır. Çoklu aracı orkestrasyonu, bağımsız botlardan oluşan bir koleksiyon ile tutarlı, güvenilir bir otonom sistem arasındaki farkı yaratan mühendislik disiplinidir.

OpenClaw, çoklu aracı orkestrasyonu için temel unsurları sağlar: yazılı bir mesaj veri yolu, bir aracı kaydı, aktarım protokolleri, paylaşılan bellek ad alanları ve aracı sınırları boyunca istekleri takip eden dağıtılmış izleme. Bu kılavuz dört temel düzenleme modelini, her birinin ne zaman kullanılacağını, bunların OpenClaw'da nasıl uygulanacağını ve tasarımda kullanılacak hata modlarını kapsar.

Önemli Çıkarımlar

• Denetçi-Çalışan modeli en yaygın mimaridir: bir düzenleme aracısı hedefleri ayrıştırır ve uzman çalışanları görevlendirir.
• Pipeline modeli, her aşamanın bir sonraki aşama için girdi ürettiği sıralı belge işleme veya çok adımlı veri dönüşümü için en iyisidir.
• Konsensüs modeli, birden fazla bağımsız temsilcinin aynı soruyu değerlendirmesine olanak tanıyarak, riskli kararlarda tek temsilcinin hata yapma riskini azaltır.
• Market-Maker modeli, görevleri mevcut en yetenekli aracıya dinamik olarak tahsis ederek yük dengelemeyi ve zarif bir bozulmayı mümkün kılar.
• Temsilciler arası iletişim, OpenClaw'ın yazılı Mesaj Veriyolunu kullanır; ham dize geçişi yoktur, aracılar arasında paylaşılan değiştirilebilir durum yoktur.
• Dağıtılmış izleme, çok aracılı hata ayıklama için gereklidir; her mesaj, aracı sınırlarını kapsayan bir korelasyon kimliği taşır.
• Ajan sınırındaki devre kesiciler, sistemdeki bir ajan kullanılamaz hale geldiğinde kademeli arızaları önler.
• ECOSIRE, karmaşık kurumsal otomasyon iş akışları için çok aracılı mimariler tasarlar ve uygular.

---

Temel: OpenClaw'ın Temsilci İletişim Modeli

Kalıpları ele almadan önce OpenClaw aracılarının nasıl iletişim kurduğunu anlamak önemlidir. Her biri farklı değiş tokuşlara sahip üç mekanizma vardır:

Mesaj Veri Yolu aynı sistemdeki aracılar arasındaki birincil iletişim kanalıdır. Aracılar, yazılan mesajları adlandırılmış kanallara yayınlar; diğer temsilciler bu kanallara abone olur. Mesajlar veri yolu aracısı (Redis Streams veya Kafka, yapılandırılabilir) tarafından kalıcı hale getirilir, böylece alıcı aracı geçici olarak kullanılamadığında mesajlar kaybolmaz.

Doğrudan Çağırma, bir aracının başka bir aracının açığa çıkan becerilerini doğrudan çağırmasına ve yanıt beklemesine olanak tanır. Bu, arayanın bakış açısından eşzamanlıdır ve arayan aracının sonuca ulaşana kadar ilerleyemeyeceği düşük gecikmeli iş akışları için uygundur. Dikkatli kullanın; ajanlar arasında sıkı bir bağlantı oluşturur.

Paylaşılan Bellek Ad Alanları, aynı sistemdeki aracıların bellek deposunun paylaşılan bir bölgesinden okumasına ve bu bölgeye yazmasına olanak tanır. Bu, büyük bağlam nesnelerinin (işlenmekte olan bir belge, aşamalar boyunca zenginleştirilen bir müşteri profili) mesaj yükleri aracılığıyla serileştirilmeden geçirilmesi için uygundur.

// Publishing a message
await messageBus.publish("document.classified", {
  documentId: "DOC-4521",
  type: "vendor-invoice",
  confidence: 0.94,
  storageKey: "incoming/doc-4521.pdf",
});

// Subscribing to messages
messageBus.subscribe("document.classified", async (message) => {
  await extractionAgent.handle(message);
});

Tüm iletiler bir korelasyon kimliğini, zaman damgasını, kaynak aracı kimliğini ve şema sürümünü içerir. Şema sürümü, mesaj veri yolunun mesajları beyan edilen sözleşmeye göre doğrulamasına ve hatalı biçimlendirilmiş mesajları alıcı aracıya ulaşmadan önce reddetmesine olanak tanır.

---

Desen 1: Amir-İşçi

Denetleyici-Çalışan modeli, en yaygın olarak uygulanabilir çoklu aracı mimarisidir. Bir Denetleyici temsilcisi, üst düzey hedefi alır, onu alt görevlere ayırır, her bir alt görevi uzman bir Çalışan temsilcisine atar, ilerlemeyi izler ve sonuçları sentezler.

User/System Goal
      ↓
[ Supervisor Agent ]
  ├─ task 1 → [ Worker Agent A ]
  ├─ task 2 → [ Worker Agent B ]
  └─ task 3 → [ Worker Agent C ]
      ↓
[ Supervisor Agent ] ← results from all workers
      ↓
Synthesized Response

Ne zaman kullanılır: Karmaşık bir hedef, heterojen uzmanlık gerektirdiğinde. Süpervizör koordinasyon mantığını yönetir; çalışanlar bir şeyi iyi yapan alan uzmanlarıdır.

OpenClaw uygulaması:

export const SupervisorAgent = defineAgent({
  name: "due-diligence-supervisor",
  skills: ["decompose-goal", "assign-workers", "synthesize-results"],
  async run({ goal, workerRegistry, messageBus }) {
    // Decompose goal into tasks
    const tasks = await decomposeGoal(goal);

    // Assign to appropriate workers
    const assignments = tasks.map((task) => ({
      task,
      worker: workerRegistry.findBestMatch(task.type),
    }));

    // Publish tasks and wait for results
    const results = await Promise.allSettled(
      assignments.map(({ task, worker }) =>
        messageBus.requestReply(`worker.${worker.id}.tasks`, task, { timeoutMs: 60_000 })
      )
    );

    // Synthesize
    const successfulResults = results
      .filter((r) => r.status === "fulfilled")
      .map((r) => r.value);

    return synthesize(goal, successfulResults);
  },
});

Önemli tasarım kararları:

• Denetleyici, etki alanı mantığını içermemelidir; yalnızca koordine etmelidir.
• Çalışanlar vatansız ve bağımsız olarak ölçeklenebilir olmalıdır.
• Başarısız olan işçi görevleri, çalışan tarafından değil, amir tarafından yeniden denenir.
• Yönetici seviyesindeki görev zaman aşımları, yavaş bir çalışanın tüm iş akışını engellemesini önler.

Gerçek dünyadan örnek: Süpervizörün bir şirket incelemesini Mali Analiz Çalışanına, Yasal Belge İnceleme Çalışanına, Pazar Araştırması Çalışanına ve Referans Kontrol Çalışanına atanan paralel görevlere ayırdığı durum tespiti otomasyon sistemi. Denetim otoritesi tüm bulguları birleşik bir durum tespiti raporunda birleştirir.

---

Desen 2: Boru Hattı

Pipeline modeli, aracıları, her aracının çıktısının bir sonraki aracının girdisi olacağı şekilde sıralar. Belge işleme, veri zenginleştirme ve her adımın yükü belirli bir sırayla dönüştürdüğü veya zenginleştirdiği tüm iş akışları için idealdir.

Input Document
    ↓
[ Stage 1: Ingestion Agent ]
    ↓
[ Stage 2: Classification Agent ]
    ↓
[ Stage 3: Extraction Agent ]
    ↓
[ Stage 4: Validation Agent ]
    ↓
[ Stage 5: Integration Agent ]
    ↓
Output: ERP Record

Ne zaman kullanılmalı: Net aşama sınırları ve her adımda dönüşüm içeren sıralı iş akışları. Yüksek verimli belge işleme için mükemmeldir.

OpenClaw uygulaması:

OpenClaw'ın Pipeline primitifi, aşama zincirini yönetir, arızaları yönetir ve yük içeriğine bağlı olarak herhangi bir aşamada dallanmayı destekler.

import { definePipeline } from "@openclaw/orchestration";

export const InvoicePipeline = definePipeline({
  name: "invoice-processing",
  stages: [
    { agent: "document-ingester", timeout: 30_000 },
    {
      agent: "document-classifier",
      timeout: 15_000,
      branch: {
        "vendor-invoice": "invoice-extractor",
        "credit-memo": "credit-memo-extractor",
        "unknown": "human-review-queue", // Branch to exception handling
      },
    },
    { agent: "invoice-validator", timeout: 20_000 },
    { agent: "invoice-enricher", timeout: 10_000 },
    { agent: "erp-integrator", timeout: 30_000, retries: 3 },
  ],
  onFailure: {
    agent: "exception-handler",
    preservePartialState: true,
  },
});

Önemli tasarım kararları:

• Her aşama idempotent olmalıdır; eğer aynı girdiyle iki kez çalışırsa aynı çıktıyı üretir.
• onFailure işleyicisi kısmi işlem hattı durumunu alır, böylece baştan başlamak yerine son başarılı aşamadan devam edebilir.
• Dallanma, farklı belge türlerinin sınıflandırma sonrasında farklı alt hatları takip etmesine olanak tanır.
• Büyük yükleri (belge arabellekleri) ileti veri yolu aracılığıyla serileştirmek yerine aşamalar arasında geçirmek için paylaşılan bellek ad alanını kullanın.

Hata yönetimi: M başarılı aşamadan sonra N aşaması başarısız olduğunda, işlem hattı durumu M aşamasında kontrol noktasına alınır. Arıza çözümlendikten sonra (manuel düzeltme, bağımlılık kurtarıldıktan sonra yeniden deneme), işlem hattı aynı yük ile M+1 aşamasından devam eder.

---

Desen 3: Fikir Birliği

Consensus modeli, birden fazla bağımsız aracıyı aynı girdiye karşı çalıştırır ve sistem harekete geçmeden önce bunların (bir eşik dahilinde) anlaşmasını gerektirir. İkinci görüşün çok temsilcili eşdeğeridir ve tek temsilci hatasının maliyetli olacağı yüksek riskli kararlarda en değerlidir.

Input
  ├─ → [ Evaluator Agent A ] → assessment A
  ├─ → [ Evaluator Agent B ] → assessment B
  └─ → [ Evaluator Agent C ] → assessment C
          ↓
  [ Consensus Resolver ]
    ├── unanimous or majority? → act
    └── no consensus? → escalate to human

Ne zaman kullanılmalı: Yüksek riskli kararlar (kredi onayları, dolandırıcılık tespiti, tıbbi kayıt analizi, sözleşme maddesi incelemesi), tek bir aracının manipüle edilebileceği rakip girdiler veya farklı modellerin tamamlayıcı güçlere sahip olduğu durumlar.

OpenClaw uygulaması:

export const FraudConsensusCheck = defineAgent({
  name: "fraud-consensus",
  async run({ transaction, evaluators }) {
    // Run all evaluators in parallel
    const assessments = await Promise.all(
      evaluators.map((evaluator) =>
        evaluator.assess(transaction)
      )
    );

    const fraudVotes = assessments.filter((a) => a.isFraud).length;
    const totalVotes = assessments.length;
    const agreementRatio = fraudVotes / totalVotes;

    if (agreementRatio >= 0.67) { // Supermajority fraud detection
      return { decision: "block", confidence: agreementRatio, assessments };
    } else if (agreementRatio === 0) { // Unanimous clear
      return { decision: "allow", confidence: 1 - agreementRatio, assessments };
    } else {
      // Disagreement — escalate with all assessments for human review
      return { decision: "escalate", confidence: null, assessments };
    }
  },
});

Önemli tasarım kararları:

• Değerlendirici temsilcileri, ilişkili hataları en aza indirmek için farklı modeller veya farklı yönlendirme stratejileri kullanmalıdır. Aynı modeli aynı istemle kullanan iki aracı genellikle aynı fikirde olacaktır; bu da amacı boşa çıkarmaktadır.
• Konsensüs eşiği yapılandırılabilir. Geri dönüşü olmayan eylemlerde oybirliğiyle anlaşma uygundur; Geri alınabilecek kararlar için basit çoğunluk yeterlidir.
• Yükseltme yollarının kapasite planlaması gerekir; yükseltme oranınız yüksekse değerlendirici kriterlerinin ayarlanması gerekir.

---

Model 4: Piyasa Yapıcı

Market-Maker modeli, Çalışan temsilcilerinden oluşan bir havuz sağlar ve görevleri, görev geldiğinde mevcut en uygun çalışana dinamik olarak tahsis eder. İşçiler yeteneklerini ve mevcut yüklerini kaydederler; Piyasa Yapıcı her görevi en iyi eşleşmeye yönlendirir.

Task Queue
    ↓
[ Market-Maker Agent ]
    ├── Worker A: [language-translation] load: 30%
    ├── Worker B: [language-translation] load: 80%
    └── Worker C: [language-translation] load: 10%  ← assigned

Ne zaman kullanılmalı: Görev hacminin önemli ölçüde değişiklik gösterdiği yüksek verimli sistemler. Yönlendirme mantığını değiştirmeden çalışan aracılarının yatay ölçeklendirilmesine olanak tanır. Aynı zamanda zarif bir bozulmaya da olanak tanır; eğer uzman bir çalışan mevcut değilse, Piyasa Yapıcı, görevde başarısız olmak yerine daha düşük performansa sahip genel bir çalışana yönlendirebilir.

export const TranslationMarketMaker = defineAgent({
  name: "translation-market-maker",
  tools: ["worker-registry", "task-queue"],
  async run({ tools }) {
    while (true) {
      const task = await tools.taskQueue.dequeue("translation.pending");
      if (!task) { await sleep(100); continue; }

      const workers = await tools.workerRegistry.getAvailable({
        capability: "language-translation",
        targetLanguage: task.targetLanguage,
      });

      if (workers.length === 0) {
        // No specialist available — try generalist
        const generalists = await tools.workerRegistry.getAvailable({ capability: "general-translation" });
        if (generalists.length === 0) {
          await tools.taskQueue.requeueWithDelay(task, { delayMs: 5000 });
          continue;
        }
        workers.push(...generalists);
      }

      // Select worker with lowest load
      const selected = workers.sort((a, b) => a.currentLoad - b.currentLoad)[0];
      await selected.dispatch(task);
    }
  },
});

Önemli tasarım kararları:

• Çalışan yükü raporlaması doğru ve düşük gecikmeli olmalıdır. Eski yük verileri eşit olmayan dağılıma yol açar.
• Geri dönüş zinciri (uzman → genel → gecikmeli kuyruk) kapasite eksiklikleri sırasında görev kaybını önler.
• Çalışanlar başlangıçta kendi kendilerine kaydolur ve otomatik kapatma durumunda kayıtlarını siler. Sağlık kontrolü yoklaması, kaza yapan çalışanları otomatik olarak ortadan kaldırır.

---

Çapraz Desen: Dağıtılmış İzleme

Hangi orkestrasyon modelini kullanırsanız kullanın, üretimdeki çok aracılı sistemler için dağıtılmış izleme tartışılamaz. Her mesaj bir correlationId ve bir spanId taşır. Bir aracı bir alt görev oluşturduğunda (Süpervizör modelinde) veya işi bir sonraki aşamaya (Boru Hattı modelinde) aktardığında, geçerli yayılma alanının alt öğesi olarak yeni bir yayılma oluşturur.

// Middleware that injects tracing into all agent message handlers
agent.useHook("preRun", (ctx) => {
  ctx.span = tracer.startSpan(ctx.skill, { childOf: ctx.message.parentSpan });
  ctx.span.setTag("agent.id", ctx.agentId);
  ctx.span.setTag("correlation.id", ctx.message.correlationId);
});

agent.useHook("postRun", (ctx) => {
  ctx.span.finish();
});

Dağıtılmış izlemeyle, tüm aracı sınırlarında herhangi bir görev için yürütme ağacının tamamını görselleştirebilirsiniz; bu, gecikme sorunları ve beklenmedik davranışlarda hata ayıklamak için çok değerlidir.

---

Kaçınılması Gereken Anti-Desenler

Paylaşılan değiştirilebilir durum: Birden fazla aracının aynı veri deposu kaydına koordinasyon olmadan yazması, güncellemelerin ve yarış koşullarının kaybolmasına neden olur. Koordinasyon için mesaj veriyolunu kullanın; ajanlar kendi devletlerine sahiptirler.

Üç ajandan daha uzun senkronize zincirler: A ajanı B'yi ararsa, C'yi çağırırsa ve D'yi eşzamanlı olarak çağırırsa, gecikme bileşikleri ve arıza patlama yarıçapı büyüktür. Uzun eşzamanlı zincirleri denetim noktası oluşturmayla eşzamansız ardışık düzen aşamalarına bölün.

Etki alanı mantığına sahip denetleyici aracılar: Denetleyiciler etki alanı işini yürütmemeli, düzenlemelidir. Bir denetçi, çıkarma mantığını veya doğrulama kurallarını içermeye başladığında, kılık değiştirmiş bir monolit haline gelir.

Aracılar arasındaki örtülü sözleşmeler: Mesaj şemalarının veri yolu düzeyinde sürümü oluşturulmalı ve doğrulanmalıdır. Mesaj yapısını doğrulamak yerine üstlenen aracılar, gönderen çıkış formatını değiştirdiğinde sessizce başarısız olur.

---

Sıkça Sorulan Sorular

Bazı çalışanların başarılı, bazılarının ise başarısız olduğu bir Yönetici-İşçi sisteminde kısmi başarısızlıklarla nasıl başa çıkıyorsunuz?

Süpervizör, tüm çalışan görevlerinin sonuçlarını başarı ve başarısızlıkların bir karışımı olarak alır. Sentez becerisi hedefe dayalı kısmi sonuçların nasıl ele alınacağına karar verir: bazı hedefler için kısmi sonuçlar yararlı bir çıktı üretmek için yeterlidir; diğerleri için tüm sonuçlar gereklidir. Süpervizörü minimum başarı eşiğiyle yapılandırın; eğer bu orandan daha az sayıda çalışan başarılı olursa, potansiyel olarak yanıltıcı bir kısmi çıktı üretmek yerine durumu tırmandırın.

Aynı aracı aynı anda birden fazla düzenleme modeline katılabilir mi?

Evet. Bir temsilci yalnızca bir hizmettir; bir Süpervizör-İşçi sisteminde Çalışan olabilir, aynı zamanda bir Boru Hattında Aşama olabilir ve Konsensüs kontrolünde Değerlendirici olarak yer alabilir. Her çağrı bağımsızdır. Kritik gereksinim, aracıların çağrılar arasında durumsuz olmasıdır (durum bilgisi olan veriler, aracı örnek değişkenlerine değil, bellek depolarına gider), böylece birden fazla eşzamanlı çağrının müdahale etmemesidir.

Yüksek verimli sistemler için mesaj veriyolunun yükü nedir?

İleti veri yolu arka ucu olarak Redis Streams kullanıldığında, ileti yayınlama/abone olma gecikmesi, 64 KB'nin altındaki iletiler için genellikle 2 ms'nin altındadır. Dakikada binlerce belgeyi işleyen yüksek verimli işlem hatları için bu, her aşamadaki işleme çalışmasıyla karşılaştırıldığında ihmal edilebilir düzeydedir. Son derece yüksek aktarım hızına sahip sistemler için (günde milyonlarca mesaj), Kafka, daha yüksek operasyonel karmaşıklık pahasına daha yüksek sürdürülebilir aktarım hızı sağlar.

Bireysel aracılar geliştikçe çoklu aracılı sistemleri nasıl versiyonlarsınız?

Sürüm aracıları, bildirimlerinde anlamsal sürüm oluşturmayı bağımsız olarak kullanır. Mesaj veri yolu, mesajları bildirilen şema sürümüne göre doğrular. Bir aracı çıktı şemasını değiştirdiğinde (değişikliği bozar), ana sürümü yükseltir ve veri yolu eski şema mesajlarını önceki sürüme yönlendirir. Geçiş penceresi sırasında her iki sürüm de aynı anda çalışır. Denetleyici veya İşlem Hattı yapılandırması, her bir çalışanın hangi sürümünün gerekli olduğunu belirterek, kullanıma sunma zamanlaması üzerinde tam kontrol sahibi olmanızı sağlar.

Görevlerin bağımlılıkları olduğunda Market-Maker modeli görev sıralamasını nasıl ele alır?

Piyasa Yapıcı bağımsız görevler (herhangi bir sırayla yürütülebilen görevler) için uygundur. Bağımlılıkları olan görevler için bunun yerine siparişi açıkça zorunlu kılan İşlem Hattı veya Denetleyici modelini kullanın. Bağımsız ve bağımlı görevlerin bir karışımına sahipseniz, Süpervizör modeli iyi çalışır: Süpervizör, Market-Maker havuzuna bağımsız görevler gönderir ve geri kalanı için bağımlılık sıralamasını yönetir.

---

Sonraki Adımlar

Çoklu aracı orkestrasyonu, tek aracıların başa çıkamayacağı otomasyon karmaşıklığının kilidini açar. Bu kılavuzdaki modeller (Süpervizör-Çalışan, Boru Hattı, Konsensus ve Pazar Yapıcı) kurumsal otomasyon kullanım durumlarının büyük çoğunluğunu kapsamaktadır. Önemli olan, her sorunu tek bir mimariye zorlamak değil, sorunun iletişim yapısı için doğru modeli seçmektir.

ECOSIRE'ın OpenClaw çok aracılı düzenleme hizmeti, karmaşık çok aracılı sistemler için mimari tasarım, uygulama ve sürekli optimizasyon sağlar. Ekibimiz, ayda milyonlarca belgeyi işleyen belge işleme sistemleri, 7/24 çalışan mali analiz hatları ve bir düzine uzman temsilci arasında koordinasyon sağlayan İK otomasyon sistemleri için orkestrasyon mimarileri tasarladı.

Çoklu aracı mimarisi gereksinimlerinizi görüşmek için ECOSIRE ile iletişime geçin.