İnsan-onaylı araçlar (guard)

Bir agent para tahsil etmek, e‑posta göndermek veya kayıt silmek gibi geri alınamaz bir araç çağırdığında, çağrı ÇALIŞMADAN ÖNCE bir insanın onayını beklemek istersiniz. Guard , her tool çağrısından önce (exactly-once kontrolünden sonra) devreye giren genel bir politika kancasıdır: LLM'in hangi tool'ları gördüğünü kısıtlamaz, yalnızca yan etkiyi kapıya alır.

Guard require-approval döndürdüğünde gerçek tool ÇALIŞMAZ; bunun yerine bir Interrupt journal'a suspended olarak yazılır ve run durur. Operatör onayı verdikten sonra aynı runId ile resumeRun çağrılır — prompt'u yeniden vermeye gerek yoktur, girdi journal'dan okunur.

import { runDurable, resumeRun } from '@gnldev/durable';
import type { Guard, GuardCall, GuardDecision, Interrupt } from '@gnldev/durable';

Ekstra bir alt-paket gerekmez — Guard tipi ve resumeRun çekirdek @gnldev/durable export'larıdır. Journal adaptörünü (ör. @gnldev/durable/sqlite) ihtiyacınıza göre ayrıca içe aktarın.

1) Bir Guard tanımlayın — tool adı ve argümanlara bakıp allow / deny / require-approval döner:

const guard: Guard = ({ toolName, args }) =>
  toolName === 'chargeCard' && (args as any).amount > 1000
    ? { action: 'require-approval' }
    : { action: 'allow' };

2) runDurable'a guard'ı verin. Riskli çağrı askıya alınırsa gerçek tool hiç çalışmaz, dönen sonuçta interrupts dolu gelir:

const r1 = await runDurable({
  runId: 'o1',
  journal,
  model: makeModel(),
  tools: makeTools(counter),
  guard,
  prompt: 'charge 5000',
  stopWhen: stepCountIs(6),
});

// counter.charges === 0 → the tool did NOT run
// r1.interrupts.length === 1 → one call is awaiting approval
console.log(r1.interrupts[0]);
// { toolCallId: 'call-c', toolName: 'chargeCard', args: { amount: 5000 }, reason: undefined }

3) Operatör onayı verdikten sonra AYNI runId ile resumeRun çağırın — prompt tekrar verilmez, girdi journal'dan okunur. approvals objesinde askıdaki toolCallId'yi trueişaretleyin:

const r2 = await resumeRun('o1', {
  journal,
  model: makeModel(),
  tools: makeTools(counter),
  guard,
  approvals: { 'call-c': true },
  stopWhen: stepCountIs(6),
});

// counter.charges === 1 → the tool has now actually run
// r2.text.includes('Done') → the run completed