agent-loop-guard: Yapay Zeka Ajanlarında Sonsuz Döngü ve Kontrolsüz Çalışmayı Engelleyen Güvenlik Kütüphanesi

Otonom yapay zeka ajanları (AI Agents), kendilerine verilen hedeflere ulaşmak için LLM çıktılarından faydalanarak dinamik araçlar (tools) çağırır ve çok adımlı karar zincirleri yürütür. Ancak bu süreçte modeller; yetersiz bağlam, belirsiz araç çıktıları veya mantıksal çıkmazlar nedeniyle aynı fonksiyonu sürekli tekrarlayabilir, birbirini tetikleyen döngülere girebilir veya kontrolsüz bir şekilde çalışmayı sürdürebilir (runaway loop). Bu durum hem dakikalar içinde fırlayan API maliyetlerine hem de uygulamanın kilitlenmesine neden olur.

OMD-123/agent-loop-guard, yapay zeka ajanlarını bu tür kontrolsüz yürütmelerden korumak için geliştirilmiş, harici hiçbir bağımlılığı olmayan (zero-dependency), model ve platform sağlayıcısından bağımsız (provider-independent) ve TypeScript öncelikli hafif bir güvenlik kütüphanesidir.

Neden Önemli ve Geliştiriciler İçin Değeri Ne?#

Üretim (production) ortamında çalışan otonom sistemlerde deterministik güvenlik katmanları oluşturmak kritik bir gereksinimdir. agent-loop-guard, geliştiricilere şu temel avantajları sunar:

• Maliyet ve Kota Koruması: Beklenmeyen sonsuz döngüleri ve aşırı token tüketimini ilk adımlarda tespit ederek API bütçesinin tükenmesini önler.
• Tekrarlayan Araç Çağrısı Tespiti: Ajanın aynı parametrelerle veya sonuç alamadığı kalıplarla aynı aracı art arda çağırmasını (repeated tool calls) engeller.
• Sıfır Bağımlılık ve Yüksek Performans: Projenize harici paket yükü bindirmez, ek gecikme (latency) oluşturmaz ve Node.js, Deno, Bun veya Edge çalışma ortamlarında sorunsuz çalışır.
• Sağlayıcı Bağımsızlığı: OpenAI, Anthropic, Gemini, açık kaynaklı yerel modeller veya özel ajan mimarileriyle doğrudan entegre edilebilir.

Pratik Kullanım Örneği#

Kütüphane, ajanın işlem adımlarını ve araç çağrı imzalarını kaydederek döngü anomalilerini anlık olarak analiz eder:

import { LoopGuard } from 'agent-loop-guard';

// Güvenlik kurallarını ve limitleri tanımlayın
const guard = new LoopGuard({
  maxTotalSteps: 15,
  maxConsecutiveSameToolCalls: 3,
  detectArgumentRepetition: true,
});

async function runAgent(userPrompt: string) {
  while (true) {
    const action = await llm.determineNextAction(userPrompt);

    // Her döngü adımında çağrıyı denetleyin
    const check = guard.recordStep({
      toolName: action.tool,
      args: action.parameters,
    });

    if (check.isLoopDetected) {
      console.warn(`Ajan durduruldu: ${check.reason}`);
      return { error: 'Döngü tespit edildi', details: check.reason };
    }

    const result = await executeTool(action.tool, action.parameters);
    if (result.isComplete) break;
  }
}

Benzer Çözümlerle Karşılaştırma#

• Basit Sayaçlar (while döngüsü limitleri): Yalnızca toplam adım sayısını sınırlar; ajanın 3. adımda aynı araca takılıp kalmasını veya iki araç arasında kısır döngüye girmesini yakalayamaz.
• Ağır Güvenlik Çatıları (Guardrails AI, NeMo): Kapsamlıdır ancak projeye büyük bağımlılıklar ekler, kurulumu zahmetlidir ve ek işlem maliyeti doğurur.
• agent-loop-guard: Yalnızca döngü ve yürütme güvenliğine odaklanır; hafif, hızlı, esnek ve projenize dakikalar içinde entegre edilebilen odaklı bir koruma sağlar.

Orijinal repoya buradan ulaşabilirsiniz.