Jev Engineering：从零构建你的第一个 AI 代理"大脑"

设 key、装 SDK（SDK 会从环境变量读 key，默认用 jev-latest）：

复制export TYPESAFE_API_KEY="sk-..."

pip install typesafe-sdk        # Python 3.10+
npm install @typesafe-ai/sdk    # Node 20+

# 或直接调单端点：
# POST https://api.typesafe.ai/v1/systemone

退款工单完整示例：state 里放订单 A-104 的两笔 $49 captured 记录和退款政策，一次调用问四个问题（department 用 Choice、frustration 用 Score、refund_requested 和 policy_supports 用 Noul）：

复制from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient(model="jev-1.13.0")  # pin the version

response = client.system_one(
    state={
        "ticket": {"subject": "Duplicate charge",
                   "message": "I was charged twice for order A-104. Please refund the duplicate."},
        "order": {"id": "A-104",
                  "charges": [{"amount_usd": 49, "status": "captured"},
                               {"amount_usd": 49, "status": "captured"}]},
        "refund_policy": "Duplicate charges are eligible for a refund.",
    },
    questions={
        "department": Choice(
            instructions="Which team should handle this",
            criteria={"billing": "Payment or subscription issues",
                      "technical": "Bugs or integration problems",
                      "other": "Anything that does not fit the above"}),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=["Calm, just stating facts",
                      "Frustrated but civil",
                      "Very angry, strong language"]),
        "refund_requested": Noul(
            instructions="The customer is explicitly asking for a refund"),
        "policy_supports": Noul(
            instructions="The stated refund policy covers this situation"),
    },
)

dept = response.answers["department"]
print(dept.choice, dept.confidence)
print(response.answers["frustration"].score)
print(response.answers["refund_requested"].noul)

注意返回形状：答案都在 response.answers[...] 下，每种类型暴露自己的字段（.choice / .score / .noul）。

Jev 用 RLCD（Reinforcement Learning for Calibrated Decisions）训练：用结果而非人类偏好来优化概率，所以 confidence 在聚合层面有意义，可以按动作风险写"一动作一阈值"：

复制action = response.answers["intent"]
if action.confidence < 0.5:
    route_to_human(message)          # 真拿不准，永远升级
elif action.choice == "check_balance":
    show_balance(account_id)         # 只读操作，低门槛
elif action.choice == "approve_transfer":
    if action.confidence > 0.85:     # 动钱，高门槛
        prepare_transfer(account_id) # 只准备，绝不直接执行
    else:
        ask_user_to_confirm("Approve this transfer?")
else:
    route_to_human(message)

完整路由示例（含纯代码短路）：intent 是 order_status 且简单，直接走代码查单——完全跳过模型：

复制if intent.confidence < 0.5:
    return route_to_human(message)
if intent.choice == "order_status":
    return lookup_order(message)        # 纯代码，无模型
if intent.choice == "product_question":
    return handle_with_llm(message, PRODUCT_SPECIALIST)
if intent.choice == "complaint":
    if complexity.score > 1 or complexity.confidence < 0.5:
        return route_to_human(message)
    return handle_with_llm(message, COMPLAINT_RESOLUTION)
return route_to_human(message)

questions 是并行的：第十个问题只花 token、几乎不花时间。官方 cookbook 里 13 个问题一次调用，比逐个问便宜约 12 倍、快约 10 倍，答案相同。

Choice 实务：最多 255 个选项，每选项只花几个 token——传完整类别列表而非短名单，且永远加一个显式的 other 选项，让模型能说"都不 fit"。

Score 实务：2–10 个有序等级；score 可落在等级之间（如 1.035）；等级索引来自数组顺序，level 0 是第一个条目。Noul 实务：返回 .noul 单个数（0–1），没有独立 confidence 字段——这个数字本身就是信念。

级联的本质：Jev 不是替代 frontier 模型，而是"决定哪些请求配得上一个（frontier 模型）"。诊断信号：如果 probabilities 在选项间拉平，通常说明选项从 state 里区分不开——是 criteria 写错了，不是模型糊涂。

上下文限额：state 与所有 questions 合计 64k token；state + 单个最长 question 32k。

两条 operational 实务：① 当前限流 250,000 tokens/秒、1,200 请求/分钟，SDK 带退避重试；② 每次决策都记录模型版本、probabilities、confidence——作者原话："当 300 个退款请求以每个 $0.0004 的成本进了错误的队列，最高频那一层日志太薄，就再也重建不出现场。"