Das SDK laden
<script src="/sdk/nebo.global.js"></script>
<script>
const { nebo, identity, storage, agents, janus, decide, chat, surfaces } = NeboAppSDK;
</script> Das globale Objekt heißt NeboAppSDK; ein globales nebo gibt es nicht. NeboAppSDK.nebo ist die SDK-Instanz, und jedes Modul wird zusätzlich auf oberster Ebene exportiert, sodass NeboAppSDK.storage und NeboAppSDK.nebo.storage dasselbe Objekt sind. Damit die Browser-Objekte nicht überdeckt werden, wird nebo.fetch als neboFetch und nebo.WebSocket als NeboWebSocket exportiert.
identity
| Aufruf | Rückgabe |
|---|---|
identity.get() | {id, name, displayName, description, persona, model, skills, inputValues} für den Mitarbeiter der App. Zwischengespeichert. |
identity.invalidate() | Leert den Cache. |
storage
Ein Key-Value-Speicher für die App. Er braucht storage:readwrite. Es ist derselbe Speicher, den der Mitarbeiter der App liest und ändert: Ein Datensatz, den der Inhaber im Gespräch mit dem Mitarbeiter hinzufügt, erscheint auf der Seite, und einer, der auf der Seite eingegeben wird, kann der Mitarbeiter finden.
const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals); | Aufruf | Verhalten |
|---|---|
storage.getItem(key) | Genau das, was setItem gespeichert hat (Objekt, Liste, Zahl oder String), oder null. |
storage.setItem(key, value) | Speichert einen beliebigen JSON-Wert. |
storage.removeItem(key) | Entfernt einen Schlüssel; er erscheint nicht mehr in keys(). |
storage.keys() | Alle Schlüssel. |
storage.clear() | Entfernt alle Schlüssel. |
storage.onChange(handler) | Ruft handler({appId, keys, action, source}) nach jedem Schreibvorgang auf, ob durch den Mitarbeiter (source: "employee") oder durch ein beliebiges geöffnetes Fenster der App, dieses eingeschlossen (source: "page"). Gibt eine Funktion zurück, die das Zuhören beendet. |
Neu zeichnen, wenn sich die Daten ändern, egal wer sie geändert hat:
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();
}); Nur der eigene Mitarbeiter der App erreicht diesen Speicher, und nur für seine eigene App; ein anderer Mitarbeiter fragt den Mitarbeiter der App. Wähle Schlüssel, die beide Seiten finden können (ein Schlüssel mit einer Liste oder ein Schlüssel pro Datensatz unter einem Präfix wie deal:42), und beschreibe sie in den Anweisungen des Mitarbeiters. Ein String, der selbst gültiges JSON ist, etwa "42", kommt geparst zurück; pack ihn also in ein Objekt, wenn der Typ wichtig ist. Halte jeden Wert deutlich unter 2 MB; setItem wirft keinen Fehler, wenn ein Schreibvorgang abgelehnt wird.
agents
Frag den Mitarbeiter der App oder einen anderen Mitarbeiter und erhalte seine Antwort. Einen anderen Mitarbeiter zu fragen erfordert 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;
} | Aufruf | Rückgabe |
|---|---|
agents.invoke(message, {agent, data}) | {text, tools}, wenn der Mitarbeiter fertig ist. |
agents.stream(message, {agent, data}) | Ein asynchroner Iterator über {text, done}. |
janus
Ein direkter Modellaufruf ohne Persona, Gedächtnis oder Tools.
| Aufruf | Rückgabe |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | Der Antworttext als String. |
janus.stream(same) | Ein asynchroner Iterator über Textabschnitte. |
decide
Typisierte Entscheidungen: Stell benannte Fragen zu bestimmten Daten und erhalte jede Antwort mit Wahrscheinlichkeiten und einer Konfidenz zurück, in einem schnellen Aufruf. Es wird nichts als Text geschrieben; nutze es also für Einschätzungen (ist dieser Lead heiß, in welche Kategorie gehört dieses Ticket, wie dringend ist es) und behalte Zählen, Datumsangaben und Schwellenwerte in deinem eigenen Code. Der Mitarbeiter der App kann dieselben Fragen mit seinem Tool decide stellen, zum Beispiel über die gespeicherten Datensätze der App.
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. | Fragetyp | criteria | Antwort |
|---|---|---|
choice | Ein Objekt mit 2 bis 255 benannten Optionen, {option: description}. Füge eine Ausweichoption wie other hinzu, wenn die Liste nicht vollständig ist. | choice (die gewählte Option), confidence (0 bis 1) und probabilities pro Option. |
score | Eine Liste von 2 bis 10 geordneten Stufen, die niedrigste zuerst. | score (mit Nachkommastellen, 0 ist die erste Stufe), confidence und probabilities pro Stufe. |
noul | Keine: Die Frage ist eine einzelne Aussage, die bewertet wird. | noul, die Wahrscheinlichkeit, dass die Aussage zutrifft. Keine separate Konfidenz. |
decide({state, questions})liefert{model, answers, usage}, wobei jede Antwort unter dem Namen steht, den du ihrer Frage gegeben hast.stateist Text oder beliebiges JSON. Beschränke es auf die Felder, die die Fragen brauchen, und nenne diese Felder in Backticks innerhalb voninstructions. Die ganze Frage steht ininstructions; der Name der Frage beschriftet nur die Antwort. Sehr langer State wird vor dem Senden in der Mitte gekürzt.- Es wirft einen Fehler, dessen Meldung der Grund ist. Der Fehler hat keinen Statuscode. Vergleiche also die Meldung, wenn du die Fälle unterscheiden musst:
- Eine fehlerhafte Frage, zum Beispiel eine Auswahl mit nur einer Option (der Bot antwortet mit 400 und sagt, was falsch ist).
- Kein Arbeitskontingent mehr im Konto des Inhabers: „Du hast die gesamte in deinem Konto enthaltene Arbeit verbraucht. Wähle einen Tarif oder lade Guthaben auf, um weiterzumachen.“ (429). Erneute Versuche helfen erst, wenn der Inhaber einen Tarif oder Guthaben hinzufügt.
- Zu viele Entscheidungen auf einmal: „Zu viele Entscheidungen auf einmal. Versuch es gleich noch einmal.“ (429).
- Der Bot ist nicht angemeldet: „Entscheidungen brauchen eine Verbindung zu NeboAI. Melde dich bei NeboAI an und versuch es noch einmal.“ (503).
- Der Entscheidungsdienst ist fehlgeschlagen (502).
- Entscheidungen werden wie jeder Modellaufruf über das NeboAI-Konto des Bot-Inhabers abgerechnet. Siehe Preise.
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'); Ein relativer Pfad geht an den Sidecar der App unter /apps/<id>/api/<path>. Eine absolute http- oder https-URL läuft über Nebos Proxy und braucht network:<host> oder network:*.
NeboWebSocket
new NeboAppSDK.NeboWebSocket() öffnet einen Live-Socket zum Mitarbeiter der App und verbindet sich mit Backoff neu. Es nimmt keine Argumente und hat send(data), close(), onopen, onmessage, onerror und onclose.
surfaces und a2ui
surfaces.connect() öffnet den Live-Kanal der App. Derzeit überträgt er interaktive Karten vom Mitarbeiter der App: Ruf a2ui.init(processor) mit einem MessageProcessor aus @a2ui/web_core auf, den deine Seite mitbündelt (das SDK hat keinen eigenen Renderer). Eine Karte erreicht nur die App, für die sie erstellt wurde, ein Klick darauf geht an den Mitarbeiter dieser App, und eine Seite, die nach dem Senden einer Karte geöffnet wird, erhält sie nicht; halte also im Speicher fest, was die Seite immer anzeigen muss.
Das SDK definiert außerdem typisierte Ereignisse wie text_content, state_delta und surface_update, mit surfaces.on(type, handler), surfaces.send(name, payload) und surfaces.state. Nebo sendet diese Ereignisse noch nicht an App-Seiten, und nichts beantwortet send. Für Live-Daten nutze storage.onChange.
chat
Bette Nebos Chat mit dem Mitarbeiter der App in die Seite ein.
NeboAppSDK.chat.mount(document.getElementById('chat'), {
placeholder: 'Ask about a deal',
contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' }); | Aufruf | Verhalten |
|---|---|
chat.mount(element, options) | Optionen: placeholder, theme, height, borderless, contextId, scope. |
chat.send(text) | Sendet eine Nachricht. |
chat.setContext(context) | Legt den Kontext fest, den der Mitarbeiter sieht; null leert ihn. |
chat.onMessage(handler) | Empfängt Nachrichten. |
chat.newThread() | Startet einen neuen Thread. |
chat.unmount() | Entfernt den Chat. |
Konfiguration
Innerhalb von Nebo findet das SDK die App-ID und die Basis-URL selbst. Für eine Seite, die anderswo ausgeliefert wird, rufst du nebo.configure({appId, baseUrl}) auf oder NeboAppSDK.setAppId(id) und NeboAppSDK.setBaseUrl(url). getAppId() und getBaseUrl() lesen sie wieder aus.