NeboAI
NeboAI
Começar

SDK de apps

O App SDK conecta a página de um app ao Nebo. É um único script que o Nebo serve para todos os apps, e ele coloca um único global na página, o NeboAppSDK. Não há nada para instalar nem compilar.

Carregue o SDK

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

O global é NeboAppSDK; não existe um global nebo. NeboAppSDK.nebo é a instância do SDK, e todo módulo também é exportado no nível superior, então NeboAppSDK.storage e NeboAppSDK.nebo.storage são o mesmo objeto. Para não sobrescrever os do navegador, nebo.fetch é exportado como neboFetch e nebo.WebSocket como NeboWebSocket.

identity

ChamadaRetorna
identity.get(){id, name, displayName, description, persona, model, skills, inputValues} do funcionário do app. Fica em cache.
identity.invalidate()Limpa o cache.

storage

Um armazenamento de chave-valor para o app. Exige storage:readwrite. É o mesmo armazenamento que o funcionário do app lê e altera: um registro que o proprietário adiciona conversando com o funcionário aparece na página, e um registro digitado na página é um que o funcionário consegue encontrar.

const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals);
ChamadaComportamento
storage.getItem(key)Exatamente o que setItem armazenou (objeto, lista, número ou string), ou null.
storage.setItem(key, value)Armazena qualquer valor JSON.
storage.removeItem(key)Remove uma chave; ela deixa de aparecer em keys().
storage.keys()Todas as chaves.
storage.clear()Remove todas as chaves.
storage.onChange(handler)Chama handler({appId, keys, action, source}) depois de cada gravação, seja feita pelo funcionário (source: "employee") ou por qualquer janela aberta do app, incluindo esta (source: "page"). Retorna uma função que para de escutar.

Redesenhe quando os dados mudarem, não importa quem os mudou:

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

Só o próprio funcionário do app acessa este armazenamento, e só para o próprio app; outro funcionário pergunta ao funcionário do app. Escolha chaves que os dois lados consigam encontrar (uma chave com uma lista, ou uma chave por registro sob um prefixo como deal:42) e descreva-as nas instruções do funcionário. Uma string que já é um JSON válido, como "42", volta convertida, então coloque-a dentro de um objeto se o tipo importar. Mantenha cada valor bem abaixo de 2 MB; setItem não lança erro quando uma gravação é recusada.

agents

Pergunte ao funcionário do app, ou a outro funcionário, e receba a resposta. Perguntar a outro funcionário exige 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;
}
ChamadaRetorna
agents.invoke(message, {agent, data}){text, tools} quando o funcionário termina.
agents.stream(message, {agent, data})Um iterador assíncrono de {text, done}.

janus

Uma chamada direta ao modelo, sem persona, memória nem ferramentas.

ChamadaRetorna
janus.complete({messages, model, temperature, max_tokens, system})O texto da resposta como string.
janus.stream(same)Um iterador assíncrono de trechos de texto.

decide

Decisões tipadas: faça perguntas nomeadas sobre alguns dados e receba cada resposta com probabilidades e um nível de confiança, em uma única chamada rápida. Nada é escrito como texto, então use para julgamentos (este lead está quente, a que categoria este ticket pertence, quão urgente ele é) e deixe contagens, datas e limites no seu próprio código. O funcionário do app pode fazer as mesmas perguntas com a ferramenta decide dele, por exemplo sobre os registros armazenados do 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 perguntacriteriaResposta
choiceUm objeto com 2 a 255 opções nomeadas, {option: description}. Adicione uma opção de escape, como other, quando a lista não estiver completa.choice (a opção escolhida), confidence (de 0 a 1) e probabilities por opção.
scoreUma lista de 2 a 10 níveis ordenados, do mais baixo para o mais alto.score (fracionário, 0 é o primeiro nível), confidence e probabilities por nível.
noulNenhum: a pergunta é uma única afirmação a ser julgada.noul, a probabilidade de a afirmação ser verdadeira. Sem confiança separada.
  • decide({state, questions}) resolve para {model, answers, usage}, com cada resposta sob o nome que você deu à pergunta correspondente.
  • state é texto ou qualquer JSON. Limite-o aos campos de que as perguntas precisam e cite esses campos entre crases dentro de instructions. A pergunta inteira fica em instructions; o nome da pergunta só rotula a resposta. Um state muito longo é encurtado no meio antes de ser enviado.
  • Ele lança um erro cuja mensagem é o motivo. O erro não tem código de status, então compare a mensagem se precisar distinguir os casos:
    • Uma pergunta malformada, por exemplo uma escolha com uma única opção (o bot responde 400, indicando o que está errado).
    • Não há mais trabalho disponível na conta do proprietário: "Você usou todo o trabalho incluído na sua conta. Escolha um plano ou adicione créditos para continuar." (429). Tentar de novo não adianta até o proprietário adicionar um plano ou créditos.
    • Decisões demais ao mesmo tempo: "Decisões demais ao mesmo tempo. Tente novamente em instantes." (429).
    • O bot não está conectado: "As decisões precisam da NeboAI conectada. Entre na NeboAI e tente novamente." (503).
    • O serviço de decisões falhou (502).
  • As decisões são cobradas na conta NeboAI do proprietário do bot, como qualquer chamada de modelo. Veja os preços.

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

Um caminho relativo vai para o sidecar do app em /apps/<id>/api/<path>. Uma URL absoluta http ou https passa pelo proxy do Nebo e exige network:<host> ou network:*.

NeboWebSocket

new NeboAppSDK.NeboWebSocket() abre um socket ao vivo com o funcionário do app e se reconecta com backoff. Ele não recebe argumentos e tem send(data), close(), onopen, onmessage, onerror e onclose.

surfaces e a2ui

surfaces.connect() abre o canal ao vivo do app. Hoje ele transporta cartões interativos do funcionário do app: chame a2ui.init(processor) com um MessageProcessor de @a2ui/web_core, que a sua página empacota (o SDK não tem renderizador próprio). Um cartão só chega ao app para o qual foi criado, um clique nele vai para o funcionário desse app, e uma página aberta depois que um cartão foi enviado não o recebe, então guarde em storage o que a página precisa mostrar sempre.

O SDK também define eventos tipados, como text_content, state_delta e surface_update, com surfaces.on(type, handler), surfaces.send(name, payload) e surfaces.state. O Nebo ainda não envia esses eventos para as páginas de apps, e nada responde a send. Para dados ao vivo, use storage.onChange.

chat

Incorpore na página o chat do Nebo com o funcionário do app.

NeboAppSDK.chat.mount(document.getElementById('chat'), {
  placeholder: 'Ask about a deal',
  contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' });
ChamadaComportamento
chat.mount(element, options)Opções: placeholder, theme, height, borderless, contextId, scope.
chat.send(text)Envia uma mensagem.
chat.setContext(context)Define o contexto que o funcionário vê; null o limpa.
chat.onMessage(handler)Recebe mensagens.
chat.newThread()Inicia uma nova conversa.
chat.unmount()Remove o chat.

Configuração

Dentro do Nebo, o SDK encontra sozinho o id do app e a URL base. Para uma página servida em outro lugar, chame nebo.configure({appId, baseUrl}), ou NeboAppSDK.setAppId(id) e NeboAppSDK.setBaseUrl(url). getAppId() e getBaseUrl() leem esses valores de volta.