Jev 사용법: 처음 시작하기 위한 가이드

Jev는 TypeSafe가 제공하는 판단 전용 AI 모델입니다. 글이나 코드를 쓰는 대신 고객 문의를 분류하거나 긴급도를 판단하는 등 프로그램에 필요한 값을 반환합니다. Claude Code나 Codex로 Jev를 사용하는 프로그램을 만들 수 있습니다. 이 글에서는 TypeSafe에 가입해 Playground에서 직접 시험하고, API로 연결하는 방법까지 살펴봅니다. Jev의 개념이 궁금하다면 Jev는 에이전트가 아닙니다를 참고하세요.

가장 쉬운 시작 방법은?

처음에는 TypeSafe Console의 Playground에서 직접 시험해보세요.

TypeSafe Console에 접속합니다.
Google 또는 이메일로 로그인합니다.
Jev가 읽을 문장을 입력합니다.
그 문장에 대해 판단할 질문을 추가합니다.
결과를 확인합니다.

결과를 살펴본 뒤 API나 SDK로 옮기면 됩니다.

Playground에서 테스트하기

예를 들어 고객 문의 한 건을 입력해봅시다.

결제 연동이 사흘째 되지 않아 주문을 받지 못하고 있습니다.
언제 복구되는지 알려주세요.

여기에 질문 하나를 추가합니다.

이 메시지에서 긴급한 상황이 드러나는가?

질문을 바꾸면 결과가 어떻게 달라지는지도 살펴보세요. 같은 문의에 다음을 물어볼 수도 있습니다.

이 문의는 기술 지원팀이 처리해야 하는가?
발신자가 답변을 요청하고 있는가?
현재 서비스 장애를 언급하고 있는가?

API로 연결하기

Playground에서 질문을 시험해봤다면 API로 내 프로그램에 연결할 수 있습니다. Jev 호출 주소는 다음과 같습니다.

POST https://api.typesafe.ai/v1/systemone

요청할 때는 판단할 내용인 state와 질문을 함께 보냅니다.

{
  "state": "결제 연동이 사흘째 되지 않아 주문을 받지 못하고 있습니다.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "이 메시지에서 긴급한 상황이 드러나는가?"
    }
  }
}

API 키는 TypeSafe Console에서 발급받습니다. 키가 공개되지 않도록 서버의 환경 변수에 보관하세요.

export TYPESAFE_API_KEY="발급받은_API_키"

전체 요청과 응답 형식은 TypeSafe Quick Start에서 확인할 수 있습니다.

어떤 질문을 보낼 수 있나요?

Jev에는 세 가지 질문 유형이 있습니다.

질문 타입	용도	예시
Choice	정해진 보기 중 하나를 선택합니다.	결제·기술 지원·영업 중 어디인가?
Score	정해둔 단계에 따라 정도를 평가합니다.	고객의 불만 정도는 어느 수준인가?
Noul	예·아니오로 답할 질문에 '예'일 확률을 반환합니다.	이 메시지는 긴급한가?

각 유형의 응답 형태는 TypeSafe 공식 문서에 나와 있습니다. 질문을 나눠 묻고 결과를 조합하는 방법은 Jev 활용 사례 글에서 살펴볼 수 있습니다.

Python SDK 사용하기

Python으로 개발한다면 SDK를 설치해 사용할 수 있습니다.

pip install typesafe-sdk

uv를 사용한다면 다음과 같습니다.

uv add typesafe-sdk

SDK를 사용하면 Python 코드에서 Choice, Score, Noul 질문을 만들고 응답을 받을 수 있습니다. 자세한 예제는 공식 Quick Start에 있습니다.

코딩 에이전트와 함께 사용하기

Claude Code나 Codex에서도 Jev를 활용할 수 있습니다. 코딩 에이전트가 Jev로 바뀌는 것은 아닙니다. 에이전트에게 Jev API를 사용하는 기능을 만들어달라고 요청하고, 완성된 프로그램이 필요한 순간에 Jev를 호출하는 방식입니다. TypeSafe의 코딩 에이전트 안내에서도 이 차이를 설명합니다.

TypeSafe 스킬을 설치하면 무엇이 달라지나요?

TypeSafe 스킬은 Jev의 질문 유형, API 사용법, 설계 예시를 코딩 에이전트에게 알려주는 자료입니다. Codex 등에서 다음 명령을 실행하면 설치 과정에서 사용할 에이전트를 선택합니다. 기본적으로 현재 프로젝트에 설치됩니다.

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

Claude Code에서는 TypeSafe 플러그인을 설치합니다.

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

명령을 실행하면 에이전트가 TypeSafe 스킬을 읽을 수 있게 됩니다. 이 단계에서 Jev API가 호출되거나 기존 코드가 바뀌지는 않습니다. API 키도 별도로 TypeSafe Console에서 발급받아야 합니다. 설치 과정은 TypeSafe의 공식 스킬 문서에서 확인할 수 있습니다.

설치 후에는 자동으로 사용되나요?

설치한 스킬을 에이전트가 관련 작업에서 참고할 수는 있지만, 모든 코딩 작업에 Jev가 자동으로 들어가지는 않습니다. 처음에는 “TypeSafe 스킬을 사용해 Jev를 연동해줘”처럼 스킬과 작업을 함께 말하는 것이 확실합니다. Claude Code에서는 /typesafe:typesafe-ai로 스킬을 직접 부를 수도 있습니다. 이때 에이전트는 스킬을 참고해 코드를 작성합니다. 실제 API 호출은 그 코드를 실행하거나, 에이전트에게 테스트를 요청했을 때 일어납니다.

기존 작업을 이렇게 바꿔보세요

지금까지 고객 문의를 한 건씩 Codex나 Claude Code에 붙여 넣고 “어느 팀이 처리해야 해?”라고 물었다면, 반복되는 분류를 Jev가 맡도록 기능을 만들어볼 수 있습니다. 에이전트에게는 다음처럼 요청하세요.

TypeSafe 스킬을 사용해서 이 프로젝트에 고객 문의 분류 기능을 만들어줘. 문의가 들어오면 Jev의 Choice로 결제, 기술 지원, 영업, 기타 중 하나를 고르고, 분류 결과의 confidence가 0.8보다 낮으면 담당자가 확인할 목록으로 보내줘. API 키는 서버의 환경 변수에서 읽고, 예시 문의로 분류 결과를 확인할 수 있게 해줘.

이 요청을 받은 에이전트는 Jev API 호출 코드와 결과 처리 규칙을 만듭니다. 이후 프로그램에서 문의가 들어오면 서버가 Jev에 내용을 보내고, Jev는 분류 결과를 돌려줍니다. 프로그램은 그 값에 따라 담당 팀으로 보내거나 사람에게 검토를 요청합니다. 이때는 문의마다 사용자가 코딩 에이전트를 열거나 스킬을 다시 부를 필요가 없습니다.

위 요청의 0.8은 설명을 위한 기준입니다. confidence는 보기별 확률이 한쪽으로 얼마나 몰렸는지 보여주는 값이며, 정답을 보장하지는 않습니다. 자동 처리 기준은 실제 문의로 시험하며 조정하세요. 고객에게 보낼 답장까지 필요하다면 답장 작성은 기존 코드나 GPT·Claude 같은 생성형 모델에 맡길 수 있습니다.

시작할 때 어디를 보면 될까요?

필요한 항목을 누르면 이 글의 설명이나 해당 공식 페이지로 이동합니다.

목적	바로가기
Jev의 역할 알아보기	Jev의 역할과 한계 살펴보기
가입·로그인하기	TypeSafe Console에서 가입하기
Playground 써보기	예시 문장으로 Jev 테스트하기
API로 연결하기	API 키와 요청 형식 확인하기
질문 유형 살펴보기	Choice·Score·Noul 알아보기
Python SDK 설치하기	Python 설치 명령 확인하기
Claude Code·Codex 활용하기	TypeSafe 스킬 설치와 사용법 보기

이제 직접 해보세요

먼저 Playground에서 문장 하나와 질문 하나로 시작해보세요. 어떤 답이 나오길 기대하는지 적어두고 실제 결과와 비교하면, 질문을 더 분명하게 다듬을 수 있습니다. 그다음 같은 질문을 API로 보내고, 반환값에 따라 프로그램이 무엇을 할지 정하면 됩니다.

Jev의 개념을 더 자세히 알고 싶다면 Jev는 에이전트가 아닙니다를, 질문 설계와 활용 사례가 궁금하다면 Jev로 무엇을 만들 수 있을까?를 참고하세요.