تحميل SDK
<script src="/sdk/nebo.global.js"></script>
<script>
const { nebo, identity, storage, agents, janus, decide, chat, surfaces } = NeboAppSDK;
</script> الكائن العام هو NeboAppSDK، ولا يوجد كائن عام باسم nebo. NeboAppSDK.nebo هو نسخة SDK، وكل وحدة مُصدَّرة أيضًا في المستوى الأعلى، لذا فإن NeboAppSDK.storage وNeboAppSDK.nebo.storage هما الكائن نفسه. ولتجنّب حجب ما في المتصفح، تُصدَّر nebo.fetch باسم neboFetch وnebo.WebSocket باسم NeboWebSocket.
identity
| الاستدعاء | القيمة المُعادة |
|---|---|
identity.get() | {id, name, displayName, description, persona, model, skills, inputValues} لموظف التطبيق. مخزّنة مؤقتًا. |
identity.invalidate() | يمسح ذاكرة التخزين المؤقت. |
storage
مخزن مفاتيح وقيم للتطبيق. يحتاج إلى storage:readwrite. وهو المخزن نفسه الذي يقرؤه موظف التطبيق ويغيّره: السجل الذي يضيفه المالك بالتحدث إلى الموظف يظهر في الصفحة، والسجل الذي يُكتب في الصفحة يستطيع الموظف العثور عليه.
const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals); | الاستدعاء | السلوك |
|---|---|
storage.getItem(key) | ما خزّنه setItem بالضبط (كائن، أو قائمة، أو رقم، أو نص)، أو null. |
storage.setItem(key, value) | يخزّن أي قيمة JSON. |
storage.removeItem(key) | يزيل مفتاحًا واحدًا، فلا يعود يظهر في keys(). |
storage.keys() | كل المفاتيح. |
storage.clear() | يزيل كل المفاتيح. |
storage.onChange(handler) | يستدعي handler({appId, keys, action, source}) بعد كل كتابة، سواء من الموظف (source: "employee") أو من أي نافذة مفتوحة للتطبيق بما فيها هذه النافذة (source: "page"). ويعيد دالة توقف الاستماع. |
أعد الرسم عندما تتغير البيانات، أيًّا كان من غيّرها:
async function load() {
render((await NeboAppSDK.storage.getItem('deals')) ?? []);
}
load();
const stop = NeboAppSDK.storage.onChange((change) => {
// { appId, keys: ['deals'], action: 'set' | 'delete', source: 'employee' | 'page' }
if (change.keys.includes('deals')) load();
}); لا يصل إلى هذا المخزن إلا موظف التطبيق نفسه، ولتطبيقه فقط، أما الموظف الآخر فيسأل موظف التطبيق. اختر مفاتيح يستطيع الطرفان العثور عليها (مفتاح واحد يحمل قائمة، أو مفتاح لكل سجل تحت بادئة مثل deal:42) وصِفها في تعليمات الموظف. النص الذي يكون هو نفسه JSON صالحًا، مثل "42"، يعود محلَّلًا، لذا غلّفه في كائن إن كان النوع مهمًا. اجعل كل قيمة أقل بكثير من 2 MB، فالدالة setItem لا تُطلق خطأً عند رفض الكتابة.
agents
اسأل موظف التطبيق أو موظفًا آخر واحصل على إجابته. سؤال موظف آخر يحتاج إلى subagent:<employee-id>.
const { text } = await NeboAppSDK.agents.invoke('Which open deals close this month?');
for await (const part of NeboAppSDK.agents.stream('Summarize the pipeline.')) {
output.textContent += part.text;
} | الاستدعاء | القيمة المُعادة |
|---|---|
agents.invoke(message, {agent, data}) | {text, tools} عندما ينتهي الموظف. |
agents.stream(message, {agent, data}) | مُكرِّر غير متزامن لـ {text, done}. |
janus
استدعاء مباشر للنموذج دون شخصية أو ذاكرة أو أدوات.
| الاستدعاء | القيمة المُعادة |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | نص الرد كسلسلة نصية. |
janus.stream(same) | مُكرِّر غير متزامن لأجزاء النص. |
decide
قرارات محددة النوع: اطرح أسئلة مسمّاة عن بيانات ما واحصل على كل إجابة مع الاحتمالات ودرجة الثقة، في استدعاء واحد سريع. لا يُكتب شيء كنص، لذا استخدمها للأحكام (هل هذا العميل المحتمل جاد، وإلى أي فئة تنتمي هذه التذكرة، وما مدى إلحاحها) وأبقِ العدّ والتواريخ والعتبات في شيفرتك الخاصة. ويستطيع موظف التطبيق طرح الأسئلة نفسها عبر أداته decide، على سجلات التطبيق المخزّنة مثلًا.
const { answers } = await NeboAppSDK.decide({
state: { company: 'Example Co', status: 'asked for a quote today' },
questions: {
tier: {
type: 'choice',
instructions: 'How warm is this lead, judging by `status`?',
criteria: { hot: 'ready to buy', warm: 'interested', cold: 'not now', other: "can't tell" }
},
fit: {
type: 'score',
instructions: 'How well does `company` fit our customers?',
criteria: ['poor', 'fair', 'good', 'great']
},
reply: { type: 'noul', instructions: '`status` asks us for a reply.' }
}
});
if (answers.tier.choice === 'hot' && answers.tier.confidence > 0.8) flag(lead);
// answers.fit.score is fractional: 0 is "poor", 1.5 is between "fair" and "good".
// answers.reply.noul is the probability the statement holds, from 0 to 1. | نوع السؤال | criteria | الإجابة |
|---|---|---|
choice | كائن من 2 إلى 255 خيارًا مسمّى، {option: description}. أضِف خيارًا احتياطيًا مثل other عندما لا تكون القائمة كاملة. | choice (الخيار المختار)، وconfidence (من 0 إلى 1)، وprobabilities لكل خيار. |
score | قائمة من 2 إلى 10 مستويات مرتبة، الأدنى أولًا. | score (كسري، و0 هو المستوى الأول)، وconfidence، وprobabilities لكل مستوى. |
noul | لا شيء: السؤال عبارة واحدة يُحكم عليها. | noul، أي احتمال صحة العبارة. بلا درجة ثقة منفصلة. |
- تُرجِع
decide({state, questions})القيمة{model, answers, usage}، مع كل إجابة تحت الاسم الذي أعطيته لسؤالها. stateنص أو أي JSON. اقتصر فيه على الحقول التي تحتاج إليها الأسئلة، وسمِّ تلك الحقول بين علامات backtick داخلinstructions. السؤال كله موجود فيinstructions، واسم السؤال مجرد تسمية للإجابة. والحالة الطويلة جدًا تُختصر من المنتصف قبل إرسالها.- يطرح خطأً تكون رسالته هي السبب. لا يحمل الخطأ رمز حالة، لذا قارن الرسالة إذا احتجت إلى التمييز بين الحالات:
- سؤال بصيغة خاطئة، مثل اختيار بخيار واحد (يجيب البوت بالرمز 400، مع توضيح الخطأ).
- لم يتبقَّ عمل في حساب المالك: "لقد استخدمت كل العمل المتضمَّن في حسابك. اختر خطة أو أضِف رصيدًا للمتابعة." (429). لا تفيد إعادة المحاولة حتى يضيف المالك خطة أو رصيدًا.
- قرارات كثيرة جدًا في وقت واحد: "قرارات كثيرة جدًا في وقت واحد. حاول مجددًا بعد لحظة." (429).
- البوت لم يسجّل الدخول: "تحتاج القرارات إلى ربط NeboAI. سجّل الدخول إلى NeboAI وحاول مجددًا." (503).
- فشلت خدمة القرارات (502).
- تُحتسب القرارات على حساب NeboAI الخاص بمالك البوت مثل أي استدعاء للنموذج. انظر الأسعار.
neboFetch
// Relative path: the app's own sidecar.
const res = await NeboAppSDK.neboFetch('/deals?stage=open');
// Absolute URL: through Nebo's proxy. Needs network:api.example.com.
const rates = await NeboAppSDK.neboFetch('https://api.example.com/rates'); المسار النسبي يذهب إلى المكوّن المرافق للتطبيق على /apps/<id>/api/<path>. أما عنوان URL المطلق بـ http أو https فيمرّ عبر وكيل Nebo ويحتاج إلى network:<host> أو network:*.
NeboWebSocket
يفتح new NeboAppSDK.NeboWebSocket() مقبسًا حيًا إلى موظف التطبيق ويعيد الاتصال مع تراجع تدريجي. لا يأخذ أي وسائط، وله send(data) وclose() وonopen وonmessage وonerror وonclose.
surfaces وa2ui
يفتح surfaces.connect() القناة الحية للتطبيق. وهي تحمل اليوم بطاقات تفاعلية من موظف التطبيق: استدعِ a2ui.init(processor) مع MessageProcessor من @a2ui/web_core، الذي تحزّمه صفحتك (لا يملك SDK أداة عرض خاصة به). لا تصل البطاقة إلا إلى التطبيق الذي صُنعت له، والنقر عليها يذهب إلى موظف ذلك التطبيق، والصفحة التي تُفتح بعد إرسال بطاقة لا تستلمها، لذا احتفظ في التخزين بما يجب أن تعرضه الصفحة دائمًا.
يعرّف SDK أيضًا أحداثًا محددة النوع مثل text_content وstate_delta وsurface_update، مع surfaces.on(type, handler) وsurfaces.send(name, payload) وsurfaces.state. لا يرسل Nebo هذه الأحداث إلى صفحات التطبيقات بعد، ولا شيء يستجيب لـ send. للبيانات الحية، استخدم storage.onChange.
chat
ضمّن محادثة Nebo مع موظف التطبيق في الصفحة.
NeboAppSDK.chat.mount(document.getElementById('chat'), {
placeholder: 'Ask about a deal',
contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' }); | الاستدعاء | السلوك |
|---|---|
chat.mount(element, options) | الخيارات: placeholder، theme، height، borderless، contextId، scope. |
chat.send(text) | يرسل رسالة. |
chat.setContext(context) | يحدّد السياق الذي يراه الموظف، وnull يمسحه. |
chat.onMessage(handler) | يستلم الرسائل. |
chat.newThread() | يبدأ سلسلة محادثة جديدة. |
chat.unmount() | يزيل المحادثة. |
التهيئة
داخل Nebo، يعثر SDK على معرّف التطبيق وعنوان URL الأساسي بنفسه. أما للصفحة المستضافة في مكان آخر، فاستدعِ nebo.configure({appId, baseUrl})، أو NeboAppSDK.setAppId(id) وNeboAppSDK.setBaseUrl(url). وتقرأ getAppId() وgetBaseUrl() القيمتين.