NeboAI
NeboAI
开始使用

应用 SDK

应用 SDK 把应用的页面连接到 Nebo。它是 Nebo 提供给每个应用的同一个脚本,会在页面上放置一个全局对象 NeboAppSDK。无需安装,也无需构建。

加载 SDK

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

全局对象是 NeboAppSDK;没有 nebo 这个全局对象。NeboAppSDK.nebo 是 SDK 实例,而且每个模块也都在顶层导出,所以 NeboAppSDK.storage 和 NeboAppSDK.nebo.storage 是同一个对象。为了避免遮蔽浏览器自带的对象,nebo.fetch 导出为 neboFetch,nebo.WebSocket 导出为 NeboWebSocket。

identity

调用返回值
identity.get()应用员工的 {id, name, displayName, description, persona, model, skills, inputValues}。会被缓存。
identity.invalidate()清除缓存。

storage

应用的键值存储。它需要 storage:readwrite。它和应用员工读取、修改的是同一个存储:所有者通过和员工对话添加的记录会显示在页面上,而在页面中输入的记录,员工也能找到。

const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals);
调用行为
storage.getItem(key)与 setItem 存入的内容完全一致(对象、列表、数字或字符串),或者 null。
storage.setItem(key, value)存储任意 JSON 值。
storage.removeItem(key)移除一个键;它将不再出现在 keys() 中。
storage.keys()所有键。
storage.clear()移除所有键。
storage.onChange(handler)每次写入后调用 handler({appId, keys, action, source}),写入方可以是员工(source: "employee"),也可以是该应用任何一个打开的窗口,包括当前窗口(source: "page")。返回一个用于停止监听的函数。

无论是谁修改了数据,数据变化时都重新绘制:

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

只有应用自己的员工能访问这个存储,而且只能用于它自己的应用;其他员工需要去问该应用的员工。选择双方都能找到的键(用一个键保存一个列表,或者在某个前缀下每条记录一个键,例如 deal:42),并在员工的指令中说明它们。本身就是合法 JSON 的字符串(例如 "42")在读回时会被解析,所以如果类型很重要,请把它包在一个对象里。让每个值都远小于 2 MB;写入被拒绝时,setItem 不会抛出异常。

agents

向应用的员工或其他员工提问,并获得它的回答。向其他员工提问需要 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;
}
调用返回值
agents.invoke(message, {agent, data})员工完成时返回 {text, tools}。
agents.stream(message, {agent, data})一个 {text, done} 的异步迭代器。

janus

直接调用模型,不带人设、记忆或工具。

调用返回值
janus.complete({messages, model, temperature, max_tokens, system})字符串形式的回复文本。
janus.stream(same)一个文本块的异步迭代器。

decide

类型化决策:针对某些数据提出具名问题,在一次快速调用中得到每个答案及其概率和置信度。结果不会以文字形式写出,因此请把它用于判断(这条线索是否热门、这张工单属于哪个类别、它有多紧急),而计数、日期和阈值请留在你自己的代码中处理。应用的员工也可以用它的 decide 工具提出同样的问题,例如针对应用存储的记录。

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.
问题类型criteria答案
choice一个包含 2 到 255 个具名选项的对象,{option: description}。如果列表不完整,请添加一个兜底选项,例如 other。choice(选中的选项)、confidence(0 到 1),以及每个选项的 probabilities。
score一个包含 2 到 10 个有序等级的列表,从低到高排列。score(小数,0 表示第一个等级)、confidence,以及每个等级的 probabilities。
noul无:这个问题本身就是一条要判断的陈述。noul,即该陈述成立的概率。没有单独的置信度。
  • decide({state, questions}) 会解析为 {model, answers, usage},每个答案都以你为对应问题起的名称作为键。
  • state 是文本或任意 JSON。只保留问题需要的字段,并在 instructions 中用反引号写出这些字段的名称。整个问题都写在 instructions 中;问题的名称只用来标记答案。过长的 state 在发送前会从中间截短。
  • 它会抛出一个错误,错误消息就是原因。该错误没有状态码,所以如果需要区分不同情况,请比较消息内容:
    • 格式错误的问题,例如只有一个选项的 choice(机器人返回 400,并说明哪里有误)。
    • 所有者账户中已没有剩余的工作额度:“你已用完账户中包含的全部工作额度。请选择一个套餐或充值以继续。”(429)。在所有者添加套餐或充值之前,重试也没有用。
    • 同时进行的决策过多:“同时进行的决策过多。请稍后再试。”(429)。
    • 机器人未登录:“决策需要连接 NeboAI。请登录 NeboAI 后重试。”(503)。
    • 决策服务失败(502)。
  • 决策和任何模型调用一样,计入机器人所有者的 NeboAI 账户。参见价格。

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

相对路径会发送到应用的 sidecar,地址为 /apps/<id>/api/<path>。绝对的 http 或 https URL 会经过 Nebo 的代理,并且需要 network:<host> 或 network:*。

NeboWebSocket

new NeboAppSDK.NeboWebSocket() 会打开一个连接到应用员工的实时套接字,并以退避方式自动重连。它不接受参数,提供 send(data)、close()、onopen、onmessage、onerror 和 onclose。

surfaces 与 a2ui

surfaces.connect() 会打开应用的实时通道。目前它传送来自应用员工的交互式卡片:用你页面打包的 @a2ui/web_core 中的 MessageProcessor 调用 a2ui.init(processor)(SDK 本身没有渲染器)。一张卡片只会送达为其制作的那个应用,点击卡片会发送给该应用的员工;在卡片发送之后才打开的页面收不到它,因此请把页面必须始终显示的内容保存在 storage 中。

SDK 还定义了 text_content、state_delta 和 surface_update 等类型化事件,以及 surfaces.on(type, handler)、surfaces.send(name, payload) 和 surfaces.state。Nebo 目前还不会向应用页面发送这些事件,也没有任何东西会响应 send。如需实时数据,请使用 storage.onChange。

chat

在页面中嵌入 Nebo 与应用员工的聊天。

NeboAppSDK.chat.mount(document.getElementById('chat'), {
  placeholder: 'Ask about a deal',
  contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' });
调用行为
chat.mount(element, options)选项:placeholder、theme、height、borderless、contextId、scope。
chat.send(text)发送一条消息。
chat.setContext(context)设置员工看到的上下文;传入 null 则清除。
chat.onMessage(handler)接收消息。
chat.newThread()开始一个新会话。
chat.unmount()移除聊天。

配置

在 Nebo 内部,SDK 会自动找到应用 ID 和基础 URL。如果页面在其他地方提供,请调用 nebo.configure({appId, baseUrl}),或调用 NeboAppSDK.setAppId(id) 和 NeboAppSDK.setBaseUrl(url)。getAppId() 和 getBaseUrl() 可读取这两个值。