NeboAI
NeboAI
Bắt đầu

App SDK

App SDK kết nối trang của ứng dụng với Nebo. Đó là một script mà Nebo phục vụ cho mọi ứng dụng, và nó đặt một biến toàn cục duy nhất lên trang, NeboAppSDK. Không có gì cần cài đặt hay build.

Nạp SDK

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

Biến toàn cục là NeboAppSDK; không có biến toàn cục nebo. NeboAppSDK.nebo là thực thể SDK, và mọi mô-đun cũng được xuất ở cấp cao nhất, nên NeboAppSDK.storage và NeboAppSDK.nebo.storage là cùng một đối tượng. Để tránh che khuất API của trình duyệt, nebo.fetch được xuất dưới tên neboFetch và nebo.WebSocket dưới tên NeboWebSocket.

identity

Lệnh gọiTrả về
identity.get(){id, name, displayName, description, persona, model, skills, inputValues} của nhân viên thuộc ứng dụng. Được lưu đệm.
identity.invalidate()Xóa bộ nhớ đệm.

storage

Kho khóa-giá trị cho ứng dụng. Cần storage:readwrite. Đây cũng chính là kho mà nhân viên của ứng dụng đọc và thay đổi: một bản ghi chủ sở hữu thêm bằng cách trò chuyện với nhân viên sẽ hiện trên trang, và một bản ghi nhập vào trang là bản ghi nhân viên có thể tìm thấy.

const deals = (await NeboAppSDK.storage.getItem('deals')) ?? [];
deals.push({ name: 'Example renewal', closes: '2026-10-31' });
await NeboAppSDK.storage.setItem('deals', deals);
Lệnh gọiHành vi
storage.getItem(key)Đúng những gì setItem đã lưu (đối tượng, danh sách, số hoặc chuỗi), hoặc null.
storage.setItem(key, value)Lưu bất kỳ giá trị JSON nào.
storage.removeItem(key)Xóa một khóa; khóa đó không còn xuất hiện trong keys().
storage.keys()Mọi khóa.
storage.clear()Xóa mọi khóa.
storage.onChange(handler)Gọi handler({appId, keys, action, source}) sau mỗi lần ghi, bởi nhân viên (source: "employee") hoặc bởi bất kỳ cửa sổ nào đang mở của ứng dụng, kể cả cửa sổ này (source: "page"). Trả về một hàm để ngừng lắng nghe.

Vẽ lại khi dữ liệu thay đổi, bất kể ai thay đổi:

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

Chỉ nhân viên của chính ứng dụng mới truy cập được kho này, và chỉ cho ứng dụng của nó; nhân viên khác phải hỏi nhân viên của ứng dụng. Chọn các khóa mà cả hai bên đều tìm được (một khóa chứa một danh sách, hoặc mỗi bản ghi một khóa dưới một tiền tố như deal:42) và mô tả chúng trong chỉ dẫn của nhân viên. Một chuỗi bản thân là JSON hợp lệ, chẳng hạn "42", sẽ được trả về ở dạng đã phân tích, nên hãy bọc nó trong một đối tượng nếu kiểu dữ liệu quan trọng. Giữ mỗi giá trị nhỏ hơn nhiều so với 2 MB; setItem không ném lỗi khi một lần ghi bị từ chối.

agents

Hỏi nhân viên của ứng dụng, hoặc một nhân viên khác, và nhận câu trả lời. Hỏi nhân viên khác cần 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;
}
Lệnh gọiTrả về
agents.invoke(message, {agent, data}){text, tools} khi nhân viên hoàn tất.
agents.stream(message, {agent, data})Một async iterator của {text, done}.

janus

Một lệnh gọi mô hình trực tiếp, không có tính cách, bộ nhớ hay công cụ.

Lệnh gọiTrả về
janus.complete({messages, model, temperature, max_tokens, system})Văn bản trả lời dưới dạng chuỗi.
janus.stream(same)Một async iterator của các đoạn văn bản.

decide

Quyết định có kiểu: đặt các câu hỏi có tên về một dữ liệu nào đó và nhận lại từng câu trả lời kèm xác suất và độ tin cậy, chỉ trong một lệnh gọi nhanh. Không có gì được viết ra dưới dạng văn bản, nên hãy dùng nó cho các phán đoán (khách hàng tiềm năng này có tiềm năng cao không, phiếu hỗ trợ này thuộc danh mục nào, mức độ khẩn cấp ra sao) và giữ việc đếm, ngày tháng và ngưỡng trong mã của bạn. Nhân viên của ứng dụng có thể hỏi cùng các câu hỏi đó bằng công cụ decide, ví dụ trên các bản ghi đã lưu của ứng dụng.

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.
Loại câu hỏicriteriaCâu trả lời
choiceMột đối tượng gồm 2 đến 255 phương án có tên, {option: description}. Thêm một phương án thoát như other khi danh sách chưa đầy đủ.choice (phương án được chọn), confidence (từ 0 đến 1) và probabilities cho từng phương án.
scoreDanh sách từ 2 đến 10 mức có thứ tự, thấp nhất trước.score (số thập phân, 0 là mức đầu tiên), confidence và probabilities cho từng mức.
noulKhông có: câu hỏi là một nhận định cần đánh giá.noul, xác suất nhận định là đúng. Không có độ tin cậy riêng.
  • decide({state, questions}) trả về {model, answers, usage}, với mỗi câu trả lời nằm dưới tên bạn đã đặt cho câu hỏi tương ứng.
  • state là văn bản hoặc bất kỳ JSON nào. Chỉ giữ các trường mà câu hỏi cần và gọi tên các trường đó trong dấu backtick bên trong instructions. Toàn bộ câu hỏi nằm trong instructions; tên câu hỏi chỉ dùng để gắn nhãn câu trả lời. State quá dài sẽ được rút gọn ở phần giữa trước khi gửi.
  • Hàm ném ra một lỗi có thông điệp là lý do. Lỗi không có mã trạng thái, vì vậy hãy so sánh thông điệp nếu bạn cần phân biệt các trường hợp:
    • Câu hỏi sai định dạng, chẳng hạn một lựa chọn chỉ có một phương án (bot trả về 400, kèm thông tin lỗi).
    • Tài khoản của chủ sở hữu đã hết công việc: "Bạn đã dùng hết khối lượng công việc có trong tài khoản. Hãy chọn một gói hoặc nạp thêm tín dụng để tiếp tục." (429). Thử lại sẽ không có tác dụng cho đến khi chủ sở hữu thêm gói hoặc tín dụng.
    • Quá nhiều quyết định cùng lúc: "Quá nhiều quyết định cùng lúc. Vui lòng thử lại sau giây lát." (429).
    • Bot chưa đăng nhập: "Quyết định cần kết nối NeboAI. Hãy đăng nhập NeboAI và thử lại." (503).
    • Dịch vụ quyết định gặp lỗi (502).
  • Quyết định được tính phí vào tài khoản NeboAI của chủ sở hữu bot như mọi lệnh gọi mô hình khác. Xem bảng giá.

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

Đường dẫn tương đối được gửi tới sidecar của ứng dụng tại /apps/<id>/api/<path>. URL http hoặc https tuyệt đối đi qua proxy của Nebo và cần network:<host> hoặc network:*.

NeboWebSocket

new NeboAppSDK.NeboWebSocket() mở một socket trực tiếp tới nhân viên của ứng dụng và tự kết nối lại với backoff. Nó không nhận đối số và có send(data), close(), onopen, onmessage, onerror và onclose.

surfaces và a2ui

surfaces.connect() mở kênh trực tiếp của ứng dụng. Hiện tại kênh này mang các thẻ tương tác từ nhân viên của ứng dụng: gọi a2ui.init(processor) với một MessageProcessor từ @a2ui/web_core, do trang của bạn đóng gói kèm (SDK không có trình hiển thị riêng). Một thẻ chỉ đến được ứng dụng mà nó được tạo cho, một cú nhấp vào thẻ sẽ đến nhân viên của ứng dụng đó, và một trang mở sau khi thẻ đã được gửi sẽ không nhận được thẻ, vì vậy hãy giữ những gì trang luôn phải hiển thị trong storage.

SDK cũng định nghĩa các sự kiện có kiểu như text_content, state_delta và surface_update, với surfaces.on(type, handler), surfaces.send(name, payload) và surfaces.state. Nebo hiện chưa gửi các sự kiện đó tới trang ứng dụng, và chưa có gì phản hồi send. Với dữ liệu trực tiếp, hãy dùng storage.onChange.

chat

Nhúng cuộc trò chuyện của Nebo với nhân viên của ứng dụng vào trang.

NeboAppSDK.chat.mount(document.getElementById('chat'), {
  placeholder: 'Ask about a deal',
  contextId: 'deal-42'
});
NeboAppSDK.chat.setContext({ deal: 'Example renewal' });
Lệnh gọiHành vi
chat.mount(element, options)Tùy chọn: placeholder, theme, height, borderless, contextId, scope.
chat.send(text)Gửi một tin nhắn.
chat.setContext(context)Đặt ngữ cảnh mà nhân viên nhìn thấy; null sẽ xóa ngữ cảnh.
chat.onMessage(handler)Nhận tin nhắn.
chat.newThread()Bắt đầu một luồng mới.
chat.unmount()Xóa cuộc trò chuyện.

Cấu hình

Bên trong Nebo, SDK tự tìm app id và base URL. Với một trang được phục vụ ở nơi khác, hãy gọi nebo.configure({appId, baseUrl}), hoặc NeboAppSDK.setAppId(id) và NeboAppSDK.setBaseUrl(url). getAppId() và getBaseUrl() đọc lại các giá trị đó.