Caricare l’SDK
<script src="/sdk/nebo.global.js"></script>
<script>
const { nebo, identity, storage, agents, janus, decide, chat, surfaces } = NeboAppSDK;
</script> Il globale è NeboAppSDK; non esiste un globale nebo. NeboAppSDK.nebo è l’istanza dell’SDK, e ogni modulo è esportato anche al livello superiore, quindi NeboAppSDK.storage e NeboAppSDK.nebo.storage sono lo stesso oggetto. Per non oscurare le funzioni del browser, nebo.fetch è esportato come neboFetch e nebo.WebSocket come NeboWebSocket.
identity
| Chiamata | Restituisce |
|---|---|
identity.get() | {id, name, displayName, description, persona, model, skills, inputValues} per il dipendente dell’app. Memorizzato nella cache. |
identity.invalidate() | Svuota la cache. |
storage
Un archivio chiave-valore per l’app. Richiede storage:readwrite. È lo stesso archivio che il dipendente dell’app legge e modifica: una voce che il titolare aggiunge parlando con il dipendente compare nella pagina, e una inserita nella pagina è una che il dipendente può trovare.
const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals); | Chiamata | Comportamento |
|---|---|
storage.getItem(key) | Esattamente ciò che setItem ha salvato (oggetto, elenco, numero o stringa), oppure null. |
storage.setItem(key, value) | Salva qualsiasi valore JSON. |
storage.removeItem(key) | Rimuove una chiave; non compare più in keys(). |
storage.keys() | Tutte le chiavi. |
storage.clear() | Rimuove tutte le chiavi. |
storage.onChange(handler) | Chiama handler({appId, keys, action, source}) dopo ogni scrittura, fatta dal dipendente (source: "employee") o da qualsiasi finestra aperta dell’app, compresa questa (source: "page"). Restituisce una funzione che smette di ascoltare. |
Ridisegna quando i dati cambiano, chiunque li abbia cambiati:
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();
}); Solo il dipendente dell’app accede a questo archivio, e solo per la propria app; un altro dipendente deve chiedere al dipendente dell’app. Scegli chiavi che entrambe le parti possano trovare (una chiave con un elenco, oppure una chiave per ogni voce sotto un prefisso come deal:42) e descrivile nelle istruzioni del dipendente. Una stringa che è a sua volta JSON valido, come "42", torna già interpretata, quindi racchiudila in un oggetto se il tipo è importante. Tieni ogni valore ben al di sotto dei 2 MB; setItem non genera un errore quando una scrittura viene rifiutata.
agents
Fai una domanda al dipendente dell’app, o a un altro dipendente, e ricevi la sua risposta. Per chiedere a un altro dipendente serve 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;
} | Chiamata | Restituisce |
|---|---|
agents.invoke(message, {agent, data}) | {text, tools} quando il dipendente ha finito. |
agents.stream(message, {agent, data}) | Un iteratore asincrono di {text, done}. |
janus
Una chiamata diretta al modello, senza persona, memoria né strumenti.
| Chiamata | Restituisce |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | Il testo della risposta come stringa. |
janus.stream(same) | Un iteratore asincrono di porzioni di testo. |
decide
Decisioni tipizzate: fai domande con nome su alcuni dati e ricevi ogni risposta con probabilità e un grado di fiducia, in una sola chiamata veloce. Non viene scritto nulla come testo, quindi usalo per i giudizi (questo lead è caldo, a quale categoria appartiene questo ticket, quanto è urgente) e lascia conteggi, date e soglie al tuo codice. Il dipendente dell’app può fare le stesse domande con il suo strumento decide, per esempio sulle voci salvate dall’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. | Tipo di domanda | criteria | Risposta |
|---|---|---|
choice | Un oggetto da 2 a 255 opzioni con nome, {option: description}. Aggiungi un’opzione di uscita come other quando l’elenco non è completo. | choice (l’opzione scelta), confidence (da 0 a 1) e probabilities per ogni opzione. |
score | Un elenco da 2 a 10 livelli ordinati, dal più basso. | score (frazionario, 0 è il primo livello), confidence e probabilities per ogni livello. |
noul | Nessuno: la domanda è un’unica affermazione da giudicare. | noul, la probabilità che l’affermazione sia vera. Nessun grado di fiducia separato. |
decide({state, questions})restituisce{model, answers, usage}, con ogni risposta sotto il nome che hai dato alla sua domanda.stateè testo o qualsiasi JSON. Limitalo ai campi che servono alle domande e cita quei campi tra backtick dentroinstructions. Tutta la domanda sta ininstructions; il nome della domanda serve solo a etichettare la risposta. Uno state molto lungo viene accorciato al centro prima dell’invio.- Genera un errore il cui messaggio è il motivo. L’errore non ha un codice di stato, quindi confronta il messaggio se devi distinguere i casi:
- Una domanda formulata male, per esempio una scelta con una sola opzione (il bot risponde 400, indicando cosa non va).
- Nessun lavoro rimasto sull’account del titolare: «Hai usato tutto il lavoro incluso nel tuo account. Scegli un piano o aggiungi crediti per continuare.» (429). Riprovare non serve finché il titolare non aggiunge un piano o dei crediti.
- Troppe decisioni contemporaneamente: «Troppe decisioni contemporaneamente. Riprova tra un momento.» (429).
- Il bot non ha effettuato l’accesso: «Le decisioni richiedono che NeboAI sia collegato. Accedi a NeboAI e riprova.» (503).
- Il servizio delle decisioni non ha funzionato (502).
- Le decisioni vengono addebitate sull’account NeboAI del titolare del bot come qualsiasi chiamata a un modello. Vedi i prezzi.
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'); Un percorso relativo va al sidecar dell’app su /apps/<id>/api/<path>. Un URL assoluto http o https passa dal proxy di Nebo e richiede network:<host> o network:*.
NeboWebSocket
new NeboAppSDK.NeboWebSocket() apre un socket in tempo reale verso il dipendente dell’app e si riconnette con backoff. Non accetta argomenti e ha send(data), close(), onopen, onmessage, onerror e onclose.
surfaces e a2ui
surfaces.connect() apre il canale in tempo reale dell’app. Oggi trasporta schede interattive dal dipendente dell’app: chiama a2ui.init(processor) con un MessageProcessor di @a2ui/web_core, che la tua pagina include nel proprio bundle (l’SDK non ha un renderer proprio). Una scheda arriva solo all’app per cui è stata creata, un clic su di essa va al dipendente di quell’app, e una pagina aperta dopo l’invio di una scheda non la riceve, quindi tieni nello storage ciò che la pagina deve mostrare sempre.
L’SDK definisce anche eventi tipizzati come text_content, state_delta e surface_update, con surfaces.on(type, handler), surfaces.send(name, payload) e surfaces.state. Nebo non invia ancora questi eventi alle pagine delle app, e nessuno risponde a send. Per i dati in tempo reale, usa storage.onChange.
chat
Integra nella pagina la chat di Nebo con il dipendente dell’app.
NeboAppSDK.chat.mount(document.getElementById('chat'), {
placeholder: 'Ask about a deal',
contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' }); | Chiamata | Comportamento |
|---|---|
chat.mount(element, options) | Opzioni: placeholder, theme, height, borderless, contextId, scope. |
chat.send(text) | Invia un messaggio. |
chat.setContext(context) | Imposta il contesto che il dipendente vede; null lo cancella. |
chat.onMessage(handler) | Riceve i messaggi. |
chat.newThread() | Avvia un nuovo thread. |
chat.unmount() | Rimuove la chat. |
Configurazione
All’interno di Nebo, l’SDK trova da solo l’ID dell’app e l’URL di base. Per una pagina servita altrove, chiama nebo.configure({appId, baseUrl}), oppure NeboAppSDK.setAppId(id) e NeboAppSDK.setBaseUrl(url). getAppId() e getBaseUrl() li rileggono.