Załaduj SDK
<script src="/sdk/nebo.global.js"></script>
<script>
const { nebo, identity, storage, agents, janus, decide, chat, surfaces } = NeboAppSDK;
</script> Obiekt globalny to NeboAppSDK; nie ma globalnego nebo. NeboAppSDK.nebo to instancja SDK, a każdy moduł jest też eksportowany na najwyższym poziomie, więc NeboAppSDK.storage i NeboAppSDK.nebo.storage to ten sam obiekt. Aby nie przesłaniać obiektów przeglądarki, nebo.fetch jest eksportowane jako neboFetch, a nebo.WebSocket jako NeboWebSocket.
identity
| Wywołanie | Zwraca |
|---|---|
identity.get() | {id, name, displayName, description, persona, model, skills, inputValues} pracownika aplikacji. Zapisywane w pamięci podręcznej. |
identity.invalidate() | Czyści pamięć podręczną. |
storage
Magazyn klucz–wartość dla aplikacji. Wymaga storage:readwrite. To ten sam magazyn, który odczytuje i zmienia pracownik aplikacji: rekord dodany przez właściciela w rozmowie z pracownikiem pojawia się na stronie, a rekord wpisany na stronie pracownik może znaleźć.
const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals); | Wywołanie | Zachowanie |
|---|---|
storage.getItem(key) | Dokładnie to, co zapisało setItem (obiekt, lista, liczba lub ciąg znaków), albo null. |
storage.setItem(key, value) | Zapisuje dowolną wartość JSON. |
storage.removeItem(key) | Usuwa jeden klucz; nie pojawia się on już w keys(). |
storage.keys() | Wszystkie klucze. |
storage.clear() | Usuwa wszystkie klucze. |
storage.onChange(handler) | Wywołuje handler({appId, keys, action, source}) po każdym zapisie, wykonanym przez pracownika (source: "employee") albo przez dowolne otwarte okno aplikacji, łącznie z tym (source: "page"). Zwraca funkcję, która kończy nasłuchiwanie. |
Odśwież widok, gdy dane się zmienią, niezależnie od tego, kto je zmienił:
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();
}); Do tego magazynu ma dostęp tylko własny pracownik aplikacji i tylko dla swojej aplikacji; inny pracownik pyta pracownika aplikacji. Wybierz klucze, które obie strony mogą znaleźć (jeden klucz z listą albo jeden klucz na rekord z prefiksem, np. deal:42), i opisz je w instrukcjach pracownika. Ciąg znaków, który sam jest poprawnym JSON-em, np. "42", wraca sparsowany, więc jeśli typ ma znaczenie, opakuj go w obiekt. Każda wartość powinna być wyraźnie mniejsza niż 2 MB; setItem nie zgłasza wyjątku, gdy zapis zostanie odrzucony.
agents
Zadaj pytanie pracownikowi aplikacji lub innemu pracownikowi i odbierz jego odpowiedź. Pytanie innego pracownika wymaga 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;
} | Wywołanie | Zwraca |
|---|---|
agents.invoke(message, {agent, data}) | {text, tools}, gdy pracownik skończy. |
agents.stream(message, {agent, data}) | Asynchroniczny iterator {text, done}. |
janus
Bezpośrednie wywołanie modelu bez persony, pamięci i narzędzi.
| Wywołanie | Zwraca |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | Tekst odpowiedzi jako ciąg znaków. |
janus.stream(same) | Asynchroniczny iterator fragmentów tekstu. |
decide
Typowane decyzje: zadaj nazwane pytania o jakieś dane i otrzymaj każdą odpowiedź z prawdopodobieństwami i poziomem pewności, w jednym szybkim wywołaniu. Nic nie jest zapisywane jako tekst, więc używaj tego do ocen (czy ten lead jest gorący, do jakiej kategorii należy to zgłoszenie, jak pilne jest) i trzymaj liczenie, daty i progi we własnym kodzie. Pracownik aplikacji może zadawać te same pytania narzędziem decide, na przykład na zapisanych rekordach aplikacji.
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. | Typ pytania | criteria | Odpowiedź |
|---|---|---|
choice | Obiekt od 2 do 255 nazwanych opcji, {option: description}. Dodaj opcję awaryjną, np. other, gdy lista nie jest kompletna. | choice (wybrana opcja), confidence (od 0 do 1) i probabilities dla każdej opcji. |
score | Lista od 2 do 10 uporządkowanych poziomów, od najniższego. | score (ułamkowy, 0 to pierwszy poziom), confidence i probabilities dla każdego poziomu. |
noul | Brak: pytanie to jedno stwierdzenie do oceny. | noul, prawdopodobieństwo, że stwierdzenie jest prawdziwe. Bez osobnego poziomu pewności. |
decide({state, questions})zwraca{model, answers, usage}, a każda odpowiedź znajduje się pod nazwą, którą nadałeś jej pytaniu.stateto tekst lub dowolny JSON. Ogranicz go do pól potrzebnych pytaniom i nazwij te pola w odwrotnych apostrofach wewnątrzinstructions. Całe pytanie znajduje się winstructions; nazwa pytania tylko oznacza odpowiedź. Bardzo długi stan jest skracany w środku przed wysłaniem.- Zgłasza błąd, którego komunikat podaje przyczynę. Błąd nie ma kodu statusu, więc jeśli chcesz rozróżnić przypadki, porównuj komunikat:
- Błędnie sformułowane pytanie, np. wybór z jedną opcją (bot odpowiada kodem 400 z opisem problemu).
- Na koncie właściciela nie została żadna praca: „Wykorzystałeś całą pracę zawartą w Twoim koncie. Wybierz plan lub dodaj środki, aby kontynuować.” (429). Ponawianie nie pomoże, dopóki właściciel nie doda planu lub środków.
- Za dużo decyzji naraz: „Za dużo decyzji naraz. Spróbuj ponownie za chwilę.” (429).
- Bot nie jest zalogowany: „Decyzje wymagają połączenia z NeboAI. Zaloguj się do NeboAI i spróbuj ponownie.” (503).
- Usługa decyzji nie zadziałała (502).
- Decyzje są rozliczane z konta NeboAI właściciela bota tak jak każde wywołanie modelu. Zobacz cennik.
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'); Ścieżka względna trafia do sidecara aplikacji pod /apps/<id>/api/<path>. Bezwzględny adres URL http lub https przechodzi przez proxy Nebo i wymaga network:<host> lub network:*.
NeboWebSocket
new NeboAppSDK.NeboWebSocket() otwiera aktywne gniazdo do pracownika aplikacji i łączy się ponownie z narastającym opóźnieniem. Nie przyjmuje argumentów i ma send(data), close(), onopen, onmessage, onerror i onclose.
surfaces i a2ui
surfaces.connect() otwiera kanał na żywo aplikacji. Obecnie przenosi interaktywne karty od pracownika aplikacji: wywołaj a2ui.init(processor) z MessageProcessor z @a2ui/web_core, który Twoja strona dołącza do paczki (SDK nie ma własnego renderera). Karta trafia tylko do aplikacji, dla której powstała, kliknięcie w nią trafia do pracownika tej aplikacji, a strona otwarta po wysłaniu karty jej nie otrzyma, więc to, co strona zawsze musi pokazywać, trzymaj w storage.
SDK definiuje też typowane zdarzenia, takie jak text_content, state_delta i surface_update, z surfaces.on(type, handler), surfaces.send(name, payload) i surfaces.state. Nebo nie wysyła jeszcze tych zdarzeń do stron aplikacji i nic nie odpowiada na send. Do danych na żywo używaj storage.onChange.
chat
Osadź na stronie czat Nebo z pracownikiem aplikacji.
NeboAppSDK.chat.mount(document.getElementById('chat'), {
placeholder: 'Ask about a deal',
contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' }); | Wywołanie | Zachowanie |
|---|---|
chat.mount(element, options) | Opcje: placeholder, theme, height, borderless, contextId, scope. |
chat.send(text) | Wysyła wiadomość. |
chat.setContext(context) | Ustawia kontekst widoczny dla pracownika; null go czyści. |
chat.onMessage(handler) | Odbiera wiadomości. |
chat.newThread() | Rozpoczyna nowy wątek. |
chat.unmount() | Usuwa czat. |
Konfiguracja
Wewnątrz Nebo SDK samo znajduje identyfikator aplikacji i bazowy adres URL. W przypadku strony serwowanej gdzie indziej wywołaj nebo.configure({appId, baseUrl}) albo NeboAppSDK.setAppId(id) i NeboAppSDK.setBaseUrl(url). getAppId() i getBaseUrl() je odczytują.