Завантаження 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 — той самий об’єкт. Щоб не затіняти браузерні API, 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. Обмежтеся полями, потрібними запитанням, і назвіть ці поля в зворотних лапках усерединіinstructions. Усе запитання міститься вinstructions; назва запитання лише позначає відповідь. Дуже довгий state скорочується посередині перед надсиланням.- Викидає помилку, повідомлення якої містить причину. Помилка не має коду статусу, тож порівнюйте повідомлення, якщо треба розрізнити випадки:
- Некоректне запитання, наприклад вибір з одним варіантом (бот відповідає 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 не має власного рендерера). Картка потрапляє лише до застосунку, для якого її створено, клік по ній іде до співробітника цього застосунку, а сторінка, відкрита після надсилання картки, її не отримує, тож тримайте те, що сторінка завжди має показувати, у 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 сам знаходить ідентифікатор застосунку та базову URL-адресу. Для сторінки, розміщеної деінде, викличте nebo.configure({appId, baseUrl}) або NeboAppSDK.setAppId(id) і NeboAppSDK.setBaseUrl(url). getAppId() і getBaseUrl() зчитують їх назад.