NeboAI
NeboAI
Comenzar

SDK de aplicaciones

El App SDK conecta la página de una app con Nebo. Es un solo script que Nebo sirve a todas las apps, y coloca un único objeto global en 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 un 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 las APIs 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 agrega 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 cambian los datos, sin importar quién los cambió:

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 empleado de la propia app llega a este almacén, y solo para su propia app; otro empleado tiene que preguntarle al empleado de la app. Elige claves que ambos lados puedan encontrar (una clave que guarde una lista, o una clave por registro con un prefijo como deal:42) y descríbelas en las instrucciones del empleado. Una cadena que en sí misma es JSON válido, como "42", vuelve 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 un error cuando se rechaza una escritura.

agents

Pregúntale al empleado de la app, o a otro empleado, y recibe su respuesta. Preguntarle a otro empleado requiere 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 tipificadas: haz preguntas con nombre sobre ciertos datos y recibe 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 juicios (¿este prospecto está listo para comprar?, ¿a qué categoría pertenece este ticket?, ¿qué tan urgente es?) y deja los conteos, 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}. Agrega 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 sola afirmación que hay que juzgar.noul, la probabilidad de que la afirmación sea cierta. Sin un nivel de confianza aparte.
  • decide({state, questions}) se resuelve en {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 state muy largo se recorta 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 opción múltiple con una sola opción (el bot responde 400, indicando qué está mal).
    • No queda trabajo disponible en la cuenta del propietario: "Ya usaste todo el trabajo incluido en tu cuenta. Elige un plan o agrega créditos para continuar." (429). Reintentar no sirve hasta que el propietario agregue un plan o créditos.
    • Demasiadas decisiones a la vez: "Demasiadas decisiones a la vez. Vuelve a intentarlo en 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 falló (502).
  • Las decisiones se cobran a 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 requiere network:<host> o network:*.

NeboWebSocket

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

surfaces y a2ui

surfaces.connect() abre el canal en vivo 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 un 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 que se envió una tarjeta no la recibe, así que guarda en storage lo que la página siempre deba mostrar.

El SDK también define eventos tipificados 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 vivo, 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)Define el contexto que ve el empleado; null lo borra.
chat.onMessage(handler)Recibe mensajes.
chat.newThread()Inicia 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.