createRouteHandler(agent, options?) يشغّل الـ agent من ملف route في أي framework تستقبل الـ handlers فيه Request من Web API وترجع Response: الـ Next.js App Router، وSvelteKit، وRemix / React Router، وHono، وBun.serve. هو غلاف رفيع فوق نفس session API المستخدم في lousho dev وفي السيرفر المنشور (النشر)، لذلك تعمل الـ bindings الخاصة بـ React وVue وSvelte معه بدون أي تغيير. لا يستورد أي framework ولا أي module من node:*. بادئة vendor/ في اسم الـ model هي التي تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
Next.js App Router
auth عام (public): أي شخص يصل إليه يستطيع تشغيل الـ agent وإنفاق ميزانية الـ model لديك. مرّر bearer token، أو دالة تتحقق من الـ session أو الـ cookie الخاصة بتطبيقك:
المسارات
كل المسارات تحتbasePath (الافتراضي /api/agent؛ الشرطة المائلة في آخره مقبولة، وأي طلب خارج الـ base path يرجع 404).
الـ agent يحتفظ بالـ sessions عبر
store الخاص به (createAgent({ store }))، فإذا كنت تستخدم sessions أعطِ الـ agent store يعيش أطول من استدعاء serverless واحد. مع auth، يرتبط معرّف الـ session بأول principal يرسل إليه turn (قراءة المعرّف لا تحجزه)، وأي principal آخر يحصل على 403 (LOUSHO_SESSION_FORBIDDEN). هذا الربط محفوظ في الذاكرة، فالـ instance الجديدة على serverless تنساه، وعندها ترفض الـ session المخزّنة لكل المستخدمين، حتى لمالكها: في تطبيق فيه أكثر من مستخدم، مرّر authorizeSession أيضًا، مثلًا مع معرّفات مشتقة من المتصل (${userId}-<suffix without '-'>، كما في المثال أدناه). راجع من يحق له استخدام session.
مسارات POST تقبل JSON فقط (Content-Type: application/json، وهو ما يرسله useLoushoAgent وuseChat)، وترفض طلب متصفح من origin آخر إلا إذا أضفته إلى allowedOrigins: راجع الطلبات عبر المواقع.
من يحق له الموافقة على استدعاء. لا يوجد في createRouteHandler خيار approvers؛ الـ approvals تُحسم عبر authorizeApproval({ principal, sessionId, approval }). افتراضيًا (callerOwnsApproval) المستخدم الذي يعمل الاستدعاء المحجوز (gated) لصالحه هو من يستطيع الموافقة عليه، ولا يستطيع حسم استدعاء مستخدم آخر، فالتطبيق ذو المستخدم الواحد الذي يسأل مستخدمه نفسه لا يحتاج إلى أي شيء. وهذا يعني أيضًا أن المستخدم يستطيع الموافقة على استرداد مبلغ لنفسه. إذا كان يجب أن تأتي الموافقة من شخص آخر، فمرّر authorizeApproval. هذه قاعدة الشخصين: المشرف هو من يحسم، ولا يحسم أبدًا استدعاءً يعمل لصالحه هو. ويحتاج المشرف أيضًا authorizeSession حتى يقرأ session العميل (GET /chat/:id، ليعرض ما يوافق عليه) ويحسم فيها؛ فافتراضيًا الـ session ملك العميل وحده:
name وcode مع رسالة عامة؛ وexposeErrors: true يرسل النص الأصلي. راجع من يحق له حسم approval لمعرفة الـ 403 الذي يرد به، ولصيغة المشرف في أي session.
إذا اختفى الـ client أثناء بث turn في session (تبويب أُغلق، اتصال انقطع)، يكمل الـ turn حتى نهايته على السيرفر ويُحفظ في الـ session، فالـ tool الذي عمل فعلًا (استرداد مبلغ، بريد إلكتروني) يكون في الـ transcript، والرسالة التالية من المستخدم تستطيع السؤال عنه. لا يُكتب أي شيء بعد ذلك في الـ stream المغلق. على host من نوع serverless، مرّر waitUntil الخاص بالمنصة (مثلًا waitUntil من @vercel/functions) حتى تبقى الـ function حيّة إلى أن يُحفظ الـ turn. أما onDisconnect: 'abort' فيلغي الـ turn بدلًا من ذلك، كما كان سابقًا؛ ونتائج الـ tools التي حصل عليها تبقى محفوظة.
auth يقبل أيضًا قائمة مرتبة من jwt() وoidc() وbasic() وapiToken()، والمتصل الذي تقبله يصل إلى الـ run باسم principal: راجع auth المسارات والـ principals.
Client: useLoushoAgent
Client: useChat
مع uiMessageStream: true، وجّه useChat إلى الـ route ui. الـ id الخاص بالمحادثة هو اسم الـ session، لذلك لا يصل إلى الـ agent إلا آخر رسالة من المستخدم (AI SDK UI).