Agent harness بنائیں: loop اور اس سے نکلنے کے پانچ راستے

Chapter 14 کسی real provider کے خلاف نہیں لکھا جا سکتا تھا، کیونکہ آپ کسی provider سے chosen moment پر 429 نہیں مانگ سکتے۔ اس chapter کو وہی مسئلہ ایک مختلف شکل میں ہے: آپ real model سے demand اور reproducibly یہ نہیں کہہ سکتے کہ runaway ہو جائے، یا لگاتار دو بار identical tool request کرے۔

اس لیے پہلا program ایک scripted provider ہے: chat completions API کی شکل کا endpoint جس کا reply turn index اور tools کے اب تک واپس کیے گئے results کا function ہے۔ یہ real byte-pair encoder سے tokens count کرتا ہے، اس لیے نیچے والا money decoration نہیں بلکہ arithmetic ہے۔

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);

دو lines design اٹھاتی ہیں۔ turn index conversation سے derived ہے، variable میں held نہیں، اس لیے provider stateless ہے اور run کو kill کر کے اس کے خلاف resume کیا جا سکتا ہے۔ اور recover فیصلہ کرنے سے پہلے tool results پڑھتا ہے: scripted model جو اپنا transcript پڑھتا ہے، یہ measure کرنے کے لیے minimum ہے کہ harness نے اسے کچھ پڑھنے کے قابل دیا بھی یا نہیں۔

catalogue Chapter 18 کا ہے، تین files پر چار tools: list_files، read_file، delete_file — needsApproval marked — اور scan_archive، جو جان بوجھ کر slow ہے۔

یہ پوری idea ہے، ان تمام parts سے پہلے جو اسے survivable بناتے ہیں۔

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 provider کی طرف point کریں اور یہ بالکل وہی کرتا ہے جو دکھتا ہے:

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

تین turns، دو tool executions، ایک US cent کا چوتھائی حصہ۔ آخری line نوٹ کریں: 204، 269، 342۔ ہر turn اپنے سے پہلے سب کچھ دوبارہ بھیجتا ہے، یعنی Chapter 16 کا quadratic bill ایسی جگہ آ گیا جہاں کسی نے کچھ type بھی نہیں کیا۔ اس chapter کا باقی حصہ یہ ہے کہ جب وہ line بڑھنا بند نہیں کرتی تو کیا ہوتا ہے۔

اسی loop کو runaway script کی طرف point کریں — ایک model جو ہر single turn پر tool مانگتا ہے اور کبھی prose emit نہیں کرتا — اور marked return کبھی fire نہیں ہوتا۔ کوئی اور exit نہیں۔ program چلتا رہتا ہے جب تک process مر نہ جائے یا credit card۔

fix ایک line ہے، literature جس first control کی recommendation دیتی ہے وہی،⁵ اور آخرکار سب اسے لکھتے ہیں۔ جو تقریباً کوئی نہیں کرتا، وہ یہ measure کرنا ہے کہ اس کی value کیا ہے:

آخری دو rows کو ساتھ پڑھیں۔ cap کو 50 سے 100 double کرنے سے cost double نہیں ہوئی؛ یہ 3.7 گنا ہو گئی۔ input tokens 88,649 سے 337,299 ہو گئے، 3.8 کا factor، کیونکہ turn $n$ اپنے ساتھ ہر previous turn اٹھاتا ہے اور total $\Theta(n^2)$ ہے۔ turn cap linear dial نہیں۔ یہ آپ کے worst case کے square root پر dial ہے، اسی لیے 20 سے 100 “صرف safe رہنے کے لیے” بڑھانا ایسا decision ہے جس کی قیمت پہلے لگانی چاہیے۔

turn cap کا مسئلہ یہ ہے کہ turn کی fixed price نہیں ہوتی۔ short transcript پر twenty turns اوپر $0.038 کے تھے۔ 200-tool catalogue، retrieved document set اور history کے چالیس messages کے ساتھ twenty turns اس سے hundreds of times cost کرتے ہیں، اور cap کو پتا نہیں چلتا۔ operator جس چیز کو bound کرنا چاہتا ہے وہ bill ہے۔

اس لیے loop money count کرتا ہے، Chapter 16 کے computeCost کو وہاں پڑھی گئی rates کے خلاف استعمال کرتے ہوئے — $2.00 per million input tokens اور $12.00 per million output، اس model کے لیے جسے پورے course میں price کیا گیا ہے:

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);

وہی runaway script، کوئی turn cap بالکل نہیں، تین budgets:

دو چیزوں کو نام دینا ضروری ہے۔ پہلی، budget ہر بار different number of turns خریدتا ہے، اور یہی point ہے: یہ اس چیز کو bound کر رہا ہے جس کی operator کو پروا ہے، اور turn count کو وہاں گرنے دے رہا ہے جہاں transcript اسے رکھتا ہے۔ دوسری، ہر row overshoot کرتی ہے۔ budget $0.010 تھا اور $0.010780 spent ہوا، کیونکہ check turn سے پہلے چلتا ہے اور turn کی price ختم ہونے تک معلوم نہیں ہوتی۔ آپ spend کو exactly bound نہیں کر سکتے؛ آپ اسے ایک turn کی cost کے اندر bound کر سکتے ہیں۔ interface میں یہی کہیں، pretend نہ کریں، اور check call سے پہلے رکھیں تاکہ overshoot ایک turn ہو، دو نہیں۔

اب loop کے تین exits ہیں، اور باقی chapter کی shape visible ہے۔ production run exactly پانچ ways میں سے ایک میں end ہوتا ہے، اور یہ ایک دوسرے کی variations نہیں:

ان سب کو ایک boolean میں collapse کرنا اس file کی سب سے common design mistake ہے، اور یہ ایک specific way میں expensive ہے: پانچ میں سے تین resumable ہیں اور دو نہیں۔ جس agent نے اپنا turn cap hit کیا، اس کے پاس valid transcript، real partial result اور next step ہے؛ جس agent کو 401 ملا، اس کے پاس ان میں سے کچھ نہیں۔ اس لیے harness reason کو data کے طور پر record کرتا ہے:

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 };

Chapter 18 ایک claim پر ختم ہوا تھا جس کے ساتھ number نہیں تھا: tool کا error raise کرنے کے بجائے tool result کے طور پر model کو واپس دیں، اور model عموماً خود کو fix کر لیتا ہے۔ یہ رہا number۔

ایک failure، تین policies۔ scripted model ایک ایسی file guess کرتا ہے جو exist نہیں کرتی؛ tool no such file: timeout.log. Call list_files to see what exists. throw کرتا ہے

تیسری row پہلی سے 4.7 times cost کرتی ہے اور وہی واحد ہے جو question کا answer دیتی ہے۔ اور دوسری row interesting ہے، کیونکہ یہی زیادہ تر codebases actually کرتی ہیں: error caught ہوا، loop survived، model کو بتایا گیا کہ کچھ fail ہوا، کیا fail ہوا نہیں، اور اس نے شائستگی سے give up کر دیا۔ rows two اور three کا فرق error handling نہیں۔ یہ reader کے لیے لکھی گئی ایک sentence ہے۔

لہٰذا harness thrown tool کو data سمجھتا ہے، اور wording کو policy بناتا ہے:

} 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);   
}

Chapter 18 نے دوسری side کے بارے میں بھی warn کیا تھا، اور اس کی بھی price ہے۔ loop کو ایسے tool کی طرف point کریں جو ایسی وجہ سے fail ہوتا ہے جسے کوئی message fix نہیں کر سکتا — ایسی read جسے process perform کرنے کی اجازت نہیں — اور model اسے ہمیشہ retry کرتا رہتا ہے:

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

ایک ایسی call کی eleven identical executions جو succeed نہیں کر سکتی، اس run کی cost سے 5.2 times جس نے fixable error سے recover کیا، اور آخر میں کچھ نہیں۔ Errors context ہیں؛ permanent error ایسا context ہے جو باقی run کو poison کر دیتا ہے۔ distinction Chapter 14 کی status triage ہے جو ایک layer اوپر move ہوئی ہے: ایسا error جس پر model act کر سکتا ہے transcript میں واپس جاتا ہے، اور ایسا error جس پر وہ act نہیں کر سکتا run کو reason کے ساتھ stop کرنا چاہیے۔ آج turn cap ہی آپ اور دوسرے case کے درمیان کھڑا ہے، جو floor ہے fix نہیں۔

اب وہ failure جسے اکثر لوگ assume کرتے ہیں کہ ہو ہی نہیں سکتا۔ Models خود کو repeat کرتے ہیں۔ کسی بھی loop کو کافی دیر چلائیں اور آپ identical tool کو identical arguments کے ساتھ دو consecutive turns پر دیکھیں گے۔

اسی task کے baseline کے خلاف measured، repeat کے بغیر:

duplicated call نے $0.001050 extra cost کیا، 75 % increase، اور یہ حصہ لوگوں کو surprise کرتا ہے: result cache کرنے سے اس میں سے کچھ بھی recover نہیں ہوا۔ Deduplication نے tool execution بچائی، turn نہیں، کیونکہ جب تک آپ کا code repeat notice کرتا ہے model کو asking کے لیے already pay کیا جا چکا ہوتا ہے۔ saving real ہے جب tool slow، rate-limited، یا per-call billed ہو — اور اس line item پر zero ہے جو بڑھی۔

اس سے worse version ہے۔ یہی cache ایسے tool پر apply کریں جو write کرتا ہے، اور second call silently نہیں ہوتی:

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"]

ان میں سے کون correct ہے؟ کوئی بھی نہیں، knowably۔ protocol کہتا ہے یہ دو calls ہیں: یہ دو different tool_call_id values carry کرتی ہیں۔ arguments کہتے ہیں شاید یہ ایک ہوں۔ ایسا harness جو argument strings compare کر کے decide کرتا ہے ایک دن two identical, intended charges میں سے second کو swallow کر جائے گا — اور Chapter 14 already اس واحد mechanism کا نام دے چکا ہے جو اسے honestly resolve کرتا ہے، یعنی idempotency key جو logical operation کے لیے اس layer سے generate ہوتی ہے جو جانتی ہے کہ operation ہے کیا۔ جب تک tool کے پاس وہ نہ ہو، defensible default اوپر والا read-only gate ہے: reads cache کریں، writes execute کریں، اور write کی اپنی idempotency کو باقی handle کرنے دیں۔

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;
}

destructive script files list کرتی ہے اور پھر ایک ایسی file delete کرنے کو کہتی ہے جس کا task نے کبھی mention نہیں کیا۔ loop میں اب تک کچھ بھی اسے روکنے والا نہیں تھا۔

needsApproval marked tool نہ fail ہوتا ہے نہ proceed کرتا ہے۔ یہ run stop کرتا ہے اور control return کرتا ہے، ہر چیز کے ساتھ جو ایک person کو decide کرنے کے لیے چاہیے:

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."

یہ پورا mechanism ہے، اور وجہ کہ یہ callback کے بجائے return ہے اگلا section ہے: stop اور verdict کے درمیان process شاید exist ہی نہ کرے۔

لیکن پہلے، وہ measurement جس کی کسی کو توقع نہیں۔ rejection result کی absence نہیں — transcript میں tool_call_id سے keyed slot ہے اور اس میں کچھ نہ کچھ جانا ہے۔ same rejection کو دو بار run کریں، صرف یہ بدلتے ہوئے کہ وہ چیز کیا کہتی ہے:

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."

دونوں runs میں کچھ delete نہیں ہوا، اور second میں user کو بتایا گیا کہ ہو گیا۔ permission system perfect کام کیا؛ report جھوٹ ہے۔ یہ tool-error table جیسا ہی mechanism ہے، مگر ایسی جگہ پہنچا جہاں matter کہیں زیادہ ہے — human نے no کہا، action correctly blocked ہوا، اور agent کی summary reality سے contradict کرتی ہے کیونکہ refusal کبھی وہاں written نہیں ہوئی جہاں model پڑھتا ہے۔ اس سے نکلنے والا rule short ہے: آپ کا code tool call کے بارے میں جو بھی decide کرے، decision کو transcript میں words میں لکھیں۔ Chapter 30 security side سے اس پر واپس آتا ہے، جہاں یہ audit trail اور fiction کا فرق ہے۔

approval میں minutes یا hours لگتے ہیں۔ deploy میں seconds۔ اگر run کسی HTTP request کے اندر local variable میں رہتا ہے، تو ہر restart lost run ہے اور ہر approval race ہے۔

اس لیے run closure نہیں۔ یہ plain serialisable object ہے — messages، turn count، cost، status، interruption، approved call ids کی list — اور loop اس پر pure function ہے۔ یہی single constraint persistence کو one-line concern بناتا ہے:

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"));

correctness question saving نہیں۔ یہ ہے کہ واپس آتے وقت کیا ہوتا ہے، اور naive answer آپ سے double-charge کراتا ہے۔ اگر process اس کے بعد مر گیا کہ model نے tool مانگا مگر result written ہونے سے پہلے، تو resume اگر model کو دوبارہ call کر کے start کرے تو ایسے turn کے لیے pay کرتا ہے جو اس کے پاس already ہے — اور اگر tools دوبارہ run کر کے start کرے تو write twice perform کرتا ہے۔

fix یہ ہے کہ loop شروع میں transcript سے پوچھے کہ outstanding کیا ہے:

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));    
}

ہر iteration پہلے pending drain کرتی ہے اور model سے تب ہی پوچھتی ہے جب کچھ outstanding نہ ہو۔ Resume normal path جیسا ہی code path بن جاتا ہے، اور approval بھی — approved call simply pending call ہے جو اب run کرنے کی allowed ہے۔ process کو mid-task kill کریں اور restart کریں:

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

ایسے task کے لیے two processes میں two tool executions جسے two ہی چاہیے، اور final cost اس run جیسی identical ہے جو کبھی crash نہیں ہوا۔ Cost restart کے across accumulate ہوتی ہے کیونکہ یہ state میں تھی، variable میں نہیں۔

scan_archive یہاں three seconds لیتا ہے اور production میں three minutes لینے والے tool کی نمائندگی کرتا ہے۔ چلتے وقت دو چیزیں missing ہیں: user کو اندازہ نہیں کہ کچھ ہو رہا ہے، اور Stop button کچھ نہیں کرتا۔

دونوں کی fix ایک ہی ہے، اور یہ Chapter 14 کا AbortSignal ایک level deeper push کیا گیا ہے۔ signal صرف fetch کے لیے نہیں — اسے tool کے اندر pass کیا جاتا ہے، اور well-written tool اسے honour کرتا ہے:

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"

click سے stop تک two milliseconds، کیونکہ tool کے اندر sleep اسی signal کو listen کرتی ہے جسے fetch کرتی ہے۔ اسے صرف fetch میں thread کریں اور identical Stop button three seconds wait کرتا ہے — tool کی length — اور run “cancels” تب ہوتا ہے جب جس work کو cancel کر رہا تھا وہ already finish ہو چکا ہوتا ہے۔ Cancellation جو all the way down plumb نہیں ہوئی، ایک spinner ہے جو صحیح word کہتا ہے۔

harness ہر event پر ایک line emit کرتا ہے، اور vocabulary اتنی small ہے کہ memorise کی جا سکتی ہے: 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}

تین properties اسے logging کے بجائے trace بناتی ہیں۔ ہر line run id carry کرتی ہے، اس لیے ایسا run جو تین processes اور دو دن span کرے ایک query ہے۔ ہر turn line اپنے token counts اور running cost carry کرتی ہے، اس لیے “اس run پر forty dollars کیوں لگے” بعد میں answerable ہے، صرف theory میں reproducible نہیں۔ اور run_stopped reason carry کرتا ہے، وہ field جو support ticket کو one-line answer میں بدل دیتا ہے: budget پر رکا ہوا agent اور crashed agent باہر سے identical لگتے ہیں اور opposite responses require کرتے ہیں۔

Chapter 13 نے آپ کے own hardware پر time to first token measure کیا۔ Chapter 14 نے اسے socket کے through measure کیا۔ agent اسے multiply کرتا ہے، اور multiplier ایک ایسا number ہے جو کسی نے choose نہیں کیا:

وہی three-turn task، صرف provider کی latency بدلتے ہوئے:

harness خود three-turn run میں fifteen milliseconds contribute کرتا ہے۔ باقی سب $N$ ہے، ایسے number سے multiplied جس پر آپ control نہیں رکھتے — serving scheduler کے اندر set ہوتا ہے جو آپ کی request کو strangers کی requests کے ساتھ batch کر رہا ہے⁶ — اور $N$ model choose کرتا ہے۔ اسی لیے Chapter 14 کی streaming یہاں chat سے زیادہ matter کرتی ہے اور کم help کرتی ہے: آپ final turn stream کر سکتے ہیں، اور اس سے پہلے کے four turns silence ہیں جب تک harness progress emit نہ کرے۔ یہی اوپر والے tool_progress event کی پوری argument بھی ہے — agent میں feedback کی honest unit token نہیں، step ہے۔

اوپر کی ہر چیز scripted provider کے خلاف چلی، جو harness prove کرتی ہے اور models کے بارے میں کچھ prove نہیں کرتی۔ تو ایک line بدلیں — Chapter 14 کا seam، LLM_BASE_URL — اور identical code کو local Qwen2.5-0.5B-Instruct کی طرف point کریں، same four tools کے ساتھ۔ same three files پر six tasks:

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

تین findings، اور third ہی اس section کی وجہ ہے۔

ہر single task exactly two turns میں finish ہوا۔ turn cap کبھی fire نہیں ہوا، budget کبھی fire نہیں ہوا، اور loop کا only exit model کا prose produce کرنا تھا۔ half-billion-parameter model iterate نہیں کرتا؛ یہ اپنی second breath پر answer دے دیتا ہے، چاہے اس کے پاس جو چاہیے ہو یا نہ ہو۔ turn count model کی property ہے، آپ کے loop کی نہیں۔

mean turn نے 6,908 milliseconds لیے، اس لیے اوپر والی latency table toy نہیں: اس size پر hypothetical eight-turn run screen پر کچھ بھی نہ ہونے کے ساتھ تقریباً ایک minute wall clock ہے۔

اور answers غلط ہیں۔ largest file errors.log ہے؛ model نے files list کیں، انہیں کبھی read نہیں کیا، اور پھر بھی ایک کا نام لے دیا۔ first task نے file name guess کیا، بتایا گیا کہ وہ exist نہیں کرتی، اور conclude کر دیا۔ harness نے all six runs میں flawlessly execute کیا۔ harness agent کو governable بناتا ہے، correct نہیں — Chapter 29 یہ معلوم کرنے کا طریقہ ہے کہ کون سا، اور Chapter 30 یہ کہ جب کسی نے نہ کیا تو cost کیا ہے۔

catalogue میں ایک tool اپنے پیچھے another run رکھ سکتا ہے۔ interface Chapter 18 کا ہے — schema اور endpoint — اور پورا agent اس کے پیچھے fit ہو جاتا ہے کیونکہ interface narrow ہے:

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";
  },
};

ان ten lines میں تین چیزیں already right ہیں اور تینوں اوپر کیے گئے decisions کے consequences ہیں: child کے پاس اپنی window ہے، اس لیے parent کے transcript کو summary ملتی ہے، وہ سب کچھ نہیں جو child نے read کیا؛ اس کے پاس اپنی limits ہیں، اس لیے runaway child parent کا budget spend نہیں کر سکتا؛ اور یہ signal inherit کرتا ہے، اس لیے ایک Stop tree cancel کر دیتا ہے۔ clean window point کیوں ہے side effect نہیں، یہ Chapter 24 ہے؛ five orchestration patterns — prompt chaining، routing، parallelisation، orchestrator-workers، evaluator-optimiser — اور handoff Chapter 25 ہیں۔

اوپر کی کسی بھی بات کو libraries کے خلاف argument نہیں سمجھنا چاہیے۔ 7 September 2026 کو measured، 29 August کو ختم ہونے والے month کے لیے:⁷

یہ course ان میں سے کسی ایک کو teach کرنے کے بجائے loop ہاتھ سے کیوں لکھتا ہے، وجہ implied نہیں بلکہ declared ہے، اور measurable ہے۔ 7 September 2026 تک کے twelve months میں، ai نے 945 versions publish کیے اور major 5 سے major 7 پر move کیا، اور اس کی agent class ابھی بھی Experimental_Agent کے طور پر exported ہے؛ langchain نے اسی window میں 132 versions publish کیے؛ @openai/agents نے 83 publish کیے اور اپنی first release کے پندرہ months بعد بھی 0.x پر ہے۔⁷ ان APIs میں سے کسی کے خلاف لکھی گئی chapter ایک season میں stale ہو جاتی ہے، اور یہ one thirty-three languages میں publish ہوتی ہے، اس لیے ہر re-edition پوری translation کو cost کرتی ہے۔ ان سب کے نیچے جو ہے وہ move نہیں کرتا: loop، stopping rule، catalogue، executor، کچھ state۔

اور reference implementation اس chapter سے اس part پر agree کرتی ہے جو matter کرتا ہے۔ ai version 7.0.93 میں loop کا exit number نہیں — یہ stopWhen ہے، predicates کی list، جن میں step count صرف ایک ہے:³

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

اس loop کی most-used implementation میں stopping plural ہے، اسی reason سے جس سے اوپر کی hundred and ninety-six lines میں plural ہے۔

اب آپ کے پاس harness ہے: loop، catalogue، executor، نکلنے کے پانچ راستے، persisted run، signal جو tools تک پہنچتا ہے، اور trace جس کی ہر line پر run id ہے۔ Chapters 24، 25، 29 اور 30 اس file پر build کرتے ہیں، اور 26 سے 28 اس پر جس تک یہ پہنچ سکتی ہے۔

اس کا ایک problem باقی ہے، اور اوپر کی measurements پورے راستے اسی کی طرف point کر رہی تھیں۔ runaway table کو ایک بار پھر دیکھیں: eight turns پر 3,431 input tokens، hundred پر 337,299۔ working run دیکھیں: 204، 269، 342۔ ہر turn پورا transcript resend کرتا ہے، اس لیے agent کا context اپنی own history سے fill ہو جاتا ہے — اور model long window کے far end کو near end سے worse use کرتا ہے، اسی لیے turn five پر اچھا agent turn forty پر confused ہو جاتا ہے۔

turn cap اسے fix نہیں کرتا۔ یہ صرف آپ کو اس منظر کی payment سے روکتا ہے۔ اسے fix کرنے والی چیز ہر single turn پر decide کرنا ہے کہ کون سے tokens window کے deserve ہیں: کیا compact کرنا ہے، کیا agent کے fetch کر سکنے والے note میں باہر move کرنا ہے، clean window والے subagent کو کیا hand کرنا ہے، اور کون سی tool definitions اپنے permanent tax کے قابل ہیں۔ Chapter 24 measure کرتا ہے کہ window actually کہاں جاتی ہے — اور surprise یہ ہے کہ conversation نہیں۔

اس chapter میں ہر number اوپر described two servers سے آیا، Node 22 پر loopback interface کے through: scripted provider جو o200k_base encoding سے tokens count کرتا ہے، اور Qwen/Qwen2.5-0.5B-Instruct same shape کے endpoint کے پیچھے، greedy decoding، CPU پر۔ Costs measured token counts سے compute کیے گئے، ان rates پر جو Chapter 16 نے 6 September 2026 کو read کیے — $2.00 per million input tokens اور $12.00 per million output — اور اس chapter میں کوئی request paid endpoint تک نہیں گئی۔ local model کے answers small model کے answers ہیں؛ انہیں loop کے بارے میں evidence سمجھیں، جو دونوں ways میں identical ہے، نہ کہ current models کیا کرتے ہیں اس کا benchmark۔