NeboAI
NeboAI
시작하기

앱 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)직원(source: "employee") 또는 이 창을 포함한 앱의 열린 창(source: "page")이 쓸 때마다 handler({appId, keys, action, source})를 호출합니다. 수신을 멈추는 함수를 반환합니다.

누가 바꾸든 데이터가 바뀌면 다시 그리세요.

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 같은 접두사 아래 기록마다 키 하나), 직원의 지침에 그 키를 설명하세요. "42"처럼 그 자체로 유효한 JSON인 문자열은 파싱된 상태로 돌아오므로, 타입이 중요하다면 객체로 감싸세요. 각 값은 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답
choice2~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으로 응답).
    • 소유자 계정에 남은 작업량이 없음: "You've used all the work included in your account. Choose a plan or add credits to continue." (429). 소유자가 요금제나 크레딧을 추가하기 전까지는 재시도해도 소용없습니다.
    • 동시 판단 요청이 너무 많음: "Too many decisions at once. Try again in a moment." (429).
    • 봇이 로그인되어 있지 않음: "Decisions need NeboAI connected. Sign in to NeboAI and try again." (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');

상대 경로는 /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()로 값을 다시 읽을 수 있습니다.