مرجع Runtime API

اربط الدوال بإجراءات المستخدم

احتفظ بنسخة Runtime واحدة، ومرّر كل نتيجة عبر معالج الحالات الخمس. إضافة HTTP Handler يستدعي invoke() وحدها لا تكفي لدعم المحادثة ومتابعة خطواتها.

اربط كل إجراء بالدالة المناسبة: أرسل الرسائل إلى chat()، والعمليات المعروفة إلى invoke()، واختيار المستخدم إلى select()، وموافقته إلى confirm()، وإلغاءه إلى cancel(). تحقق من هوية المستخدم في كل Handler وحدد الـ Session المرتبطة به. تُستخدم الـ IDs التي تعيدها النتائج لمتابعة العملية، ولا تُعد بيانات اعتماد.

افصل إعداد Runtime عن Input كل استدعاء

عند إنشاء الـ Runtime، حدد configPath والـ Provider Adapters والـ Stores ونمط العرض الافتراضي. أما الرسالة وarguments والـ Token الخاص بالمستخدم وcontext وإشارة الإلغاء، فمرّرها مع كل استدعاء. لا تمرّر config وconfigPath معًا؛ سيؤدي ذلك إلى خطأ.

أمثلة الدوال أدناه مقاطع تدمجها في تطبيقك. يجب أن تأتي قيم sessionId وtoken وmessage وchoice وsignal من Handlers تتحقق من صلاحية المستخدم. لبرنامج مستقل بقيم فعلية واختبارات تحقق، استخدم مثال الحجز.

قبل الإطلاق، اختبر تكرار Confirmation وانتهاء Selection والإلغاء وتغيّر Config. عدم رمي استثناء لا يعني اكتمال العملية؛ افحص result.status.

تُعرّف الواجهات المصدّرة في src/v2/index.ts.

إنشاء Runtime

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});

تدعم RuntimeOptions الخيارات التالية:

interface RuntimeOptions {
  config?: unknown;
  configYml?: string;
  configPath?: string;
  model?: ModelAdapter;
  presentationModel?: ModelAdapter;
  sessionStore?: SessionStore;
  rateLimiter?: RateLimiter;
  retriever?: ToolRetriever;
  authentication?: AuthenticationOptions;
  fetch?: typeof fetch;
  env?: NodeJS.ProcessEnv;
  onEvent?: RuntimeHook;
  presentation?: "raw" | "ai" | "both";
  debug?: boolean;
  now?: () => Date;
}

يُسمح بمصدر إعدادات واحد فقط.

chat()

const result = await runtime.chat({
  sessionId,
  message: "Show available appointments tomorrow",
  auth: { token },
  context: { tenant: { id: "t_1" } },
  presentation: "both",
  signal,
});

المتطلبات:

• رسالة نصية غير فارغة.
• حد أقصى قدره 20 ألف محرف في التنفيذ الحالي.
• Model Adapter محدد في الـ Config أو ممرّر عند إنشاء الـ Runtime.
• Session ID يستخدم المحارف المسموحة.

invoke()

const result = await runtime.invoke({
  sessionId,
  tool: "search-services",
  arguments: { q: "hair" },
  auth: { token },
});

استخدمها عندما يعرف التطبيق المضيف الـ Tool مسبقًا. لا يحتاج التنفيذ الخام إلى AI Model.

select()

const result = await runtime.select({
  sessionId,
  selectionId,
  choice,
  auth: { token },
});

يجب أن يكون Selection موجودًا ولم تنتهِ صلاحيته، وأن يطابق بصمة الـ Session والسياق الحاليين، وأن يستخدم ID لخيار متاح حاليًا.

confirm()

const result = await runtime.confirm({
  sessionId,
  confirmationId,
  auth: { token },
});

يجب أن يطابق Confirmation العملية المجهّزة الحالية، وأن تبقى بيانات الـ Dependencies سارية الصلاحية.

cancel()

await runtime.cancel({ sessionId });

تعيد ضبط التنفيذ المعلّق وتمسح الـ References المنشورة.

listTools()

تعيد تعريفات الـ Tools غير القابلة للتغيير والمخصصة للـ AI Model.

const tools = runtime.listTools();

getConfig()

تعيد نسخة من الـ Config بعد معالجة إعداداتها وحجب القيم الحساسة.

const config = runtime.getConfig();

diagnostics()

تعرض حاليًا حالة HTTP circuit breaker:

console.log(runtime.diagnostics());

clearSession()

await runtime.clearSession(sessionId);

تمسح حالة الـ Session وبيانات الاعتماد المخزّنة للـ ID المحدد.

dispose()

runtime.dispose();

تضع الـ Runtime في حالة الإغلاق وتحرّر موارد مخزن بيانات الاعتماد الذي يملكه. لا تلغي تلقائيًا طلبات الشبكة الجارية؛ استخدم Abort Signals لإلغائها.

صيغة Session ID

يقبل التنفيذ الحالي قيم Session ID يديرها الخادم وتطابق النمط التالي تقريبًا:

[A-Za-z0-9_-]{1,200}

هذه هي الصيغة التي يتوقعها Runtime في الإصدار الحالي. لا تضع أسرارًا أو بيانات شخصية (PII) مباشرة في Session ID.