NeboAI
NeboAI
開始使用

App SDK

App 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。
score2 到 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() 可讀回這些值。