Загрузка 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() возвращают эти значения.