03 クイックスタート — APIの使い方としきい値設計

10分でJevのAPIを叩けるようにする章です。Python SDKでの基本形と、自動化の安全設計として重要な「しきい値設計」を扱います。

APIキーの取得

console.typesafe.ai にサインイン（早期アクセス）
ダッシュボードのKeysページでAPIキーを取得
環境変数 TYPESAFE_API_KEY に設定（SDKが自動読込）

⚠ APIキーの取り扱い 公式READMEの注意書きどおり、キーをコミットやソースファイルに書かないでください。環境変数で渡すのが基本です。

SDKのインストール

pip install typesafe-sdk
# または
uv add typesafe-sdk

Python 3.10 以上が必要です。

最初のAPI呼び出し（3プリミティブ混在）

公式クイックスタートのコード例です。1回の呼び出しでChoice/Score/Noulを混在できます:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()
response = client.system_one(
    state=ticket,  # 判断材料となる状態（テキスト・JSON等）
    questions={
        "department": Choice(
            instructions="この問い合わせをどの部署に振り分けるか",
            criteria={
                "technical": "技術的な不具合・エラー報告",
                "billing": "請求・支払いに関する問い合わせ",
            },
        ),
        "frustration": Score(
            instructions="顧客のフラストレーション度を10段階で採点",
            criteria=[
                "1: 平静",
                "5: 明らかな不満",
                "10: 激怒・解約の恐れ",
            ],
        ),
        "is_urgent": Noul(
            instructions="緊急対応が必要か（はい=1.0に近い値）",
        ),
    },
)

レスポンスの読み方

choice / score / noul — コードで直接分岐できる型付き値
confidence — 信頼度（0〜1）。「この答えを信用して自動化してよいか」の材料
probabilities — 確率分布。2位以下との差が小さければ曖昧な判断

if response.questions["department"].confidence >= 0.9:
    auto_route(response.questions["department"].choice)
else:
    queue_for_human_review(response.questions)

しきい値設計

公式のAPIリファレンスにしきい値の詳細な解説はないため（2026-09時点）、以下は公開事例・コミュニティ報告に基づく設計パターンです:

confidence域	挙動
0.9以上	自動で実行（例: 安いモデルへ切替）
0.6〜0.9	現状維持（自動切替しない＝何もしないが安全）
0.6未満・エラー・曖昧	人間確認に戻す

💡 Tip: 「何もしない」は安全側 曖昧な場合は必ず「人間確認」「現状維持」にフォールバックする設計にします。Jevを外したら既存の動作に戻る、という後方互換を保つと導入リスクが最小になります。

エンドポイントと仕様メモ

項目	値
エンドポイント	`POST https://api.typesafe.ai/v1/systemone`（Bearer認証）
デフォルトモデル	`jev-latest`（応答は`jev-1.13.0`のようなバージョン付き）
レート制限・コンテキスト長	2026-09時点で公式記載なし（要確認）

APIキーの取り扱い

環境変数で渡す（.secrets.env 等の一元管理推奨）
キーをリポジトリ・ログ・スクリーンショットに載せない

ここまででAPIは叩けます。次は、この仕組みをエージェントの「周辺仕組み（ハーネス）」に組み込む理論と実装です → 5層ハーネス理論・Claude Code統合