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
| Chamada | Retorna |
|---|---|
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); | Chamada | Comportamento |
|---|---|
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;
} | Chamada | Retorna |
|---|---|
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.
| Chamada | Retorna |
|---|---|
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 pergunta | criteria | Resposta |
|---|---|---|
choice | Um 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. |
score | Uma 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. |
noul | Nenhum: 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 deinstructions. A pergunta inteira fica eminstructions; 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' }); | Chamada | Comportamento |
|---|---|
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.