NeboAI
NeboAI
Начать

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