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 | 답 |
|---|---|---|
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으로 응답).
- 소유자 계정에 남은 작업량이 없음: "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()로 값을 다시 읽을 수 있습니다.