加载 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() 可读取这两个值。