ابنِ Agent Harness: الحلقة وخمس طرق للخروج منها

لم يكن ممكنًا كتابة الفصل 14 ضد مزوّد حقيقي، لأنك لا تستطيع أن تطلب منه 429 في لحظة تختارها. لدى هذا الفصل المشكلة نفسها بشكل مختلف: لا يمكنك أن تطلب من نموذج حقيقي أن ينفلت، أو أن يطلب الأداة نفسها بالحجج نفسها مرتين متتاليتين، عند الطلب وبقابلية إعادة الإنتاج.

لذلك يكون البرنامج الأول مزوّدًا scripted: endpoint له شكل chat completions API تكون إجابته دالة في فهرس الدور وما أعادته الأدوات حتى الآن. وهو يعدّ tokens باستخدام byte-pair encoder حقيقي، لذا فالمال أدناه حساب لا زينة.

const SCRIPTS = {
  // A well-behaved task: list, read, answer.
  plan: (t) =>
    t === 0 ? asks(call("c1", "list_files", {}))
    : t === 1 ? asks(call("c2", "read_file", { path: "errors.log" }))
    : text("errors.log mentions a timeout: worker 7 timed out after 30000 ms."),

  // Never declares itself done.
  runaway: (t) => asks(call(`c${t}`, "list_files", {})),           

  // Guesses a file name, then corrects itself IF it was told what happened.
  recover: (t, all) =>
    t === 0 ? asks(call("c1", "read_file", { path: "timeout.log" }))
    : /Call list_files/.test(all)                                  
      ? (t === 1 ? asks(call("c2", "list_files", {}))
        : t === 2 ? asks(call("c3", "read_file", { path: "errors.log" }))
        : text("errors.log mentions a timeout."))
      : text("I could not read the file, so I do not know."),
};

const turn = messages.filter((m) => m.role === "assistant").length;             
const toolText = messages.filter((m) => m.role === "tool").map((m) => m.content).join("\n");
const message = SCRIPTS[scenario](turn, toolText);

سطران يحملان التصميم. فهرس الدور مشتق من المحادثة، لا محفوظ في متغير، لذلك يكون المزوّد عديم الحالة ويمكن قتل تشغيل واستئنافه ضده. وrecover يقرأ نتائج الأدوات قبل أن يقرر: نموذج scripted يقرأ transcript الخاص به هو الحد الأدنى اللازم لقياس ما إذا كان harness قد أعطاه شيئًا يستحق القراءة.

الكتالوج هو كتالوج الفصل 18، أربع أدوات على ثلاثة ملفات: list_files، وread_file، وdelete_file — معلّمة needsApproval — وscan_archive، وهي بطيئة عن قصد.

هذه هي الفكرة كلها، قبل أي من الأجزاء التي تجعلها قابلة للنجاة.

while (true) {
  const reply = await callModel(base, messages, tools, signal);
  messages.push(reply.message);

  const calls = reply.message.tool_calls ?? [];
  if (!calls.length) return reply.message.content;          

  for (const c of calls) {
    const tool = byName.get(c.function.name);
    const result = await tool.run(JSON.parse(c.function.arguments));
    messages.push({ role: "tool", tool_call_id: c.id, name: c.function.name, content: result });
  }
}

وجّهها إلى المزوّد scripted وستفعل بالضبط ما يبدو أنها تفعله:

plan, cap 20    turns=3  tools=2  in=815  out=70  cost=$0.002470  ms=89  status=completed
   answer: "errors.log mentions a timeout: worker 7 timed out after 30000 ms."
   per-turn prompt tokens: 204, 269, 342

ثلاثة أدوار، تنفيذان للأدوات، وربع سنت أمريكي. لاحظ السطر الأخير: 204، 269، 342. كل دور يعيد إرسال كل ما سبقه، وهذه فاتورة الفصل 16 التربيعية تصل إلى مكان لم يكتب فيه أحد شيئًا. بقية هذا الفصل هي ما يحدث عندما لا يتوقف ذلك السطر عن النمو.

وجّه الحلقة نفسها إلى script ‏runaway — نموذج يطلب أداة في كل دور بلا استثناء ولا يصدر نثرًا أبدًا — ولن يُفعّل return المعلّم. لا يوجد مخرج آخر. يستمر البرنامج حتى تموت العملية أو تموت بطاقة الائتمان.

الإصلاح سطر واحد، وهو أول تحكم توصي به الأدبيات،⁵ والجميع يكتبه في النهاية. ما لا يفعله تقريبًا أحد هو قياس قيمته:

اقرأ الصفين الأخيرين معًا. مضاعفة الحد من 50 إلى 100 لم تضاعف التكلفة؛ بل ضربتها في 3.7. انتقلت input tokens من 88,649 إلى 337,299، أي عامل 3.8، لأن الدور $n$ يحمل كل دور سابق معه والمجموع هو $\Theta(n^2)$. حد الأدوار ليس قرصًا خطيًا. إنه قرص على الجذر التربيعي لأسوأ حالة لديك، ولهذا فإن رفعه من 20 إلى 100 «فقط للاحتياط» قرار يستحق تسعيره قبل اتخاذه.

مشكلة حد الأدوار أن الدور ليس له سعر ثابت. عشرون دورًا فوق transcript قصير كلفت $0.038 أعلاه. عشرون دورًا مع كتالوج من 200 أداة، ومجموعة مستندات مسترجعة، وأربعين رسالة من التاريخ تكلف مئات الأضعاف، والحد لا يعرف. ما يريد المشغّل تقييده هو الفاتورة.

لذلك تحسب الحلقة المال، باستخدام computeCost من الفصل 16 مقابل الأسعار المقروءة هناك — $2.00 لكل مليون input tokens و$12.00 لكل مليون output، للنموذج المسعّر في هذه الدورة كلها:

const PRICE_IN = 2.0 / 1e6, PRICE_OUT = 12.0 / 1e6;
export const cost = (u: Usage) => u.prompt_tokens * PRICE_IN + u.completion_tokens * PRICE_OUT;

// at the top of every iteration, before asking the model anything:
if (state.turns >= opts.limits.maxTurns) return stop("max_turns_exceeded", { type: "max_turns" });
if (state.costUsd >= opts.limits.maxBudgetUsd) return stop("budget_exceeded", { type: "max_budget" }); 

// ...and once the reply is back, before anything else happens with it:
state.costUsd += cost(reply.usage);

script الانفلات نفسه، بلا حد أدوار على الإطلاق، وثلاث ميزانيات:

هناك شيئان يستحقان التسمية. أولًا، تشتري الميزانية عددًا مختلفًا من الأدوار في كل مرة، وهذا هو المقصود: إنها تحدّ الشيء الذي يهتم به المشغّل، وتترك عدد الأدوار يقع حيث يضعه transcript. ثانيًا، كل صف يتجاوز الحد. كانت الميزانية $0.010 وأُنفق $0.010780، لأن الفحص يجري قبل الدور ولا يُعرف سعر الدور إلا بعد انتهائه. لا يمكنك تقييد الإنفاق بدقة؛ يمكنك تقييده ضمن تكلفة دور واحد. قل ذلك في الواجهة بدل التظاهر، وضع الفحص قبل الاستدعاء كي يكون التجاوز دورًا واحدًا لا دورين.

بات لدى الحلقة الآن ثلاثة مخارج، وصار شكل بقية الفصل مرئيًا. ينتهي تشغيل production بطريقة واحدة بالضبط من خمس طرق، وليست هذه تنويعات على الشيء نفسه:

طيّ هذه كلها في boolean واحد هو أكثر خطأ تصميمي شيوعًا في هذا الملف، وهو مكلف بطريقة محددة: ثلاثة من الخمسة قابلة للاستئناف واثنان ليستا كذلك. agent وصل إلى حد أدواره لديه transcript صالح، ونتيجة جزئية حقيقية، وخطوة تالية؛ أما agent حصل على 401 فلا يملك شيئًا من ذلك. لذلك يسجل harness السبب كبيانات:

export type RunStatus =
  | "running" | "completed" | "failed"
  | "max_turns_exceeded" | "budget_exceeded" | "interrupted";

export type Interruption =
  | { type: "approval"; callId: string; toolName: string; args: unknown }
  | { type: "max_turns" } | { type: "max_budget" }
  | { type: "cancelled"; reason: string };

أنهى الفصل 18 بادعاء بلا رقم: أعد خطأ الأداة إلى النموذج كنتيجة أداة بدل رفعه، وعادةً ما يصلح النموذج نفسه. ها هو الرقم.

فشل واحد، وثلاث سياسات. النموذج scripted يخمّن ملفًا غير موجود؛ الأداة ترمي no such file: timeout.log. Call list_files to see what exists.

يكلف الصف الثالث 4.7 أضعاف الأول، وهو الوحيد الذي يجيب عن السؤال. والصف الثاني هو المثير للاهتمام، لأنه ما تفعله معظم قواعد الكود فعليًا: التُقط الخطأ، ونجت الحلقة، وقيل للنموذج أن شيئًا فشل لا ماذا فشل، فاستسلم بأدب. الفرق بين الصفين الثاني والثالث ليس معالجة أخطاء. إنه جملة مكتوبة لقارئ.

لذلك يعامل harness الأداة التي ترمي كبيانات، ويجعل الصياغة سياسة:

} catch (err: any) {
  if (signal.aborted) return stop("interrupted", { type: "cancelled", reason: String(signal.reason) });
  if (opts.toolErrorsAreFatal) { state.error = err.message; return stop("failed"); }
  result = (opts.toolErrorText ?? ((e: Error) => `Error: ${e.message}`))(err);   
}

حذّر الفصل 18 أيضًا من الجانب الآخر، وله هو أيضًا ثمن. وجّه الحلقة إلى أداة تفشل لسبب لا تستطيع أي رسالة إصلاحه — قراءة لا يُسمح للعملية بأدائها — وسيعيد النموذج المحاولة إلى الأبد:

read a file the process may not open   turns=12  toolruns=11  in=7,079  cost=$0.018622
                                      status=max_turns_exceeded   answer=""

أحد عشر تنفيذًا متطابقًا لاستدعاء لا يمكن أن ينجح، بتكلفة 5.2 أضعاف التشغيل الذي تعافى من خطأ قابل للإصلاح، ولا شيء في النهاية. الأخطاء context؛ والخطأ الدائم context يسمّم بقية التشغيل. التمييز هو فرز حالات الفصل 14 منقولًا طبقة إلى أعلى: الخطأ الذي يستطيع النموذج التصرف بناءً عليه يعود إلى transcript، والخطأ الذي لا يستطيع يجب أن يوقف التشغيل مع سبب. حد الأدوار هو ما يقف بينك وبين الحالة الثانية اليوم، وهذا أرضية لا إصلاح.

الآن الفشل الذي يفترض معظم الناس أنه لا يمكن أن يحدث. النماذج تكرر نفسها. اطلب من أي حلقة أن تعمل مدة كافية وسترى الأداة نفسها بالحجج نفسها في دورين متتاليين.

مقيسًا مقابل baseline للمهمة نفسها دون التكرار:

كلّف الاستدعاء المكرر $0.001050 إضافية، أي زيادة 75 %، وهنا الجزء الذي يفاجئ الناس: لم تسترد cache النتيجة أيًا من ذلك. وفرت deduplication تنفيذ الأداة لا الدور، لأنه بحلول الوقت الذي يلاحظ فيه كودك التكرار يكون النموذج قد تقاضى أجر طلبه بالفعل. التوفير حقيقي عندما تكون الأداة بطيئة، أو محدودة المعدل، أو مفوترة حسب الاستدعاء — وهو صفر في بند التكلفة الذي نما.

هناك نسخة أسوأ. طبّق cache نفسها على أداة تكتب، ولن يحدث الاستدعاء الثاني بصمت:

naive cache on every tool        3 turns, 1 tool run,  files deleted: ["access.log"]
cache only on read-only tools    3 turns, 2 tool runs, files deleted: ["access.log","access.log"]

أيّهما صحيح؟ لا هذا ولا ذاك، على نحو يمكن معرفته. يقول البروتوكول إن هذه استدعاءان: يحملان قيمتي tool_call_id مختلفتين. تقول الحجج إنهما قد يكونان واحدًا. harness يقرر بمقارنة سلاسل الحجج سيبتلع يومًا ما الثاني من رسومين متطابقين مقصودين — وقد سمّى الفصل 14 الآلية الوحيدة التي تحل هذا بأمانة، وهي مفتاح idempotency يولّده، لكل عملية منطقية، المستوى الذي يعرف ما هي العملية. إلى أن تحمل الأداة واحدًا، يكون الافتراض الدفاعي هو بوابة القراءة فقط أعلاه: cache للقراءات، تنفيذ للكتابات، ودع idempotency الخاصة بالكتابة تتولى الباقي.

if (opts.dedupe && (tool.readOnly || opts.dedupeAll) && seen.has(signature)) {   
  state.messages.push({ role: "tool", tool_call_id: c.id, name: c.function.name, content: seen.get(signature)! });
  continue;
}

script ‏destructive يسرد الملفات ثم يطلب حذف ملف لم تذكره المهمة قط. لا شيء في الحلقة حتى الآن سيمنعه.

الأداة المعلّمة needsApproval لا تفشل ولا تتابع. إنها توقف التشغيل وتعيد التحكم، ومعه كل ما يحتاجه شخص ليقرر:

if (tool.needsApproval && !state.approved.includes(c.id)) {
  trace(state.runId, "approval_required", { toolName: tool.name, args: c.function.arguments, callId: c.id });
  return stop("interrupted", { type: "approval", callId: c.id, toolName: tool.name, args: JSON.parse(c.function.arguments) });
}

stopped at turn 2: interrupted / approval -> delete_file({"path":"access.log"})
files deleted so far: []
approve -> total turns=3  deleted=["access.log"]  "Deleted access.log to free space."
reject  -> total turns=3  deleted=[]              "I did not delete anything: you declined the deletion."

هذه هي الآلية كلها، والسبب في أنها return لا callback هو القسم التالي: بين التوقف والحكم، قد لا تكون العملية موجودة أصلًا.

لكن أولًا، القياس الذي لا يتوقعه أحد. الرفض ليس غياب نتيجة — في transcript خانة keyed by ‏tool_call_id ويجب أن يدخل فيها شيء. شغّل الرفض نفسه مرتين، مع تغيير ما يقوله ذلك الشيء فقط:

rejected with a reason   deleted=[]  the agent then told the user:
                                     "I did not delete anything: you declined the deletion."
rejected with nothing    deleted=[]  the agent then told the user:
                                     "Deleted access.log to free space."

لم يُحذف شيء في أي من التشغيلين، وفي الثاني يُقال للمستخدم إنه حُذف. عمل نظام الأذونات عملًا مثاليًا؛ التقرير كذبة. إنها الآلية نفسها في جدول أخطاء الأدوات، لكنها تصل إلى مكان أهم بكثير — قال إنسان لا، وحُظر الإجراء بشكل صحيح، وملخص agent يناقض الواقع لأن الرفض لم يُكتب قط حيث يقرأ النموذج. القاعدة الناتجة عن ذلك قصيرة: مهما كان قرار كودك بشأن استدعاء أداة، اكتب القرار في transcript بكلمات. يعود الفصل 30 إلى هذا من جانب الأمان، حيث يكون الفرق بين سجل تدقيق وخيال.

تستغرق الموافقة دقائق أو ساعات. يستغرق deploy ثواني. إذا كان التشغيل يعيش في متغير محلي داخل طلب HTTP، فكل إعادة تشغيل هي تشغيل ضائع، وكل موافقة سباق.

لذلك فالتشغيل ليس closure. إنه كائن عادي قابل للتسلسل — رسائل، وعدد أدوار، وتكلفة، وحالة، وانقطاع، وقائمة call ids الموافق عليها — والحلقة دالة صرفة فوقه. هذا القيد الوحيد هو ما يجعل الاستمرارية مسألة سطر واحد:

export const save = (s: RunState, dir: string) => writeFileSync(`${dir}/${s.runId}.json`, JSON.stringify(s));
export const load = (dir: string, runId: string) => JSON.parse(readFileSync(`${dir}/${runId}.json`, "utf8"));

سؤال الصحة ليس الحفظ. بل ما يحدث في طريق العودة، والإجابة الساذجة تفرض عليك تكلفة مزدوجة. إذا ماتت العملية بعد أن طلب النموذج أداة وقبل أن تُكتب النتيجة، فإن استئنافًا يبدأ باستدعاء النموذج مرة أخرى يدفع مقابل دور يملكه بالفعل — وإذا بدأ بإعادة تشغيل الأدوات، فإنه ينفذ كتابة مرتين.

الإصلاح هو أن تبدأ الحلقة بسؤال transcript عما هو معلّق:

export function pending(state: RunState): ToolCall[] {
  const answered = new Set(state.messages.filter((m) => m.role === "tool").map((m) => m.tool_call_id));
  const last = state.messages.at(-1);
  if (last?.role !== "assistant") return [];
  return (last.tool_calls ?? []).filter((c) => !answered.has(c.id));    
}

كل تكرار يفرّغ pending أولًا ولا يسأل النموذج إلا عندما لا يبقى شيء معلّق. يصبح الاستئناف مسار الكود نفسه كالمسار العادي، وكذلك الموافقة — الاستدعاء الموافق عليه هو ببساطة استدعاء معلّق صار مسموحًا بتشغيله. اقتل العملية في منتصف المهمة وأعد تشغيلها:

process died after turn 2. tool runs so far: list_files, read_file:errors.log
restored from disk: turns=2  cost=$0.001570  messages=6  status=running
resumed and finished: turns=3  cost=$0.002470  status=completed
tool runs across BOTH processes: list_files, read_file:errors.log

تنفيذان للأدوات عبر عمليتين لمهمة تحتاج اثنين، والتكلفة النهائية مطابقة للتشغيل الذي لم يتعطل قط. تتراكم التكلفة عبر إعادة التشغيل لأنها كانت في الحالة، لا في متغير.

scan_archive يستغرق ثلاث ثوانٍ هنا ويمثل الأداة التي تستغرق ثلاث دقائق في production. هناك شيئان مفقودان أثناء تشغيله: لا يعرف المستخدم أن شيئًا يحدث، وزر Stop لا يفعل شيئًا.

كلاهما له الإصلاح نفسه، وهو AbortSignal من الفصل 14 مدفوعًا مستوى أعمق. الإشارة ليست للـ fetch فقط — بل تُمرّر إلى الأداة، والأداة المكتوبة جيدًا تحترمها:

result = await tool.run(JSON.parse(c.function.arguments), {
  signal,                                                                     
  progress: (label) => { trace(state.runId, "tool_progress", { toolName: tool.name, label }); opts.onProgress?.(label); },
});

progress: scanned 200 of 1200 files  (t+506 ms)
progress: scanned 400 of 1200 files  (t+1007 ms)
no cancellation:            stopped after 3,015 ms, status=completed
user presses Stop at 1.2 s: stopped after 1,202 ms, status=interrupted, reason="user pressed Stop"

ميليثانيتان من النقرة إلى التوقف، لأن sleep داخل الأداة يستمع إلى الإشارة نفسها التي يستمع إليها fetch. مرّرها فقط إلى fetch وسيظل زر Stop نفسه ينتظر ثلاث ثوانٍ — طول الأداة — و«يُلغي» التشغيل بعد أن يكون العمل الذي كان يلغيه قد انتهى بالفعل. الإلغاء الذي لا يُوصّل إلى الأسفل كله spinner يقول الكلمة الصحيحة.

يبث harness سطرًا واحدًا لكل حدث، والمفردات صغيرة بما يكفي لحفظها: turn، tool_start، tool_progress، tool_result، approval_required، run_stopped.

{"runId":"n1","type":"turn","turn":1,"prompt_tokens":204,"completion_tokens":23,"total_tokens":227,"costUsd":0.000684,"finish":"tool_calls"}
{"runId":"n1","type":"tool_start","toolName":"list_files","args":"{}","callId":"c1"}
{"runId":"n1","type":"tool_result","toolName":"list_files","ms":1,"ok":true}
{"runId":"n1","type":"turn","turn":2,"prompt_tokens":269,"completion_tokens":29,"total_tokens":298,"costUsd":0.00157,"finish":"tool_calls"}
{"runId":"n1","type":"approval_required","toolName":"delete_file","args":"{\"path\":\"access.log\"}","callId":"c2"}
{"runId":"n1","type":"run_stopped","status":"interrupted","reason":"approval","turns":2,"costUsd":0.00157}

ثلاث خصائص تجعل هذا trace لا logging. يحمل كل سطر run id، لذلك يكون التشغيل الممتد عبر ثلاث عمليات ويومين استعلامًا واحدًا. يحمل كل سطر turn أعداد token الخاصة به والتكلفة الجارية، لذلك يصبح سؤال «لماذا كلف هذا التشغيل أربعين دولارًا» قابلًا للإجابة بعد الواقعة بدل أن يكون قابلًا للإعادة نظريًا فقط. ويحمل run_stopped السبب، وهو الحقل الذي يحوّل تذكرة دعم إلى إجابة من سطر واحد: agent توقف عند الميزانية وagent تعطل يبدوان متطابقين من الخارج ويحتاجان ردين متعاكسين.

قاس الفصل 13 time to first token على عتاد تملكه. وقاسه الفصل 14 عبر socket. يضاعفه agent، والمضاعف رقم لم يختره أحد:

المهمة ذات الأدوار الثلاثة نفسها، مع تغيير latency المزوّد فقط:

يساهم harness نفسه بخمس عشرة ميليثانية في تشغيل من ثلاثة أدوار. كل ما عدا ذلك هو $N$ مضروبًا في رقم لا تتحكم فيه — مُعيّن داخل serving scheduler يجمّع طلبك مع طلبات غرباء⁶ — و$N$ يختاره النموذج. لهذا يهم streaming الفصل 14 هنا أكثر مما يهم في chat ويساعد أقل: يمكنك streaming الدور الأخير، والأدوار الأربعة قبله صمت إلا إذا بث harness تقدمًا. وهذا أيضًا هو الحجة كلها لحدث tool_progress أعلاه — في agent، وحدة التغذية الراجعة الصادقة ليست token، بل الخطوة.

كل ما سبق عمل ضد مزوّد scripted، وهذا يثبت harness ولا يثبت شيئًا عن النماذج. لذلك غيّر سطرًا واحدًا — seam من الفصل 14، LLM_BASE_URL — ووجّه الكود المطابق إلى Qwen2.5-0.5B-Instruct محلي مع الأدوات الأربع نفسها. ست مهام على الملفات الثلاثة نفسها:

turns=2 tools=1 wall= 15,260ms  Which file mentions a timeout?      -> "The file timeout.txt does not exist..."
turns=2 tools=1 wall= 13,037ms  How many files are in the directory? -> "There are three files..."
turns=2 tools=1 wall= 10,121ms  Read notes.txt and tell me what it says. -> "Remember to rotate your logs."
turns=2 tools=2 wall= 21,290ms  List the files and then read each one.
turns=2 tools=1 wall= 10,698ms  Which file is the largest?          -> "The largest file is access.log."
turns=2 tools=1 wall= 12,490ms  Is there a file about rotating logs?
TOTAL turns=12  toolruns=7  wall=82,896ms  mean turn=6,908ms

ثلاث نتائج، والثالثة هي سبب وجود هذا القسم.

انتهت كل مهمة بلا استثناء في دورين بالضبط. لم يُفعّل حد الأدوار، ولم تُفعّل الميزانية، وكان المخرج الوحيد للحلقة هو أن ينتج النموذج نثرًا. نموذج بنصف مليار parameter لا يكرر؛ يجيب في نفسه الثاني سواء كان يملك ما يحتاجه أم لا. عدد الأدوار خاصية للنموذج، لا لحلقتك.

استغرق الدور الوسطي 6,908 ميليثانية، لذا فجدول latency أعلاه ليس لعبة: عند هذا الحجم، تشغيل افتراضي من ثمانية أدوار يقترب من دقيقة wall clock بلا شيء على الشاشة.

والإجابات خاطئة. أكبر ملف هو errors.log؛ سرد النموذج الملفات، ولم يقرأها قط، وسمّى واحدًا على أي حال. خمنت المهمة الأولى اسم ملف، وقيل لها إنه غير موجود، ثم خلصت. نفّذ harness بلا عيب في كل التشغيلات الستة. يجعل harness الـ agent قابلًا للحكم، لا صحيحًا — الفصل 29 هو كيف تعرف أيهما، والفصل 30 هو ما يكلفه الأمر عندما لا يفعل أحد.

يمكن لأداة واحدة في الكتالوج أن يكون خلفها تشغيل آخر. الواجهة هي واجهة الفصل 18 — schema وendpoint — ويناسب agent كامل خلفها لأن تلك الواجهة ضيقة:

const research: Tool = {
  name: "research",
  description: "Investigate one question and return a short summary.",
  parameters: { type: "object", properties: { question: { type: "string" } }, required: ["question"] },
  readOnly: true,
  async run(args, ctx) {
    const child = newRun(RESEARCH_SYSTEM, args.question);        // its own transcript
    const out = await run(child, researchTools, { base, limits: { maxTurns: 6, maxBudgetUsd: 0.05 }, signal: ctx.signal });
    return out.output ?? "no result";
  },
};

ثلاثة أشياء صحيحة بالفعل في تلك الأسطر العشرة، والثلاثة كلها عواقب لقرارات اتُّخذت أعلاه: لدى الطفل نافذته الخاصة، لذلك يتلقى transcript الأب ملخصًا لا كل ما قرأه الطفل؛ ولديه حدوده الخاصة، لذلك لا يستطيع طفل منفلت إنفاق ميزانية الأب؛ ويرث الإشارة، لذلك تلغي نقرة Stop واحدة الشجرة. لماذا تكون النافذة النظيفة هي المقصود لا أثرًا جانبيًا هو الفصل 24؛ وأنماط orchestration الخمسة — prompt chaining، وrouting، وparallelisation، وorchestrator-workers، وevaluator-optimiser — وhandoff هي الفصل 25.

لا ينبغي قراءة أي شيء أعلاه كحجة ضد المكتبات. مقيسًا في 7 سبتمبر 2026، للشهر المنتهي في 29 أغسطس:⁷

سبب كتابة هذه الدورة الحلقة يدويًا بدل تعليم واحدة منها مُعلن لا ضمني، وهو قابل للقياس. في الاثني عشر شهرًا حتى 7 سبتمبر 2026، نشر ai 945 إصدارًا وانتقل من major 5 إلى major 7، وما زالت فئة agent الخاصة به مُصدّرة باسم Experimental_Agent؛ نشر langchain 132 إصدارًا في النافذة نفسها؛ ونشر @openai/agents 83 إصدارًا وما زال على 0.x، بعد خمسة عشر شهرًا من أول إصدار له.⁷ فصل مكتوب مقابل أي من تلك APIs يصبح قديمًا خلال موسم، وهذا الفصل منشور بثلاث وثلاثين لغة، لذا فكل إعادة تحرير تكلف الترجمة كلها. ما تحتها جميعًا لا يتحرك: حلقة، وقاعدة توقف، وكتالوج، ومنفذ، وبعض الحالة.

ويتفق التنفيذ المرجعي مع هذا الفصل في الجزء المهم. في ai الإصدار 7.0.93 مخرج الحلقة ليس رقمًا — إنه stopWhen، قائمة predicates، لا يكون عدّ الخطوات إلا واحدًا منها:³

type StopCondition<TOOLS extends ToolSet> = (options: { steps: Array<StepResult<TOOLS>> }) => PromiseLike<boolean> | boolean;
declare function isStepCount(stepCount: number): StopCondition<any, any>;   // exported as stepCountIs

التوقف جمع في أكثر تنفيذ مستخدم لهذه الحلقة، للسبب نفسه الذي يجعله جمعًا في الأسطر المئة والستة والتسعين أعلاه.

لديك الآن harness: حلقة، وكتالوج، ومنفذ، وخمس طرق للخروج، وتشغيل مستمر، وإشارة تصل إلى الأدوات، وtrace يحمل run id على كل سطر. تبني الفصول 24 و25 و29 و30 على هذا الملف، والفصول 26 إلى 28 على ما يستطيع الوصول إليه.

تبقى له مشكلة واحدة، وكانت القياسات أعلاه تشير إليها طوال الطريق. انظر إلى جدول الانفلات مرة أخرى: 3,431 input tokens عند ثمانية أدوار، و337,299 عند مئة. وانظر إلى التشغيل العامل: 204، 269، 342. كل دور يعيد إرسال transcript كله، لذلك يمتلئ context الخاص بـ agent بتاريخه هو — والنموذج أسوأ في استخدام الطرف البعيد من window طويلة منه في استخدام الطرف القريب، ولهذا يكون agent جيدًا عند الدور الخامس ومرتبكًا عند الدور الأربعين.

حد الأدوار لا يصلح ذلك. إنه يوقفك فقط عن الدفع لمشاهدة حدوثه. ما يصلحه هو أن تقرر، في كل دور بلا استثناء، أي tokens تستحق window: ما الذي تضغطه، وما الذي تنقله إلى ملاحظة يستطيع agent جلبها، وما الذي تسلّمه إلى subagent بنافذة نظيفة، وأي تعريفات أدوات تستحق ضريبتها الدائمة. يقيس الفصل 24 أين تذهب window فعليًا — والمفاجأة أنها ليست المحادثة.

خرج كل رقم في هذا الفصل من الخادمين الموصوفين أعلاه، على Node 22 عبر loopback interface: مزوّد scripted يعدّ tokens بترميز o200k_base، وQwen/Qwen2.5-0.5B-Instruct خلف endpoint بالشكل نفسه، greedy decoding، على CPU. تُحسب التكاليف من أعداد token المقاسة بالأسعار التي قرأها الفصل 16 في 6 سبتمبر 2026 — $2.00 لكل مليون input tokens و$12.00 لكل مليون output — ولم يذهب أي طلب في هذا الفصل إلى endpoint مدفوع. إجابات النموذج المحلي هي إجابات نموذج صغير؛ اقرأها كدليل على الحلقة، وهي متطابقة في الحالتين، لا كـ benchmark لما تفعله النماذج الحالية.