NeboAI
NeboAI
Empezar

SDK de apps

El SDK de apps conecta la página de una app con Nebo. Es un único script que Nebo sirve a todas las apps, y añade un solo objeto global a la página, NeboAppSDK. No hay nada que instalar ni compilar.

Carga el SDK

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

El objeto global es NeboAppSDK; no existe ningún global nebo. NeboAppSDK.nebo es la instancia del SDK, y cada módulo también se exporta en el nivel superior, así que NeboAppSDK.storage y NeboAppSDK.nebo.storage son el mismo objeto. Para no ocultar los del navegador, nebo.fetch se exporta como neboFetch y nebo.WebSocket como NeboWebSocket.

identity

LlamadaDevuelve
identity.get(){id, name, displayName, description, persona, model, skills, inputValues} del empleado de la app. Se guarda en caché.
identity.invalidate()Borra la caché.

storage

Un almacén de clave-valor para la app. Requiere storage:readwrite. Es el mismo almacén que lee y modifica el empleado de la app: un registro que el propietario añade hablando con el empleado aparece en la página, y uno que se escribe en la página es uno que el empleado puede encontrar.

const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals);
LlamadaComportamiento
storage.getItem(key)Exactamente lo que guardó setItem (objeto, lista, número o cadena), o null.
storage.setItem(key, value)Guarda cualquier valor JSON.
storage.removeItem(key)Elimina una clave; deja de aparecer en keys().
storage.keys()Todas las claves.
storage.clear()Elimina todas las claves.
storage.onChange(handler)Llama a handler({appId, keys, action, source}) después de cada escritura, ya sea del empleado (source: "employee") o de cualquier ventana abierta de la app, incluida esta (source: "page"). Devuelve una función que deja de escuchar.

Vuelve a dibujar cuando cambien los datos, los cambie quien los cambie:

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 el propio empleado de la app accede a este almacén, y solo para su propia app; cualquier otro empleado se lo pregunta al empleado de la app. Elige claves que ambas partes puedan encontrar (una clave que contenga una lista, o una clave por registro con un prefijo como deal:42) y descríbelas en las instrucciones del empleado. Una cadena que a su vez es JSON válido, como "42", se devuelve ya interpretada, así que envuélvela en un objeto si el tipo importa. Mantén cada valor muy por debajo de 2 MB; setItem no lanza ningún error cuando se rechaza una escritura.

agents

Pregunta al empleado de la app, o a otro empleado, y obtén su respuesta. Para preguntar a otro empleado se necesita 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;
}
LlamadaDevuelve
agents.invoke(message, {agent, data}){text, tools} cuando el empleado termina.
agents.stream(message, {agent, data})Un iterador asíncrono de {text, done}.

janus

Una llamada directa al modelo sin personalidad, memoria ni herramientas.

LlamadaDevuelve
janus.complete({messages, model, temperature, max_tokens, system})El texto de la respuesta como cadena.
janus.stream(same)Un iterador asíncrono de fragmentos de texto.

decide

Decisiones tipadas: haz preguntas con nombre sobre unos datos y obtén cada respuesta con probabilidades y un nivel de confianza, en una sola llamada rápida. No se escribe nada como texto, así que úsalo para valoraciones (¿este contacto está caliente?, ¿a qué categoría pertenece este ticket?, ¿cuánta urgencia tiene?) y deja los recuentos, las fechas y los umbrales en tu propio código. El empleado de la app puede hacer las mismas preguntas con su herramienta decide, por ejemplo sobre los registros guardados de la 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 de preguntacriteriaRespuesta
choiceUn objeto de 2 a 255 opciones con nombre, {option: description}. Añade una opción de escape como other cuando la lista no esté completa.choice (la opción elegida), confidence (de 0 a 1) y probabilities por opción.
scoreUna lista de 2 a 10 niveles ordenados, del más bajo al más alto.score (fraccionario, 0 es el primer nivel), confidence y probabilities por nivel.
noulNinguno: la pregunta es una afirmación que hay que valorar.noul, la probabilidad de que la afirmación sea cierta. Sin confianza aparte.
  • decide({state, questions}) se resuelve como {model, answers, usage}, con cada respuesta bajo el nombre que le diste a su pregunta.
  • state es texto o cualquier JSON. Limítalo a los campos que necesitan las preguntas y nombra esos campos entre comillas invertidas dentro de instructions. Toda la pregunta va en instructions; el nombre de la pregunta solo etiqueta la respuesta. Un estado muy largo se acorta por la mitad antes de enviarse.
  • Lanza un error cuyo mensaje es el motivo. El error no tiene código de estado, así que compara el mensaje si necesitas distinguir los casos:
    • Una pregunta mal formada, por ejemplo una de elección con una sola opción (el bot responde 400, indicando qué está mal).
    • No queda trabajo en la cuenta del propietario: «Has usado todo el trabajo incluido en tu cuenta. Elige un plan o añade créditos para continuar.» (429). Reintentar no sirve de nada hasta que el propietario añada un plan o créditos.
    • Demasiadas decisiones a la vez: «Demasiadas decisiones a la vez. Vuelve a intentarlo dentro de un momento.» (429).
    • El bot no ha iniciado sesión: «Las decisiones necesitan NeboAI conectado. Inicia sesión en NeboAI y vuelve a intentarlo.» (503).
    • El servicio de decisiones ha fallado (502).
  • Las decisiones se cobran en la cuenta de NeboAI del propietario del bot como cualquier llamada al modelo. Consulta los precios.

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');

Una ruta relativa va al sidecar de la app en /apps/<id>/api/<path>. Una URL absoluta http o https pasa por el proxy de Nebo y necesita network:<host> o network:*.

NeboWebSocket

new NeboAppSDK.NeboWebSocket() abre un socket en directo con el empleado de la app y se vuelve a conectar con espera progresiva. No recibe argumentos y tiene send(data), close(), onopen, onmessage, onerror y onclose.

surfaces y a2ui

surfaces.connect() abre el canal en directo de la app. Hoy transporta tarjetas interactivas del empleado de la app: llama a a2ui.init(processor) con un MessageProcessor de @a2ui/web_core, que tu página incluye en su bundle (el SDK no tiene renderizador propio). Una tarjeta solo llega a la app para la que se creó, un clic en ella va al empleado de esa app, y una página que se abre después de enviar una tarjeta no la recibe, así que guarda en storage lo que la página deba mostrar siempre.

El SDK también define eventos tipados como text_content, state_delta y surface_update, con surfaces.on(type, handler), surfaces.send(name, payload) y surfaces.state. Nebo todavía no envía esos eventos a las páginas de las apps, y nada responde a send. Para datos en directo, usa storage.onChange.

chat

Integra en la página el chat de Nebo con el empleado de la app.

NeboAppSDK.chat.mount(document.getElementById('chat'), {
  placeholder: 'Ask about a deal',
  contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' });
LlamadaComportamiento
chat.mount(element, options)Opciones: placeholder, theme, height, borderless, contextId, scope.
chat.send(text)Envía un mensaje.
chat.setContext(context)Establece el contexto que ve el empleado; null lo borra.
chat.onMessage(handler)Recibe mensajes.
chat.newThread()Empieza un hilo nuevo.
chat.unmount()Quita el chat.

Configuración

Dentro de Nebo, el SDK encuentra por sí solo el id de la app y la URL base. Para una página servida en otro lugar, llama a nebo.configure({appId, baseUrl}), o a NeboAppSDK.setAppId(id) y NeboAppSDK.setBaseUrl(url). getAppId() y getBaseUrl() los devuelven.