Carregar 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 nenhum global nebo. NeboAppSDK.nebo é a instância do SDK, e todos os módulos também são exportados no nível superior, por isso NeboAppSDK.storage e NeboAppSDK.nebo.storage são o mesmo objeto. Para não ocultar os do navegador, nebo.fetch é exportado como neboFetch e nebo.WebSocket como NeboWebSocket.
identity
| Chamada | Devolve |
|---|---|
identity.get() | {id, name, displayName, description, persona, model, skills, inputValues} do funcionário da app. Em cache. |
identity.invalidate() | Limpa a cache. |
storage
Um armazenamento chave-valor para a app. Precisa de storage:readwrite. É o mesmo armazenamento que o funcionário da app lê e altera: um registo que o proprietário acrescenta ao falar com o funcionário aparece na página, e um registo escrito 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 guardou (objeto, lista, número ou cadeia), ou null. |
storage.setItem(key, value) | Guarda qualquer valor JSON. |
storage.removeItem(key) | Remove uma chave; 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 escrita, feita pelo funcionário (source: "employee") ou por qualquer janela aberta da app, incluindo esta (source: "page"). Devolve uma função que para de escutar. |
Volte a desenhar quando os dados mudam, seja quem for que 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 da app chega a este armazenamento, e só para a sua própria app; outro funcionário pergunta ao funcionário da app. Escolha chaves que ambos os lados consigam encontrar (uma chave com uma lista, ou uma chave por registo com um prefixo como deal:42) e descreva-as nas instruções do funcionário. Uma cadeia que seja ela própria JSON válido, como "42", volta já interpretada, por isso envolva-a num objeto se o tipo importar. Mantenha cada valor bem abaixo de 2 MB; setItem não lança erro quando uma escrita é recusada.
agents
Pergunte ao funcionário da 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 | Devolve |
|---|---|
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 a um modelo, sem persona, memória nem ferramentas.
| Chamada | Devolve |
|---|---|
janus.complete({messages, model, temperature, max_tokens, system}) | O texto da resposta como cadeia. |
janus.stream(same) | Um iterador assíncrono de fragmentos de texto. |
decide
Decisões tipificadas: faça perguntas com nome sobre alguns dados e receba cada resposta com probabilidades e um grau de confiança, numa só chamada rápida. Nada é escrito como texto, por isso use-as para juízos (este potencial cliente está quente, a que categoria pertence este ticket, qual a urgência) e mantenha contagens, datas e limiares no seu próprio código. O funcionário da app pode fazer as mesmas perguntas com a sua ferramenta decide, por exemplo sobre os registos guardados da 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 de 2 a 255 opções com nome, {option: description}. Acrescente uma opção de saída, como other, quando a lista não estiver completa. | choice (a opção escolhida), confidence (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 afirmação a avaliar. | noul, a probabilidade de a afirmação ser verdadeira. Sem grau de confiança separado. |
decide({state, questions})devolve{model, answers, usage}, com cada resposta sob o nome que deu à respetiva pergunta.stateé texto ou qualquer JSON. Limite-o aos campos de que as perguntas precisam e indique esses campos entre acentos graves dentro deinstructions. A pergunta inteira vive eminstructions; o nome da pergunta serve apenas de etiqueta da resposta. Um state muito longo é encurtado no meio antes de ser enviado.- Lança um erro cuja mensagem é o motivo. O erro não tem código de estado, por isso compare a mensagem se precisar de distinguir os casos:
- Uma pergunta mal formada, por exemplo uma escolha com uma só opção (o bot responde 400, com o que está errado).
- Já não há trabalho disponível na conta do proprietário: «Usou todo o trabalho incluído na sua conta. Escolha um plano ou adicione créditos para continuar.» (429). Tentar de novo não ajuda enquanto o proprietário não adicionar um plano ou créditos.
- Demasiadas decisões em simultâneo: «Demasiadas decisões em simultâneo. Tente novamente daqui a pouco.» (429).
- O bot não tem sessão iniciada: «As decisões precisam da NeboAI ligada. Inicie sessão na NeboAI e tente novamente.» (503).
- O serviço de decisões falhou (502).
- As decisões são faturadas na conta NeboAI do proprietário do bot, como qualquer chamada a um modelo. Ver 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 da app em /apps/<id>/api/<path>. Um URL http ou https absoluto passa pelo proxy do Nebo e precisa de network:<host> ou network:*.
NeboWebSocket
new NeboAppSDK.NeboWebSocket() abre um socket em direto com o funcionário da app e volta a ligar-se com backoff. Não recebe argumentos e tem send(data), close(), onopen, onmessage, onerror e onclose.
surfaces e a2ui
surfaces.connect() abre o canal em direto da app. Hoje transporta cartões interativos do funcionário da app: chame a2ui.init(processor) com um MessageProcessor de @a2ui/web_core, que a sua página inclui (o SDK não tem renderizador próprio). Um cartão só chega à app para a qual foi feito, um clique nele vai para o funcionário dessa app, e uma página aberta depois de um cartão ter sido enviado não o recebe, por isso guarde no armazenamento o que a página tem sempre de mostrar.
O SDK também define eventos tipificados 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 das apps, e nada responde a send. Para dados em direto, use storage.onChange.
chat
Incorpore na página o chat do Nebo com o funcionário da 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 limpa-o. |
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 da app e o URL base. Para uma página servida noutro lado, chame nebo.configure({appId, baseUrl}), ou NeboAppSDK.setAppId(id) e NeboAppSDK.setBaseUrl(url). getAppId() e getBaseUrl() devolvem esses valores.