NeboAI
NeboAI
Commencer

SDK des apps

Le SDK d'application relie la page d'une application à Nebo. C'est un seul script que Nebo sert à chaque application, et il place un unique objet global sur la page, NeboAppSDK. Il n'y a rien à installer ni à compiler.

Charger le SDK

<script src="/sdk/nebo.global.js"></script>
<script>
  const { nebo, identity, storage, agents, janus, decide, chat, surfaces } = NeboAppSDK;
</script>

L'objet global est NeboAppSDK ; il n'existe pas d'objet global nebo. NeboAppSDK.nebo est l'instance du SDK, et chaque module est aussi exporté au premier niveau : NeboAppSDK.storage et NeboAppSDK.nebo.storage sont donc le même objet. Pour ne pas masquer les objets du navigateur, nebo.fetch est exporté sous le nom neboFetch et nebo.WebSocket sous le nom NeboWebSocket.

identity

AppelRenvoie
identity.get(){id, name, displayName, description, persona, model, skills, inputValues} pour l'employé de l'application. Mis en cache.
identity.invalidate()Vide le cache.

storage

Un magasin clé-valeur pour l'application. Il nécessite storage:readwrite. C'est le même magasin que celui que lit et modifie l'employé de l'application : une fiche que le propriétaire ajoute en parlant à l'employé apparaît sur la page, et une fiche saisie dans la page est une fiche que l'employé peut retrouver.

const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals);
AppelComportement
storage.getItem(key)Exactement ce que setItem a stocké (objet, liste, nombre ou chaîne), ou null.
storage.setItem(key, value)Stocke n'importe quelle valeur JSON.
storage.removeItem(key)Supprime une clé ; elle n'apparaît plus dans keys().
storage.keys()Toutes les clés.
storage.clear()Supprime toutes les clés.
storage.onChange(handler)Appelle handler({appId, keys, action, source}) après chaque écriture, que ce soit par l'employé (source: "employee") ou par n'importe quelle fenêtre ouverte de l'application, y compris celle-ci (source: "page"). Renvoie une fonction qui arrête l'écoute.

Redessinez la page quand les données changent, quel que soit l'auteur du changement :

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();
});

Seul l'employé propre à l'application accède à ce magasin, et uniquement pour sa propre application ; un autre employé doit passer par l'employé de l'application. Choisissez des clés que les deux côtés peuvent retrouver (une clé contenant une liste, ou une clé par fiche sous un préfixe comme deal:42) et décrivez-les dans les instructions de l'employé. Une chaîne qui est elle-même du JSON valide, comme "42", revient analysée : enveloppez-la dans un objet si le type compte. Gardez chaque valeur bien en dessous de 2 MB ; setItem ne lève pas d'erreur lorsqu'une écriture est refusée.

agents

Interrogez l'employé de l'application, ou un autre employé, et obtenez sa réponse. Interroger un autre employé nécessite 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;
}
AppelRenvoie
agents.invoke(message, {agent, data}){text, tools} lorsque l'employé a terminé.
agents.stream(message, {agent, data})Un itérateur asynchrone de {text, done}.

janus

Un appel direct au modèle, sans persona, mémoire ni outils.

AppelRenvoie
janus.complete({messages, model, temperature, max_tokens, system})Le texte de la réponse, sous forme de chaîne.
janus.stream(same)Un itérateur asynchrone de fragments de texte.

decide

Les décisions typées : posez des questions nommées sur des données et obtenez chaque réponse avec des probabilités et un niveau de confiance, en un seul appel rapide. Rien n'est écrit sous forme de texte : utilisez-les pour des jugements (ce prospect est-il chaud, à quelle catégorie appartient ce ticket, quel est son degré d'urgence) et gardez les calculs, les dates et les seuils dans votre propre code. L'employé de l'application peut poser les mêmes questions avec son outil decide, par exemple sur les fiches stockées de l'application.

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.
Type de questioncriteriaRéponse
choiceUn objet de 2 à 255 options nommées, {option: description}. Ajoutez une option de sortie comme other lorsque la liste n'est pas exhaustive.choice (l'option choisie), confidence (de 0 à 1) et probabilities par option.
scoreUne liste de 2 à 10 niveaux ordonnés, du plus bas au plus haut.score (fractionnaire, 0 correspond au premier niveau), confidence et probabilities par niveau.
noulAucun : la question est une seule affirmation à juger.noul, la probabilité que l'affirmation soit vraie. Pas de niveau de confiance distinct.
  • decide({state, questions}) renvoie {model, answers, usage}, chaque réponse étant rangée sous le nom que vous avez donné à sa question.
  • state est du texte ou n'importe quel JSON. Limitez-le aux champs dont les questions ont besoin et nommez ces champs entre accents graves dans instructions. Toute la question se trouve dans instructions ; le nom de la question ne sert qu'à étiqueter la réponse. Un état très long est raccourci en son milieu avant d'être envoyé.
  • Elle lève une erreur dont le message indique la raison. L'erreur n'a pas de code de statut, donc comparez le message si vous devez distinguer les cas :
    • Une question mal formée, par exemple un choix avec une seule option (le bot répond 400, en précisant ce qui ne va pas).
    • Plus de travail disponible sur le compte du propriétaire : « Vous avez utilisé tout le travail inclus dans votre compte. Choisissez une offre ou ajoutez des crédits pour continuer. » (429). Réessayer ne sert à rien tant que le propriétaire n'a pas ajouté d'offre ou de crédits.
    • Trop de décisions à la fois : « Trop de décisions à la fois. Réessayez dans un instant. » (429).
    • Le bot n'est pas connecté : « Les décisions nécessitent que NeboAI soit connecté. Connectez-vous à NeboAI et réessayez. » (503).
    • Le service de décision a échoué (502).
  • Les décisions sont facturées sur le compte NeboAI du propriétaire du bot, comme tout appel de modèle. Voir les tarifs.

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 chemin relatif est envoyé au sidecar de l'application à /apps/<id>/api/<path>. Une URL absolue http ou https passe par le proxy de Nebo et nécessite network:<host> ou network:*.

NeboWebSocket

new NeboAppSDK.NeboWebSocket() ouvre un socket en direct vers l'employé de l'application et se reconnecte avec un backoff. Il ne prend aucun argument et dispose de send(data), close(), onopen, onmessage, onerror et onclose.

surfaces et a2ui

surfaces.connect() ouvre le canal en direct de l'application. Aujourd'hui, il transporte des cartes interactives provenant de l'employé de l'application : appelez a2ui.init(processor) avec un MessageProcessor issu de @a2ui/web_core, que votre page intègre (le SDK n'a pas de moteur de rendu propre). Une carte n'atteint que l'application pour laquelle elle a été créée, un clic sur une carte est envoyé à l'employé de cette application, et une page ouverte après l'envoi d'une carte ne la reçoit pas : gardez donc dans le stockage ce que la page doit toujours afficher.

Le SDK définit aussi des événements typés comme text_content, state_delta et surface_update, avec surfaces.on(type, handler), surfaces.send(name, payload) et surfaces.state. Nebo n'envoie pas encore ces événements aux pages des applications, et rien ne répond à send. Pour des données en direct, utilisez storage.onChange.

chat

Intégrez dans la page la discussion de Nebo avec l'employé de l'application.

NeboAppSDK.chat.mount(document.getElementById('chat'), {
  placeholder: 'Ask about a deal',
  contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' });
AppelComportement
chat.mount(element, options)Options : placeholder, theme, height, borderless, contextId, scope.
chat.send(text)Envoie un message.
chat.setContext(context)Définit le contexte que voit l'employé ; null l'efface.
chat.onMessage(handler)Reçoit les messages.
chat.newThread()Démarre un nouveau fil.
chat.unmount()Supprime la discussion.

Configuration

Dans Nebo, le SDK trouve tout seul l'identifiant de l'app et l'URL de base. Pour une page servie ailleurs, appelez nebo.configure({appId, baseUrl}), ou NeboAppSDK.setAppId(id) et NeboAppSDK.setBaseUrl(url). getAppId() et getBaseUrl() permettent de les relire.