Jevの始め方とは｜HTTP API・Python SDK・JavaScript SDK・Vercel AI Gateway・Agentスキル

Jev（ジェヴ）を自分のコードから呼ぶには、何を用意すればよいのでしょうか。
結論から言うと、APIキーを1つ発行して環境変数に置けば、HTTP・Python・JavaScript・Vercel AI Gateway のどこからでも同じ1本のエンドポイントを呼べます。
業務の自動化に組み込むなら、まず1問だけ投げて応答の形を見てから SDK に移るのが近道です。

Jevの呼び出し口とは

TypeSafe AI の System One モデル「Jev」は、API リファレンスによると、POST の1本のエンドポイントで提供されています。
リクエストは state（状態）、model、questions（質問）の3つの必須フィールドで構成され、質問ごとの answers（回答）が同じキー名で返る仕組みです。
呼び出し方は HTTP、Python SDK、JavaScript SDK、Vercel AI Gateway の4系統で、質問設計を手伝う Agent スキルも公式に配布されています。

使い方｜6つの手順で試す

1. APIキーを発行して環境変数に置く

クイックスタートでは、キーはダッシュボードで発行すると説明されています。
取得したキーは環境変数 TYPESAFE_API_KEY に設定します。
SDK はこの環境変数を自動で読み、既定で jev-latest を呼ぶとされています。

2. HTTP API に1問だけ送る

POST https://api.typesafe.ai/v1/systemone に、Authorization: Bearer <API_KEY> ヘッダと JSON 本文を送ります。
API リファレンスの最小例は、支払い遅延の訴えに「緊急か」を Noul（ヌール、はい／いいえ型の質問）で聞くものです。

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

応答は model、answers、usage の3つで、上の例なら answers の is_urgent に "noul": 0.92 のような確率が返ると示されています。
エラーは 401（キーの欠落か無効）、422（本文の検証エラー）、429（レート制限超過）、529（一時的な過負荷）の4つが示されています。
429 と 529 は指数バックオフ（待ち時間を倍々に伸ばす再試行）で対応するよう案内され、公式 SDK は既定でこれを自動処理するとされています。

3. Python SDK を使う

Python SDK は Python 3.10 以上が必要で、pip install typesafe-sdk で導入します。
同期の TypeSafeClient と非同期の AsyncTypeSafeClient があり、質問は Noul、Choice、Score の3クラスで書きます。

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={
            "billing": Noul(instructions="Is this ticket about billing?"),
            "tone": Choice(
                instructions="What is the customer's tone?",
                criteria={"calm": None, "frustrated": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["can wait", "this week", "today"],
            ),
        },
    )

print(response.nouls["billing"].noul)
print(response.choices["tone"].choice)
print(response.scores["urgency"].score)

回答は response.answers["billing"] のようにキーで引けるほか、型ごとの nouls、choices、scores からも取れます。
非同期版は AsyncTypeSafeClient を async with で開き、await を付けて同じ system_one を呼ぶ形です。

4. JavaScript SDK を使う

JavaScript SDK は Node.js 20 以上が対象で、npm install @typesafe-ai/sdk で導入します。
公式例では new TypeSafeClient() を作り、client.systemOne({ state, questions }) に choice(...) で組んだ質問を渡し、response.answers.category.choice を読みます。
回答の型は質問から推論され、ESM、CommonJS、TypeScript の型定義が同梱されているとされています。

5. Vercel AI Gateway から呼ぶ

Vercel の告知によると、AI SDK 7.0.105 以降の experimental_evaluate から、モデル ID typesafe-ai/jev で Jev を呼べます。
渡すのは API と同じ model、state、questions です。
注意したいのは型名で、Gateway 側は「boolean」と呼びますが、TypeSafe の API では同じ質問型を「noul」と呼びます。
confidence は result.providerMetadata.typesafe.confidence に入り、providerOptions.gateway の zeroDataRetention: true でリクエスト単位のゼロデータ保持を有効にできると説明されています。

6. Agent スキルを入れる

Agent スキルは、3つの質問型と設計パターンをコーディングエージェントに読み込ませるものです。
Claude Code では次の2コマンドで入れ、/typesafe:typesafe-ai で呼び出せます。

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

他のエージェントでは npx skills add typesafe-ai/skills --skill typesafe-ai を実行し、対象を選びます。

活用例｜どんな業種・職種で使えるか

EC の問い合わせ対応では、Python SDK で受信メールを state に入れ、担当部署の Choice と緊急度の Noul を1回で取って振り分けを自動化できます。
返答文は生成しないので、定型文と組み合わせます。

Next.js で SaaS を作る Web 制作者は、Vercel AI Gateway 経由なら別の SDK を足さずに AI SDK の中で Jev を呼べます。
利用ログや予算も Gateway 側で管理できると案内されています。

士業やバックオフィスの個人事業者は、Claude Code に Agent スキルを入れ、手元のスクリプトのどこに判定を置けるか探らせる使い方が公式に例示されています。
質問文としきい値の定数だけを自分で確認する運用です。

つまずきポイント・注意点

422 は本文の形の問題です。criteria は Choice と Score では必須、Noul では任意とされています。
429 と 529 を即時に叩き直すと悪化します。HTTP 直接呼び出しなら指数バックオフを自分で実装します。
Gateway の「boolean」と API の「noul」は同じ質問型です。ドキュメント間を行き来するときに読み替えます。

まとめ｜Jevの始め方は「1問のHTTP呼び出し」から「SDKでの本番組み込み」への入り口にする

Jev の入口はどれも同じ1本のエンドポイントに集約され、違いは呼ぶ側の道具だけです。
核心は、state・model・questions を送れば同じキー名で answers が返るという単純な契約にあります。
次の一手は、1問だけ投げて数値を見てから、Python か JavaScript の SDK に質問を3つ載せ替えることです。