Alt ajanlar: birim istektir

Bir ajanın agents alanına kayıtlı ajan adlarını yazdığınızda, her biri o ajana agent_<name> adlı bir araç olarak sunulur. Aracın tek argümanı vardır: task. Araç açıklaması alt ajanın description alanından gelir.

Alt ajan ayrı bir kod yolu değildir. Doğrudan çalıştırmayla aynı ajan çalıştırmasından doğar; görevi devreden çalıştırmanın bir kat altında, agent:<parent runId>:<delegation call> run id'siyle. Kendi processor'ları, scorer'ları, guard'ı ve alt ajanları çalışır. Ebeveynin çağıranı, iptali, zaman aşımları ve onayları devirle birlikte aşağı iner.

Taint iki yönde de geçer. Ebeveyn güvenilmeyen içerik okumuşsa alt ajan taint'li başlar; yan etkileri aynı taintedSideEffects merdiveninden geçer. Alt ajan güvenilmeyen içerik okursa, döndükten sonra ebeveyn de taint'li olur.

Bir isteğin başlattığı her şey — ebeveyn, her kardeş alt ajan, alttaki her kat — tek bir istektir. Tek bir ajan çalıştırması için geçerli olan, istek için de geçerlidir:

• İstek başına bir kez. idempotencyKey ve idempotencyWindow: 'run' taşıyan ya da idempotency: 'args' olan bir çağrı, isteğin tamamında tekilleştirilir. Kayıt istekte durur (xreq:<runId>:args-…); her çalıştırma kendi çağrısı altında bir aynasını tutar.
• Limitler isteğindir. maxToolCalls, maxTokens, maxCostUsd ve maxConcurrency ebeveynin, her kardeşin ve alt ajanın çağrılarını birlikte sayar.
• Onayların adresi vardır. Alt ajanın sorusunun kendi adresi olduğu için bir onay tam olarak bir çağrıyı yanıtlar.

Örnek: 30 çalışan bordro alt ajanlarına dağıtılıyor, biri on kez veriliyor. Ödeme aracı çalışan kimliğiyle anahtarlanmış ve idempotencyWindow: 'run' taşıyor. 0.10'dan önce her alt ajan ayrı bir pencereydi ve 40 ödeme yapılıyordu. 0.10'da pencere istektir; 30 ödeme yapılır.

Anahtarsız bir tekrar da sessizce düşürülmez: varsayılan sideEffectDuplicates: 'suspend' ile bir kişiye soru olur. Kişinin reddettiği tekrar aynı istekte bir daha sorulmaz.

Kayıt, işi yürüten çağrıyı adıyla taşır (ranBy). İşi yapan alt ajan çalıştırmasını telafi etmek (compensateRun) ya da silmek (purgeRun), doğrudan çalıştırmada olduğu gibi o etkiyi geri alır ve siler.

desk ajanı işi refunder'a devredebilir. refund aracı bir yan etkidir, çalışmadan önce bir kişinin onayını ister ve istek boyunca sipariş numarasıyla anahtarlanır.

import { tool } from 'ai';
import { z } from 'zod';
import { createGnl, gnlTool } from '@gnldev/durable';

const refund = gnlTool(
  tool({
    description: 'Refund an order',
    inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
    execute: async ({ orderId, amount }) => payments.refund(orderId, amount),
  }),
  {
    sideEffect: true,
    confirm: true,                // a person approves before it runs
    idempotencyKey: (input) => (input as { orderId: string }).orderId,
    idempotencyWindow: 'run',     // once per request, across every sub-agent
  },
);

const gnl = createGnl({
  storage,
  agents: {
    desk: {
      model,
      system: 'You answer customer tickets. Hand refunds to the refunder.',
      agents: ['refunder'],       // desk sees the tool agent_refunder({ task })
    },
    refunder: {
      model,
      description: 'Refunds an order',
      system: 'You refund orders.',
      tools: { refund },
    },
  },
});

İsteği çalıştırın. Alt ajan refund'da durur ve soru ebeveynin sonucunda görünür:

import { STAFF } from '@gnldev/durable';

const request = {
  runId: 'ticket-881',
  prompt: 'Refund order A-1001, 40 EUR.',
  caller: STAFF,
  limits: { maxToolCalls: 20 },   // counts desk's calls and refunder's together
};

const first = await gnl.run('desk', request);
const [q] = first.interrupts;
// q.toolCallId  'call_0/call_0'   <delegation call>/<child call>
// q.toolName    'refund'
// q.args        { orderId: 'A-1001', amount: 40 }
// q.reason      "The 'refunder' sub-agent asks: 'refund' requires explicit confirmation before it runs."
// q.delegatedTo { runId: 'agent:ticket-881:call_0', agent: 'refunder' }

const done = await gnl.run('desk', {
  ...request,
  approvals: { [q.toolCallId]: true },
});
// refund ran once; done.interrupts is []

Çalıştırmanın gösterdiği toolCallId'yi değiştirmeden yanıtlayın. Devam edildiğinde tamamlanmış iş journal'dan tekrar oynatılır, devir onayla birlikte aşağı iner ve refund bir kez çalışır. ticket-881'i yeniden çalıştırmak onu ikinci kez çalıştırmaz.

Devir, ebeveynin üzerinde dallanabileceği bir sonuç döndürür. Sonuç alt ajanın metninden değil, araç sonuçlarından okunur:

// what an agent_<name> call returns to the parent's model
type DelegationResult = {
  status: 'completed' | 'failed' | 'suspended';
  text: string;
  interrupts: Interrupt[];   // addressed <delegation call>/<child call> when suspended
  failed?: Array<{ tool: string; kind: 'error' | 'blocked' | 'denied'; message: string }>;
}

failed, alt ajandaki son çağrısı başarısız olan, engellenen ya da reddedilen her aracı listeler. Aynı aracın başarısızlığından sonra gelen bir başarı sayılmaz.

Alt ajanın sorusu <delegation call>/<child call> adresini taşır. Çağrılarını ikisi de call_0 diye numaralayan iki alt ajan iki ayrı soru üretir. Her alt kat adrese yeniden önek ekler.

Soru delegatedTo: { runId, agent } taşır: alt ajanın çalıştırması ve adı; o alt ajan da devrettiyse bir sonraki adım için via. Kişinin okuduğu reason run id'yi değil alt ajanın adını söyler: The 'refunder' sub-agent asks: …. İki kat şöyle okunur: The 'lead' sub-agent asks: The 'medic' sub-agent asks: ….

Aynı runId ile approvals: { [interrupt.toolCallId]: true } vererek devam edin. Gösterilen id'yi yanıtlayan bir istemcinin başka bir şey yapması gerekmez; alt ajanın id'sini kendiniz kurmayın.

limits'i çalıştırmaya verin. maxToolCalls, maxTokens, maxCostUsd ve maxConcurrency isteğin tamamını sayar. Devir çağrısının kendisi (agent_<name>) bir araç çağrısı değildir ve eşzamanlılık yuvası tutmaz; alt ajanın yaptığı çağrılar sayılır.

Bir araç çağrısı çalışmadan önce isteğin toplamı üzerinde tek bir atomik adımla yer ayırır; bu yüzden paralel çağrılar maxToolCalls'u aşamaz (200 paralel çağrı, limit 50: bellek, SQLite, Postgres ve Redis'te 50 çalıştı). Yeni bir model adımı ancak token ve maliyet bütçesi kaldıysa başlar.

Çalıştırma limitleri