NeboAI
NeboAI
Começar

SDK de apps

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

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

ChamadaDevolve
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);
ChamadaComportamento
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;
}
ChamadaDevolve
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.

ChamadaDevolve
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 perguntacriteriaResposta
choiceUm 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.
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 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 de instructions. A pergunta inteira vive em instructions; 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' });
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 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.