載入 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 在送出前會從中間截短。- 它會拋出錯誤,錯誤訊息就是原因。這個錯誤沒有狀態碼,所以若要區分不同情況,請比對訊息:
- 格式錯誤的問題,例如只有一個選項的選擇題(機器人會回應 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 網址則會經過 Nebo 的代理伺服器,並需要 network:<host> 或 network:*。
NeboWebSocket
new NeboAppSDK.NeboWebSocket() 會開啟一條連到應用程式員工的即時 socket,並以退避機制自動重新連線。它不接受任何引數,提供 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 會自行找到 app id 與 base URL。若頁面放在其他地方,請呼叫 nebo.configure({appId, baseUrl}),或 NeboAppSDK.setAppId(id) 與 NeboAppSDK.setBaseUrl(url)。getAppId() 與 getBaseUrl() 可讀回這些值。