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 — той самий об’єкт. Щоб не затіняти браузерні 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() зчитують їх назад.