Jev AI는 입력 내용을 읽고 정해 둔 선택지나 점수로 판단 결과를 돌려주는 TypeSafe의 모델입니다. 한국어로 ‘제브 AI’라고도 부릅니다. 예를 들어 고객 문의가 ‘다음 결제를 멈춰 달라’는 뜻인지, ‘이미 낸 돈을 돌려 달라’는 뜻인지 구분하는 데 사용할 수 있습니다.

처음이라면 웹 Playground에서 동작을 확인하고, 프로그램에 연결할 때 SDK나 코딩 에이전트 스킬을 선택하면 됩니다. 여기서 설치하는 것은 연결용 패키지·스킬이며, 모델 파일을 PC에 내려받는 과정은 아닙니다. 아래 예제는 2026년 9월 29일, JavaScript SDK 0.6.0과 Jev 1.13.0으로 실행을 확인했습니다.

먼저 사용할 방식을 고르기

시작 방법은 만들려는 것에 따라 고르면 됩니다.

지금 하려는 일 선택할 방법 준비할 것
코드를 쓰기 전에 판단 결과부터 보기 웹 Playground TypeSafe 로그인과 이용 가능한 계정
Codex·Claude Code에 구현을 맡기기 공식 TypeSafe 스킬 코딩 에이전트와 API 키
내 프로그램에서 직접 호출하기 JavaScript SDK Node.js와 API 키

설치 없이 시험하려면 공식 Playground에 로그인해 입력 상태인 state와 질문을 작성합니다. 질문 형식은 참·거짓을 묻는 Noul, 선택지 중 하나를 고르는 Choice, 기준에 따라 점수를 매기는 Score가 있습니다. 이 글의 예제에는 Choice가 맞습니다.

Jev는 긴 답변을 작성하는 대화형 모델과 역할이 다릅니다. 취소·환불 중 하나를 고르면, 그 결과에 따라 안내문을 보여 주거나 담당자에게 전달하는 흐름은 프로그램이 처리합니다. 스킬을 설치했다고 Codex나 Claude Code의 기본 모델이 Jev로 교체되는 것도 아닙니다.

API 키 발급과 환경변수

TypeSafe API 키 페이지에 로그인한 뒤 페이지 안내에 따라 키를 준비합니다. 가입·이용 조건과 사용 가능한 잔액은 자신의 계정에서 확인하세요. 설치 명령이 무료로 실행된다는 것과 API 호출이 무료라는 것은 별개입니다.

키는 코드에 직접 적지 않고 TYPESAFE_API_KEY라는 환경변수로 전달합니다. 아래 두 명령 중 사용 중인 터미널에 맞는 하나만 실행하고, 발급받은_API_키를 자신의 키로 바꿉니다.

Windows PowerShell:

$env:TYPESAFE_API_KEY = "발급받은_API_키"

macOS·Linux의 bash 또는 zsh:

export TYPESAFE_API_KEY="발급받은_API_키"

위 설정은 현재 터미널 세션에서 사용합니다. 뒤의 node example.mjs도 같은 터미널에서 실행하세요. 이미 켜 둔 코딩 에이전트 앱에는 이 값이 자동으로 전달되지 않을 수 있습니다. 에이전트로 실행한다면 해당 앱이나 CLI가 API 키를 읽을 수 있는지도 따로 확인해야 합니다.

키가 들어간 화면을 공유하거나 Git에 올리지 마세요. 웹사이트에 연결할 때도 키를 HTML이나 브라우저 JavaScript에 넣지 않고 서버에서 호출해야 합니다.

코딩 에이전트에 스킬 설치

에이전트에게 Jev를 이용한 기능 구현을 맡길 때는 공식 TypeSafe 스킬을 설치합니다. npx를 사용할 수 있는 터미널에서, 적용할 프로젝트 폴더로 이동한 뒤 실행합니다.

npx skills add typesafe-ai/skills --skill typesafe-ai

설치 도구가 대상 에이전트를 물으면 실제 사용하는 Codex·Claude Code 등을 선택합니다. 기본은 프로젝트 범위입니다. 여러 프로젝트에서 공통으로 쓸 때는 위 명령 끝에 -g를 붙여 전역 범위를 선택합니다. 같은 스킬을 양쪽에 반복 설치할 필요는 없습니다.

설치 후에는 “TypeSafe 스킬을 사용해서 고객 문의를 취소·환불·기타로 분류하는 Node.js 예제를 만들어 줘. API 키는 환경변수에서 읽어 줘”처럼 요청하면 됩니다. 스킬은 에이전트에 공식 문서와 구현 방법을 알려주는 안내서이므로, 실제 API를 호출할 코드와 실행 환경은 별도로 필요합니다.

Codex에서 스킬이 보이지 않으면 설치한 대상과 범위를 먼저 확인하세요. 공식 안내상 사용자 공통 스킬 위치는 ~/.agents/skills, 프로젝트 위치는 .agents/skills입니다. 새 스킬을 인식하지 못할 때는 Codex를 다시 시작합니다.

코드에서 직접 호출하는 방법

직접 실행하려면 Node.js 공식 다운로드에서 현재 지원하는 LTS 버전을 설치합니다. SDK 요구사항은 Node.js 20 이상이고, 아래 검증에는 24.19.0을 사용했습니다. 터미널에서 node --version과 npm --version이 출력되는지 먼저 확인하세요.

빈 예제 폴더를 만들고 SDK를 설치합니다. 재현할 수 있도록 검증한 버전인 0.6.0을 지정했습니다.

mkdir jev-example
cd jev-example
npm init -y
npm install @typesafe-ai/sdk@0.6.0

같은 폴더에 example.mjs 파일을 만들고 다음 코드를 저장합니다. .mjs 확장자를 사용하면 이 예제의 import 문을 그대로 실행할 수 있습니다.

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

if (!process.env.TYPESAFE_API_KEY?.trim()) {
  throw new Error("TYPESAFE_API_KEY를 먼저 설정하세요.");
}

const client = new TypeSafeClient({
  retry: { maxRetries: 0 },
  logLevel: "off",
});

const result = await client.systemOne({
  model: "jev-1.13.0",
  state: {
    message: "다음 달 해지가 아니라 어제 결제한 돈을 돌려받고 싶어요.",
  },
  questions: {
    intent: choice("message에서 원하는 처리를 하나 고르세요.", {
      cancel: "앞으로의 정기 결제 중단을 요청한다.",
      refund: "이미 결제한 금액의 반환을 요청한다.",
      other: "둘 다 아니거나 원하는 처리를 판단할 수 없다.",
    }),
  },
});

console.log(JSON.stringify(result, null, 2));

앞에서 API 키를 설정한 터미널에서 실행합니다.

node example.mjs

state.message가 읽을 내용이고, choice() 안에는 물을 질문과 선택 기준이 들어갑니다. other는 어느 쪽인지 판단할 수 없는 입력을 받기 위한 선택지입니다. 처음 연결 상태를 확인하기 쉽도록 자동 재시도는 껐습니다. Python으로 연결하려면 공식 Python SDK 안내를 따라가면 됩니다.

한국어 예제의 실행 결과

위 코드를 실행했을 때 answers.intent.choice는 refund였습니다. 응답 전체 중 선택 결과와 사용량을 추리면 다음과 같습니다.

model: jev-1.13.0
answers.intent.choice: refund
usage.input_tokens: 398
usage.output_tokens: 38

입력 문장만 바꾼 두 번째 실행도 확인했습니다.

입력 문장 실제 선택
다음 달 해지가 아니라 어제 결제한 돈을 돌려받고 싶어요. refund
어제 결제한 돈은 그대로 두고 다음 달부터 자동 결제만 멈춰 주세요. cancel

이 결과는 시험용으로 작성한 두 문장에서 취소와 환불을 구분했다는 뜻입니다. 모든 한국어 문장에 대한 정확도를 보여 주지는 않습니다. TypeSafe는 영어를 주된 언어로 안내하며 한국어 등 CJK 언어에서는 성능 차이가 있을 수 있다고 설명합니다.

응답의 confidence도 정답 보증서가 아닙니다. 선택지 확률이 얼마나 한쪽에 모였는지에 관한 값입니다. 실제 환불 승인처럼 결과가 중요한 기능에 붙일 때는 애매한 문장과 복합 요청도 시험하고, 결과만으로 바로 처리하지 않도록 확인 절차를 둬야 합니다.

호출 비용과 사용량 확인

2026년 9월 29일 공식 모델 안내의 Jev 단가는 입력 100만 토큰당 0.042달러, 출력 토큰 무료입니다. 한글 글자 수를 토큰 수로 대신 계산하지 말고 응답의 usage.input_tokens를 확인합니다.

실행 입력 토큰 공개 단가로 계산한 비용
위 환불 예제 1회 398 0.000016716달러
취소 예제까지 2회 합계 797 0.000033474달러

계산식은 입력 토큰 × 0.042 ÷ 1,000,000입니다. 위 값은 단가에 따른 추정액이며 계정의 실제 청구액·최소 충전액·무료 크레딧을 확인한 수치는 아닙니다.

별도의 한국어 검색 의도 비교 시험 24건에서는 입력 82,557토큰을 사용했고, 같은 단가로 약 0.00347달러였습니다. 요청부터 JSON 수신까지의 중앙값은 206ms였습니다. 긴 기존 원고를 함께 보낸 시험이라 이 글의 짧은 예제와 입력 크기가 다릅니다.

24건 모두 사전에 정한 기대 분류와 일치했지만, 질문과 기대 분류를 Codex가 작성한 소규모 시험입니다. 독립 검수된 정답 집합이나 서비스 응답속도 보장으로 해석할 수 없습니다. 처음에는 작은 입력으로 결과와 사용량을 함께 확인하는 편이 좋습니다.

실행이 안 될 때 확인할 것

막힌 지점에 따라 확인할 곳이 달라집니다.

증상 먼저 확인할 것
node·npm·npx 명령을 찾지 못함 Node.js 설치와 터미널 재시작, 명령 경로 확인
TYPESAFE_API_KEY를 먼저 설정하세요. 예제 자체가 내는 오류. 키를 설정한 터미널에서 실행했는지 확인
@typesafe-ai/sdk를 찾지 못함 example.mjs가 있는 폴더에서 SDK를 설치했는지 확인
인증 실패 또는 권한 오류 키의 유효 여부와 해당 계정의 API 이용 권한 확인
스킬은 보이지만 API 실행이 안 됨 스킬 설치와 별도로 실행 환경에 키·SDK가 준비됐는지 확인

키 누락 오류는 환경변수를 뺀 상태에서 실제로 재현했고, API 요청 전에 중단되는 것을 확인했습니다. 나머지는 연결 환경에 따라 점검할 항목입니다. 오류를 문의할 때는 키를 제외한 오류명·SDK 버전·실행 명령만 공유하세요.

결과가 나오는데 분류가 틀렸다면 설치 문제와 구분해야 합니다. 입력에 필요한 정보가 있는지, 선택지의 경계가 겹치지 않는지 먼저 살펴보세요. 타입에 맞는 결과가 돌아와도 내용상 오판은 가능합니다. 정확한 날짜 차이나 금액 계산은 일반 코드로 처리하고, Jev에는 문장의 의미를 판단할 부분을 맡기는 편이 맞습니다.

참고 자료