İstek limitleri & maliyet tavanı

Bir çalıştırma kontrolden çıkabilir — pahalı bir model döngüsü, kaçak bir araç-çağrısı zinciri, bütçelemediğiniz bir maliyet. RunLimits, birikimli token'lara, birikimli USD maliyetine ve araç çağrısı sayısına bir tavan koyar, aynı anda yürüyen araç çağrısı sayısını sınırlar; ayrıca aynı çağrıyı tekrarlayıp duran bir aracı da tespit edebilir. Tavanlar isteğe aittir: isteğin başlattığı her çalıştırmayı sayar, ajanın kendisininkini ve altındaki her alt-ajanınkini. Tüm alanlar opsiyoneldir: bir alanı ayarlamazsanız o koruma KAPALIdır.

Her alan opsiyoneldir ve ayarlanmazsa bağımsız olarak kapalıdır:

RunLimits @gnldev/durable içinde yaşar. Bir çalıştırmaya verilir ve tüm istek için sayılır:

import { createGnl, RunLimitExceededError, type RunLimits } from '@gnldev/durable';

gnl.run'a limits geçin. Bir tavana ulaşıldığında RunLimitExceededError fırlatılır ve çalıştırma bir sonraki adımı başlatmaz:

// A new model step starts only if budget is left. A step already running is not cut,
// so that one step can go past the ceiling; no step starts after it.
const limits: RunLimits = { maxTokens: 50_000, maxCostUsd: 0.5, maxToolCalls: 20 };

try {
  await gnl.run('asst', { runId: 'r5', prompt: 'do the task', limits });
} catch (e) {
  if (e instanceof RunLimitExceededError) {
    // e.detail: { kind, value, limit }
    console.log('limit exceeded:', e.detail.kind, e.detail.value, e.detail.limit);
  }
}

Aynı araç çağrısını tekrarlayıp duran bir modeli yakalamak için loopDetection ayarlayın. reflect, hiçbir şey bloklanmadan önce modele toparlanma şansı verir:

// Same tool + identical argsHash repeated 3 times IN A ROW → 'reflect' delivers a nudge
// instead of an immediate block ('block' throws ToolLoopDetectedError right away).
const limits: RunLimits = { loopDetection: { maxRepeats: 3, onRepeat: 'reflect' } };

Hata fırlatıldığında journal tutarlı kalır — limiti yükseltin ve çalıştırmanın bıraktığı yerden devam etmek için AYNI runId ile resume edin:

// The journal stays consistent when RunLimitExceededError is thrown.
// Raise the ceiling and resume the SAME runId to continue past the cut-off point:
await gnl.run('asst', { runId: 'r5', prompt: 'continue', limits: { maxTokens: 200_000 } });

Bir istek, tek bir çağrının başlattığı her şeydir: ajanın çalıştırması ve altındaki her alt-ajan çalıştırması. maxToolCalls, maxTokens ve maxCostUsd hepsini sayar — üst ajanın çağrılarını, her kardeşinkini ve alt-ajanınkini. İşi bir alt-ajana devretmek kendi başına bir araç çağrısı sayılmaz. Yeni bir model adımı yalnızca bütçe kaldıysa başlar: 60 token'lık bir bütçede istek artık doğrudan da alt-ajanlar üzerinden de 60'ta durur (0.10'dan önce: doğrudan 75, alt-ajanlar üzerinden 90).

Paralel gönderilen her çağrı, yürümeden önce isteğin araç-çağrısı toplamında tek bir atomik adımla bir koltuk alır; biten çağrı koltuğunu kendisini saydığı adımda geri verir. Limitin kabul ettiği her çağrı çalışır, fazlası çalışmaz: limit 5 iken on iki paralel çağrının 0.10'dan önce on ikisi de çalışıyordu, şimdi beşi çalışır; limit 50 iken 200 paralel çağrıdan memory, Sqlite ve Postgres'te tam 50'si çalışır. incrBy'ı değer döndürmeyen özel bir journal, compare-and-set koltuğunu korur: limit asla aşılmaz, ama limitin sınırındaki bir çağrı, başka biri biterken reddedilebilir.

// The limits are the request's: the agent's calls and every sub-agent's count
// toward one total. Handing work to a sub-agent is not itself a tool call.
const limits: RunLimits = {
  maxToolCalls: 50,  // 200 parallel calls → exactly 50 run
  maxConcurrency: 4, // at most 4 tool calls of the request execute at the same time
};

await gnl.run('coordinator', { runId: 'r7', prompt: 'process the batch', limits });

Bir GNL sunucusuna gönderilen istek kendi limits'ini taşıyabilir, ama yalnızca maxCostUsd, maxTokens, maxToolCalls, maxConcurrency ve loopDetection.maxRepeats'i sıkılaştırabilir — sunucunun değeriyle isteğinkinden küçük olanı geçerlidir. İsteğin limits'indeki başka her ad 400 ile reddedilir; sunucunun kendi limitlerinin hepsi çalıştırmaya ulaşır.

CLI'nin yazdığı bir projede dağıtımın kendi sınırı gnl.config.ts içindeki limits alanıdır (maxCostUsd, maxTokens, maxToolCalls ve döngü algılama). gnl dev ile gnl add host'un yazdığı src/app.ts onu sunucu tarafı sınır olarak createRestApi'ye verir: istek hiçbirini söylemediğinde olduğu gibi uygulanır, istek onu yalnızca sıkılaştırabilir. Studio Playground çalıştırmaları REST isteği değildir ve bununla sınırlanmaz.

export default {
  // the server-side bound: `gnl dev` and the src/app.ts that `gnl add host` writes hand it to createRestApi
  limits: { maxCostUsd: 0.5, maxToolCalls: 20 },
};

maxCostUsd tavanı artık kendini adlandırmayan bir modelde de devreye girer. Fiyatlama model kimliğini yalnızca cevaptan okurdu; bunu atlayan bir sağlayıcı, proxy ya da middleware her adımı unknown, yani 0 $ olarak fiyatlar ve tavan hiç tetiklenmezdi. Modelin yapılandırılmış kimliği (wrapLanguageModel'in tuttuğu) artık yedektir ve her adımın yanına configuredModelId olarak yazılır; cevabın kendi kimliği yine önce gelir ve fiyatsız model uyarısı gerçek kimliği söyler. Bundan önce yazılmış kayıtlarda alan yoktur ve eskisi gibi fiyatlanır.

streamDurable / gnl.stream(name, opts), bir loop, maxToolCalls, duplicate ya da tainted BLOCK ateşlendiğinde çağrılan bir onBlocked callback'i kabul eder. Guard'ın ürettiği HAM yapılandırılmış ihlali alır — fırlatılan bir hatanın taşıyacağı bilgiyle aynısını. result.text artık bir block'ta da REDDEDİLİR; bu, gnl.run'dan fırlatılan RunLimitExceededError'ı yansıtır, böylece stream'in doğrudan bir tüketicisi bunu sessizce kaçıramaz.

// onBlocked fires for a loop / maxToolCalls / duplicate / tainted BLOCK — you get the
// RAW breach and decide what (if anything) the user sees. GNL does not invent a
// user-facing message.
const result = await gnl.stream('asst', {
  runId: 'r6',
  prompt: 'do the task',
  limits,
  onBlocked: (breach) => {
    // breach.kind identifies which guard fired; breach.message is a raw diagnostic
    // string; breach.detail carries that guard's own structured payload.
    console.log('blocked:', breach.kind, breach.message);
  },
});

try {
  const text = await result.text;
} catch (e) {
  // result.text REJECTS on a block — mirrors runDurable throwing, so a direct
  // consumer of the stream cannot silently miss the breach.
}