بارگذاری 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 است و هر ماژول در سطح بالا هم export میشود، پس NeboAppSDK.storage و NeboAppSDK.nebo.storage یک شیء هستند. برای اینکه با مرورگر تداخل نکند، nebo.fetch با نام neboFetch و nebo.WebSocket با نام NeboWebSocket export میشوند.
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}) | یک async iterator از {text, done}. |
janus
فراخوانی مستقیم مدل بدون شخصیت، حافظه یا ابزار.
| فراخوانی | خروجی |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | متن پاسخ بهصورت رشته. |
janus.stream(same) | یک async iterator از تکههای متن. |
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 | شیئی با ۲ تا ۲۵۵ گزینه نامدار، {option: description}. وقتی فهرست کامل نیست، یک گزینه گریز مثل other اضافه کنید. | choice (گزینه انتخابشده)، confidence (0 تا 1) و probabilities برای هر گزینه. |
score | فهرستی از ۲ تا ۱۰ سطح مرتب، از پایینترین. | score (کسری، 0 اولین سطح است)، confidence و probabilities برای هر سطح. |
noul | هیچ: پرسش یک گزاره برای قضاوت است. | noul، احتمال درست بودن گزاره. بدون اطمینان جداگانه. |
decide({state, questions})به{model, answers, usage}میرسد و هر پاسخ زیر همان نامی قرار میگیرد که به سؤالش دادهاید.stateمتن یا هر JSON است. آن را به فیلدهایی که پرسشها لازم دارند محدود کنید و نام آن فیلدها را درون backtick درinstructionsبیاورید. کل پرسش درinstructionsاست؛ نام پرسش فقط برچسب پاسخ است. state بسیار طولانی پیش از ارسال از وسط کوتاه میشود.- خطایی میدهد که پیامش همان دلیل است. این خطا کد وضعیت ندارد، پس اگر باید حالتها را از هم تشخیص دهید، پیام را مقایسه کنید:
- پرسش بدشکل، مثلاً choice با یک گزینه (بات با 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'); مسیر نسبی به sidecar برنامه در /apps/<id>/api/<path> میرود. URL مطلق http یا https از پراکسی Nebo میگذرد و به network:<host> یا network:* نیاز دارد.
NeboWebSocket
new NeboAppSDK.NeboWebSocket() یک سوکت زنده به کارمند برنامه باز میکند و با backoff دوباره وصل میشود. هیچ آرگومانی نمیگیرد و send(data)، close()، onopen، onmessage، onerror و onclose دارد.
surfaces و a2ui
surfaces.connect() کانال زنده برنامه را باز میکند. امروز کارتهای تعاملی کارمند برنامه را منتقل میکند: a2ui.init(processor) را با یک MessageProcessor از @a2ui/web_core فرا بخوانید که صفحه شما آن را bundle میکند (SDK رندرکننده خودش را ندارد). هر کارت فقط به برنامهای میرسد که برایش ساخته شده، کلیک روی آن به کارمند همان برنامه میرود و صفحهای که پس از ارسال کارت باز شود آن را دریافت نمیکند، پس چیزی را که صفحه همیشه باید نشان دهد در storage نگه دارید.
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 شناسهٔ اپ و نشانی پایه را خودش پیدا میکند. برای صفحهای که جای دیگری ارائه میشود، nebo.configure({appId, baseUrl}) یا NeboAppSDK.setAppId(id) و NeboAppSDK.setBaseUrl(url) را فراخوانی کنید. getAppId() و getBaseUrl() آنها را برمیگردانند.