TypeScript SDK 시작하기

이 가이드는 서버 측 TypeScript 애플리케이션을 System One 호스팅 의사결정 API에 연결합니다. SDK를 설치하고, 플랫폼 API 키와 카탈로그 모델을 설정하고, 지원 메시지를 팀 선택·긴급도 점수·중복 청구 확률로 평가합니다. API는 의사결정을 반환할 뿐 티켓을 라우팅하거나 환불을 처리하거나 도구를 실행하지 않습니다.

답변 준비

Q: System One TypeScript SDK는 어떻게 시작하나요?
A: Install the System One TypeScript SDK, set your API key, choose a model such as Clef Flash or Jev, and call Choice, Score, or Noul for a typed decision from the hosted System One API.

Q: Credits?
A: 신규 계정은 가입 시 100 크레딧을 받으며, 크레딧은 만료되지 않습니다.

SDK 설정과 API 과금은 별개입니다

오픈소스 TypeScript SDK는 클라이언트, 어댑터, 타입이 있는 결과를 제공합니다. 설치해도 호스팅 계정이 생기거나 추론을 구매하지 않습니다. 호스팅 의사결정 API 호출은 선택한 모델의 현재 가격으로 System One 계정 크레딧을 사용합니다. SDK 설치는 가격제가 아닙니다.

이 가이드는 System One 플랫폼 API 키를 사용합니다. 다른 서비스에 직접 연결하려면 SDK 설치와 직접 서비스 어댑터를 따르세요. 그런 통합은 해당 서비스의 자격 증명과 과금을 사용합니다. SYSTEM_ONE_API_KEY에 제공자 키를 넣지 마세요.

1. API 키 만들기

System One에 로그인해 이메일 인증을 마치고 콘솔의 API keys를 여세요. 이름을 붙여 키를 만들고, 표시되는 시크릿을 복사하세요. 목록에는 접두사만 보이며 전체 시크릿은 나중에 다시 가져올 수 없습니다. 서버에 보관하고 프롬프트, 브라우저 코드, 로그, 버전 관리 대상에서 제외하세요.

신규 계정은 가입 시 100 크레딧을 받습니다. 콘솔에서 잔액을 확인하세요. 키를 더 만들어도 웰컴 크레딧이 늘지 않습니다.

2. 설치와 설정

SDK는 Node.js 20+를 지원합니다. 아래 명령은 **Node.js 22.18+**를 사용하며 .mts TypeScript 파일을 바로 실행할 수 있습니다.

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

패키지는 독립적으로 배포되며 모두 core@^0.8.0으로 해석됩니다. systemOneAdapter는 Clairic extract()(이미지 포함)를 인코딩하지만 evaluate() 이미지는 아직 인코딩하지 않습니다. 호스팅 Clef/Clef Flash/Clef Omni 의사결정 이미지는 표준 Fetch 예제를 사용하세요.

버전 관리에서 제외하는 로컬 .env 파일을 만드세요.

SYSTEM_ONE_API_KEY=replace-with-your-platform-key
SYSTEM_ONE_BASE_URL=https://system-one.dev/v1
SYSTEM_ONE_MODEL=YOUR_MODEL_ID

API는 문서 호스트가 아니라 메인 웹사이트 오리진을 사용합니다. YOUR_MODEL_ID는 지원되는 별칭이 아니라 자리표시자입니다. 카탈로그 항목의 정확한 name으로 교체하세요. 작업 키는 다릅니다: 새로운 논리 평가마다 임의 UUID를 새로 만들되, 그 작업을 재시도할 때는 같은 키와 완전한 요청을 유지하세요.

3. 첫 의사결정 보내기

예제는 하나의 공유 지원 메시지를 state로, 세 개의 이름 있는 질문을 사용합니다. choice()는 허용된 팀을, score()는 순서가 있는 긴급도 루브릭을, booleanQuestion()은 참/거짓 동작이 아니라 확률을 요청합니다.

decision.mts로 저장하세요.

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'I was charged twice for the same order.' },
    questions: {
      team: choice('Choose the team that should review this request.', {
        billing: 'Payments, invoices, and refunds',
        support: 'Technical troubleshooting',
        review: 'More context is needed',
      }),
      urgency: score('Rate urgency using this ordered rubric.', [
        'Can wait for normal review',
        'Needs a timely response',
        'Needs immediate human attention',
      ]),
      duplicate: booleanQuestion('Does the message report a duplicate charge?', {
        true: 'The same order was charged more than once',
        false: 'No duplicate charge is reported',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
});

console.log({
  team: result.answers.team.choice,
  distribution: result.answers.team.probabilities,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
  inputTokens: result.usage.inputTokens,
  model: result.model,
  requestId: result.response.requestId,
});

node --env-file=.env decision.mts

이 스크립트를 실행할 때마다 새 과금 작업이 시작됩니다. 입력이 같아도 그렇습니다. 작업은 메모리에만 있으므로 스크립트를 다시 실행하는 것은 타임아웃이나 크래시 후 복구가 아닙니다. 질문 개수와 전체 요청 크기가 선택한 모델의 현재 요율에 영향을 줍니다. 예상치와 잔액을 먼저 확인하세요.

4. 결과 읽기

• team.choice는 선언된 옵션 이름 중 하나이며 리터럴 타입이 보존됩니다.
• urgency.score는 세 단계 루브릭에서 0부터 2 사이의 소수일 수 있습니다.
• duplicate.probability는 P(true)이며 0부터 1 사이입니다. JavaScript boolean이 아닙니다.
• 선택적 통계와 토큰 수는 없으면 알 수 없는 상태로 남습니다. 0으로 바꾸지 마세요.

코어는 어댑터 간 결과를 정규화합니다. 와이어에서 booleanQuestion()은 type: 'noul'이 되고 답 필드 이름은 noul입니다. 코어는 type: 'boolean'과 probability를 노출합니다. 이 타입이 있는 결과는 정확한 HTTP 응답 본문이 아니며 모든 응답 헤더를 노출하지도 않습니다.

result.model을 함께 확인해 반환된 모델을 확인하고, 진단용으로 요청 ID를 보관하세요. 타입이 잘 맞은 답이 판단의 정확성을 증명하지는 않습니다. 티켓을 라우팅할지 사람 검토를 요구할지는 애플리케이션이 결정합니다. 답을 액션에 연결하기 전에 에이전트 통합과 실행 경계를 보세요.

크레딧

신규 계정은 가입 시 100 크레딧을 받고, 크레딧은 만료되지 않습니다. 비용은 요청 크기, 질문 개수, 모델 단가로 계산됩니다. 4KB마다 한 블록이고 작은 요청도 한 블록으로 계산합니다. blocks × questions × 단가. 실패한 호출은 과금되지 않습니다. 자세한 내용은 과금과 크레딧을 보세요.

다음 단계

• SDK 문서
• 의사결정 프리미티브
• API 레퍼런스
• 모델 선택
• 에이전트 통합
• 멱등성과 재시도