NeboAI
NeboAI
Zacznij

SDK aplikacji

App SDK łączy stronę aplikacji z Nebo. To jeden skrypt, który Nebo serwuje każdej aplikacji, i dodaje do strony jeden globalny obiekt, NeboAppSDK. Nie trzeba niczego instalować ani budować.

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łanieZwraca
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łanieZachowanie
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łanieZwraca
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łanieZwraca
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 pytaniacriteriaOdpowiedź
choiceObiekt 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.
scoreLista 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.
noulBrak: 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.
  • state to tekst lub dowolny JSON. Ogranicz go do pól potrzebnych pytaniom i nazwij te pola w odwrotnych apostrofach wewnątrz instructions. Całe pytanie znajduje się w instructions; 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łanieZachowanie
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ą.