טעינת ה-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() קוראים אותם בחזרה.