NeboAI
NeboAI
شروع کنید

App SDK

App SDK صفحه یک برنامه را به Nebo وصل می‌کند. یک اسکریپت است که Nebo به همه برنامه‌ها ارائه می‌دهد و یک متغیر سراسری واحد به نام NeboAppSDK روی صفحه می‌گذارد. چیزی برای نصب یا ساختن نیست.

بارگذاری 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() آن‌ها را برمی‌گردانند.