التنفيذ المتين

import { AgentExecutor, LocalStorageCheckpointStore } from '@lousho/build-ai-agent';

const checkpoints = new LocalStorageCheckpointStore(storage);

// First message of a conversation.
await AgentExecutor.execute({ agent, input: 'Book a table for 2 tonight', provider, sessionId: 'chat-42', checkpointStore: checkpoints });

// Later - same process or another one - the next message of the same conversation.
await AgentExecutor.execute({ agent, input: 'Make it 3 people', provider, sessionId: 'chat-42', checkpointStore: checkpoints });

import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({ provider, store: new SqliteStore('./.lousho/jobs.db') });

const finished = await agent.resume('job-1'); // the interrupted run, if any
const next = await agent.send('Now write a summary', { sessionId: 'job-1' }); // continues the same run's conversation

​

ما الذي يُحفظ في نقطة الحفظ، ومتى

​

ما الذي يحدث حين تستدعي execute() مرة أخرى بالـsessionId نفسه

• تشغيل غير مكتمل ('in-progress': تعطّل، أو أُوقف، أو فشلت كتابة في المخزن). يُستأنف التشغيل. إذا كانت دورة النموذج الأخيرة فيه تتضمن استدعاءات أدوات بلا نتيجة، تُنفَّذ تلك الاستدعاءات بعينها أولًا، عبر مسار الأدوات المعتاد (التحقق من المعطيات، والخطّافات، وneedsApproval، وtoolConcurrency)، من دون استدعاء النموذج من جديد. ثم تستمر الحلقة بما تبقّى من ميزانية maxSteps؛ ويستمر usage من الإجماليات المحفوظة في نقطة الحفظ (والأمر نفسه في resumeAfterApproval()، انطلاقًا من اللقطة).
  • يُضاف input الجديد كرسالة مستخدم بعد نتائج تلك الأدوات. ولا يوضع أبدًا بين دورة استدعاء أدوات ونتائجها، فيبقى سجل المحادثة صالحًا لدى كل مزوّد. وهذا ما يتيح للمستخدم أن يقاطع تشغيلًا (بإيقافه) ويعيد توجيهه برسالة جديدة.
  • الـinput الذي يعيد إرسال الرسالة التي بدأ منها التشغيل (وهو التصرف الطبيعي: «أعد الطلب نفسه بعد تعطّل») يُعامَل كإعادة محاولة ولا يُضاف مرة أخرى. وinput: [] كذلك يستأنف فحسب.
• تشغيل منتهٍ ('finished'). تستمر الجلسة كمحادثة: تبقى الرسائل المخزَّنة ويصبح input دورة المستخدم التالية. مرّر الرسالة أو الرسائل الجديدة فقط؛ وإذا أعدت إرسال السجل المخزَّن متبوعًا برسائل جديدة، يُتعرَّف على السجل ولا يُكرَّر. وتُحتسب steps وusage وtoolCalls في النتيجة من الصفر للتشغيل الجديد؛ أما messages فهي المحادثة كاملة.
• متوقف بانتظار موافقة ('awaiting-approval'). ترمي execute() الخطأ SessionAwaitingApprovalError (مع sessionId وapprovalId) ولا تستدعي النموذج ولا أي أداة: فلا يجوز أن يتجاوز مدخل جديد قرارًا معلّقًا. احسمه أولًا بـresumeAfterApproval()، مع تمرير checkpointStore نفسه، ثم أرسل الرسالة الجديدة.

import { AgentExecutor, SessionAwaitingApprovalError } from '@lousho/build-ai-agent';

try {
  await AgentExecutor.execute({ agent, input: 'Are you done?', provider, sessionId: 'chat-42', checkpointStore });
} catch (error) {
  if (error instanceof SessionAwaitingApprovalError) {
    console.log(`Waiting on approval ${error.approvalId} - resolve it with resumeAfterApproval() first.`);
  }
}

​

الموافقات في منتصف دفعة أدوات

1. تسجّل نتيجة الاستدعاء المتوقف: نتيجة الأداة إن وُوفق عليه، أو نتيجة رفض منظَّمة { error, note } إن رُفض؛
2. تنفّذ الاستدعاءات المتبقية بمنطق الدفعة نفسه: فقد تُنفَّذ، أو تفشل في التحقق، أو توقف التشغيل مرة أخرى عند موافقة أخرى (approvalId جديد؛ احسمه بالطريقة نفسها، وبعدد المرات اللازم)؛
3. تستدعي النموذج حالما يصبح لكل استدعاء في الدورة نتيجة واحدة بالضبط.

import { AgentExecutor, resumeAfterApproval } from '@lousho/build-ai-agent';

const paused = await AgentExecutor.execute({
  agent, input, provider, toolRegistry, approvalStore, sessionId: 'chat-42', checkpointStore,
});

if (paused.finishReason === 'awaiting-approval') {
  // ...a human decides, possibly days later, in another process...
  const result = await resumeAfterApproval(
    { id: paused.approvalId!, approved: true },
    approvalStore,
    toolRegistry,
    provider,
    {},
    checkpointStore, // clears the 'awaiting-approval' mark and keeps checkpointing
  );
  console.log(result.finishReason); // 'stop', or 'awaiting-approval' again for the next gated call
}

​

الضمانات

• يحصل كل استدعاء أداة على نتيجة واحدة بالضبط، بترتيب الاستدعاء، بعد أي تتابع من حالات التعطّل والإيقاف والتوقف المؤقت والاستئناف. (الاستدعاء الذي أُوقف يحصل على نتيجة «أُلغي»؛ والاستدعاء المرفوض يحصل على نتيجة رفض.)
• النتيجة المسجَّلة لا يُعاد تنفيذها أبدًا. تُحفظ النتائج في نقاط الحفظ كلما امتدّت سلسلة الاستدعاءات المكتملة المتتالية بترتيبها؛ والتشغيل المستأنف لا ينفّذ إلا الاستدعاءات التي ليست لها نتيجة مسجَّلة.
• دورة النموذج المحفوظة في نقطة حفظ لا تُولَّد من جديد أبدًا. إذا توقفت العملية بعد أن أجاب النموذج، ينفّذ التشغيل المستأنف استدعاءات الأدوات الواردة في تلك الإجابة بدل سؤال النموذج مرة أخرى (فلا تكلفة إضافية ولا خطة مختلفة).
• يتلقى المزوّد دائمًا سجل محادثة صالحًا: نتائج الأدوات تأتي مباشرة بعد دورة استدعاء الأدوات الخاصة بها، ومدخل المستخدم الجديد يأتي بعدها.

​

الأدوات تُنفَّذ مرة واحدة على الأقل: اجعل الآثار الجانبية آمنة عند التكرار

import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

declare const payments: { charge(amount: number, opts: { idempotencyKey: string }): Promise<{ id: string }> };

const chargeCard = defineTool({
  name: 'charge_card',
  description: 'Charge the customer',
  input: z.object({ amount: z.number() }),
  execute: async ({ amount }, { toolCallId }) =>
    payments.charge(amount, { idempotencyKey: toolCallId }), // a re-run cannot charge twice
});

​

السجل التاريخي لنقاط الحفظ

import { getCheckpointHistory, memoryStore } from '@lousho/build-ai-agent';

const { checkpoints } = memoryStore({ historyLimit: 20 }); // default 50, 0 keeps none
// new SqliteStore(path, { historyLimit }), new LocalStorageCheckpointStore(storage, { historyLimit })

// ... after a run with sessionId 'chat-42' ...
const history = await getCheckpointHistory(checkpoints, 'chat-42', { limit: 10 });
for (const { step, savedAt, status, checkpoint } of history ?? []) {
  console.log(step, status, savedAt, checkpoint.messages.length);
}

// Clear the checkpoint but keep its history (by default delete() clears both).
await checkpoints.delete('chat-42', { keepHistory: true });

• تعيد history(sessionId, { limit? }) مدخلات بالشكل { step, savedAt, status, checkpoint }، الأحدث أولًا (step هو checkpoint.stepIndex، وsavedAt طابع زمني بصيغة ISO، وstatus يكون 'in-progress' لنقطة حفظ لا تحمل حالة). يحفظ المنفِّذ بعد كل دورة نموذج وكل دفعة أدوات، فللجلسة مدخل واحد لكل عملية حفظ؛ والمدخلات تحتوي نقاط حفظ كاملة، فاخفض historyLimit لسجلات المحادثة الطويلة. والجلسة غير المعروفة تعطي [].
• الدالة history اختيارية في CheckpointStore: المخزن المخصَّص الذي لا يوفّرها يواصل العمل، وتعيد له getCheckpointHistory() القيمة undefined بدل أن ترمي خطأً.
• يحتفظ KVCheckpointStore بمفتاح فهرس واحد لكل جلسة (<prefix><sessionId>#history، وفيه معرّفات المدخلات من الأقدم إلى الأحدث) وبمفتاح واحد لكل مدخل (<prefix><sessionId>#history/<id>)، فلا تكبر أي قيمة مع نمو السجل التاريخي؛ وتبقى أحدث نقطة حفظ عند <prefix><sessionId>، فالمخزن المكتوب قبل وجود السجل التاريخي يُحمَّل كما كان. عملية الحفظ تكتب نقطة الحفظ، ثم المدخل، ثم الفهرس، ثم تحذف المدخلات التي أسقطتها: فالتعطّل بين كتابتين يترك في أسوأ الأحوال مدخلًا غير مدرج في الفهرس (تنتهي صلاحيته مع TTL)، ولا يترك أبدًا مخزنًا تتعذّر قراءته. لا يدعم KV المعاملات (transactions)، فقد تفقد عمليتا حفظ متزامنتان لجلسة واحدة تحديثًا واحدًا للفهرس (فيغيب ذلك المدخل عن history())، وقد يغيب مدخل لبعض الوقت في موقع طرفي (edge) آخر (اتساق نهائي؛ وhistory() تتخطاه). وجِّه طلبات الجلسة إلى موقع واحد حين يكون ذلك مهمًا. كل عملية حفظ تكلّف عملية get واحدة وعمليتي put إضافية؛ وhistoryLimit: 0 يعطّل ذلك.
• مخزن الملفات في Agent Forge يكتب السجل التاريخي ملفًا واحدًا لكل جلسة (.lousho/agents/<id>/checkpoint-history/<session>.json، ويُستبدل استبدالًا ذرّيًا)؛ والملف الذي أتلفه تعطّل يُقرأ كأنه بلا سجل تاريخي ويعيد الحفظ التالي بناءه.
• يحتفظ SqliteStore بالسجل التاريخي في جدول جديد checkpoint_history، يُضاف عند فتح ملف قاعدة بيانات موجود؛ وprune() تزيل أيضًا مدخلات السجل التاريخي الأقدم من حدّها الزمني.

​

التفريع وإعادة التشغيل

import { AgentExecutor, compareTrajectories, memoryStore } from '@lousho/build-ai-agent';

const { checkpoints } = memoryStore();
await AgentExecutor.execute({ agent, provider, toolRegistry, input: 'Plan my trip', sessionId: 'trip', checkpointStore: checkpoints });

const fork = await AgentExecutor.fork({
  sessionId: 'trip',
  fromStep: 1,
  checkpointStore: checkpoints,
  patch: { toolResult: { toolCallId: 'call_weather', result: { forecast: 'rain' } } },
});
// fork.sessionId is 'trip.fork-1'; the 'trip' checkpoint and history are unchanged.
await AgentExecutor.execute({ agent, provider, toolRegistry, input: [], sessionId: fork.sessionId, checkpointStore: checkpoints });

const original = await checkpoints.load('trip');
const replayed = await checkpoints.load(fork.sessionId);
if (original && replayed) {
  const { divergedAt, a, b, drift } = compareTrajectories(original, replayed);
  console.log(divergedAt, a.length, b.length, drift); // 1, then each run's steps and the tool-call diff
}

import { createAgent, memoryStore } from '@lousho/build-ai-agent';

const assistant = createAgent({ provider, store: memoryStore() });
await assistant.send('Plan my trip', { sessionId: 'trip' });
const fork = await assistant.fork('trip', { fromStep: 1, patch: { appendInput: 'It will rain, plan for that.' } });
const result = await assistant.resume(fork.sessionId);

• يُطبَّق patch بهذا الترتيب: messages(messages) تعيد كتابة سجل المحادثة؛ وbusinessState يحلّ محلّ القيمة المحفوظة؛ وtoolResult: { toolCallId, result } يستبدل نتيجة ذلك الاستدعاء في مكانها (الموضع نفسه ومعرّف الاستدعاء نفسه واسم الأداة نفسه، فيبقى سجل المحادثة صالحًا لدى كل مزوّد)، أو يسجّلها حين لا تكون للاستدعاء نتيجة بعد؛ وappendInput يضع رسالة مستخدم في الانتظار، تُرسل بعد أي استدعاءات أدوات ما زالت معلّقة.
• تحتفظ التفريعة بعدد خطوات نقطة الحفظ المصدر وباستهلاكها، فينطبق عليها ما تبقّى من ميزانية maxSteps. نتائج الأدوات المسجَّلة لا يُعاد تنفيذها؛ واستدعاءات الأدوات التي بلا نتيجة تُنفَّذ أولًا، كما في أي استئناف (فتفريعة من مدخل بالحالة 'awaiting-approval' تمرّ عبر needsApproval من جديد؛ ولا يُنقل approvalId القديم).
• يسمّي newSessionId التفريعة؛ والافتراضي <sessionId>.fork-<n> حيث n أول عدد ليست له نقطة حفظ. ويُرفض newSessionId الذي له نقطة حفظ أصلًا.
• الخطوة غير الموجودة في السجل التاريخي (الجلسة غير معروفة، أو الخطوة لم تُنفَّذ قط، أو أُسقطت لتجاوزها historyLimit) ترمي SDKError برمز الخطأ LOUSHO_CHECKPOINT_NOT_FOUND، ورسالته تسرد الخطوات المحفوظة. والمخزن الذي بلا history() لا يمكن التفريع منه (ConfigurationError).
• تأخذ compareTrajectories(a, b) نقطتي حفظ أو سجلَّي محادثة وتعيد خطوات كل تشغيل (خطوة لكل دورة للمساعد: نصها واستدعاءات أدواتها مع نتائجها)، وdivergedAt (أول خطوة تختلف، بصرف النظر عن معرّفات استدعاءات الأدوات)، وdrift، وهو الفروق في ترتيب الأدوات والمعطيات وعدد الخطوات وسبب الانتهاء، بالبنية نفسها التي يخرجها lousho eval --drift.

​

الاستئناف بوكيل تغيَّر

import { createAgent, memoryStore } from '@lousho/build-ai-agent';
import type { LLMProvider } from '@lousho/build-ai-agent';

declare const provider: LLMProvider;

// After a deploy that renamed a tool or changed the model, refuse to continue old runs.
const agent = createAgent({ provider, store: memoryStore(), onAgentDrift: 'error' });
const result = await agent.resume('job-1');

• نقاط الحفظ واللقطات المكتوبة قبل وجود هذه الميزة ليست لها بصمة، وتُستأنف تمامًا كما في السابق، بلا تحذير.
• تشغيل وكيل ديناميكي يحفظ ctx والنموذج الذي اختاره في نقطة الحفظ (runConfig)، ويستخدمهما الاستئناف بعد تعطّل: النموذج المحفوظ، وأدوات وتعليمات تُحسب من جديد بالـctx المحفوظ (وكان الحساب قبل ذلك يجري بـinput: [] وبلا metadata).
• تغطي البصمة أدوات الوكيل نفسه ونموذجه وتعليماته، لا الأدوات التي تضيفها subagents وskills. والوكيل الفرعي الذي يتوقف بانتظار موافقة له بصمته الخاصة في لقطته المتداخلة، لكن الاستئناف لا يقارن إلا وكيل المستوى الأعلى.
• التشغيل المستأنف بعد موافقة يواصل بالتعليمات التي بدأ بها (فهي في سجل محادثته)، ولذلك تسجّل نقاط حفظه اللاحقة تلك التعليمات.

​

التوافق مع البيانات المخزَّنة

• نقاط الحفظ المكتوبة قبل وجود status تُعامَل على أنها 'in-progress' (فقبل هذا التغيير كانت التشغيلات المنتهية تحذف نقطة حفظها، فلم يكن يُخزَّن إلا التشغيلات غير المكتملة).
• الجلسات المحفوظة قبل أن يحتفظ المخزن بسجل تاريخي يبقى سجلها التاريخي فارغًا حتى الحفظ التالي.
• لقطات الموافقة المكتوبة قبل وجود remainingToolCalls تُستأنف كما كانت تُستأنف: لا تُنفَّذ الاستدعاءات التي تلي الاستدعاء المتوقف. ويحصل كل منها على نتيجة خطأ تفيد بأنه لم يُنفَّذ، فيبقى سجل المحادثة صالحًا.

​

القيود

• يعرّف sessionId محادثة منطقية واحدة؛ وتشغيل استدعاءين لـexecute() على المعرّف نفسه في الوقت نفسه غير مدعوم.
• إذا استدعيت resumeAfterApproval() من دون checkpointStore، تحتفظ الجلسة بعلامة 'awaiting-approval' وتظل استدعاءات execute() اللاحقة ترمي SessionAwaitingApprovalError؛ مرّر المخزن (أو احذف نقطة الحفظ).
• Workers KV متّسق اتساقًا نهائيًا (eventual consistency) عبر المواقع؛ انظر النشر لمعرفة تفاصيل هذا التحفّظ.