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, וכל מודול מיוצא גם ברמה העליונה, כך ש-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. הגבל אותו לשדות שהשאלות צריכות וציין את השדות האלה בתוך backticks בתוך instructions. כל השאלה נמצאת ב-instructions; השם של השאלה רק מתייג את התשובה. state ארוך מאוד מקוצר באמצעו לפני שהוא נשלח.
  • היא זורקת שגיאה שההודעה שלה היא הסיבה. לשגיאה אין קוד סטטוס, אז השווה את ההודעה אם אתה צריך להבחין בין המקרים:
    • שאלה פגומה, למשל בחירה עם אפשרות אחת (הבוט עונה 400, עם מה שלא תקין).
    • לא נשארה עבודה בחשבון של הבעלים: "You've used all the work included in your account. Choose a plan or add credits to continue." (429). ניסיון חוזר לא יעזור עד שהבעלים יוסיף תוכנית או קרדיט.
    • יותר מדי החלטות בבת אחת: "Too many decisions at once. Try again in a moment." (429).
    • הבוט לא מחובר: "Decisions need NeboAI connected. Sign in to NeboAI and try again." (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 עוברת דרך ה-proxy של Nebo ודורשת network:<host> או network:*.

NeboWebSocket

new NeboAppSDK.NeboWebSocket() פותח socket חי לעובד של האפליקציה ומתחבר מחדש עם השהיה הולכת וגדלה. הוא לא מקבל ארגומנטים ויש לו send(data), close(), onopen, onmessage, onerror ו-onclose.

surfaces ו-a2ui

surfaces.connect() פותח את הערוץ החי של האפליקציה. כיום הוא נושא כרטיסים אינטראקטיביים מהעובד של האפליקציה: קרא ל-a2ui.init(processor) עם MessageProcessor מ-@a2ui/web_core, שהדף שלך כולל בחבילה (ל-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() קוראים אותם בחזרה.