用 Pi SDK + Jev 搭一个自定义 Agent Harness：Gate / Routing / Verifiers 实战 · 干货攻略

• 链接: https://x.com/omarsar0/status/2102762406204076532
• 分类: x-tips
• 来源: X @{omarsar0}
• 作者: Jay
• 更新: 2026-09-27
• 仓库: earendil-works/pi

这是什么

本攻略解读 @omarsar0 于 2026 年 9 月 27 日发布的实操教程，主题是用 Pi SDK（TypeScript）+ Jev（TypeSafe AI 的决策模型）搭建自定义 Agent Harness，展示三个核心决策点的具体实现模式：Gate（门控）、Routing（路由）、Verifier（验证器）。

前置概念：传统 Agent 循环里，LLM 每做一次判断（如"这个工具调用安全吗"、"这个答案够不够好"）都要调一次完整聊天模型，既贵又慢。实际上大多数 Harness 为了省成本把这些检查跳过了——这正是自定义 Harness 的价值所在：用小型专用模型替代大模型做检查，把决策成本从每次几毛钱降到几乎为零。

为什么值得关注

分享者 @omarsar0（Oscar Martinez）是 DAIR.AI 的核心成员，长期输出高质量 AI 工程教程。他的教程特点是有官方源码、有 playground 可跑、有代码可改，不是空谈概念。

Jev 是什么：TypeSafe AI 的 Jev 是他们所谓"System One"模型的开山作——它不是传统 LLM，不生成文本，只做结构化决策（分类/评分/是非判断）。你把上下文（state）发过去，它回答每个问题时返回一个概率值，你用这个值去驱动代码逻辑。

为什么用 Jev 而不是普通 LLM 做判断：

数据来源：TypeSafe AI 官方博客（2026 年 9 月 15 日发布）

Pi SDK 是什么：earendil-works/pi 是一个 TypeScript 原生的 AI Agent 工具包，核心包包括：

• @earendil-works/pi-agent-core：Agent 运行时，含工具调用和状态管理
• @earendil-works/pi-ai：统一多提供商 LLM API（OpenAI / Anthropic / Google 等）
• @earendil-works/pi-coding-agent：交互式编程 Agent CLI
• @earendil-works/pi-telemetry：厂商中立的遥测契约

三个决策模式（教程核心）：

1. Gate（门控）：每次工具调用前问 Jev"这个操作安全吗？"，防止危险操作执行
2. Routing（路由）：问 Jev"这个任务该用哪个模型处理？"，自动选最优模型
3. Verifier（验证器）：任务完成后问 Jev"答案质量够不够？"，不够就重试或降级

核验过程

官方来源读取：

1. DAIR.AI Academy 教程页（https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness）：确认了 Harness 的定义、Jev 在 Agent 循环中的角色、以及三个模式（Gate/Routing/Verifier）的存在。教程可直接在 playground 运行并修改参数。
2. earendil-works/pi GitHub README（https://github.com/earendil-works/pi）：确认了 SDK 包结构、npm 安装方式、安全边界说明（Pi 默认无沙箱，需容器隔离）、以及不内置权限系统的设计决策。
3. TypeSafe AI 官方博客（https://typesafe.ai/blog/introducing-system-one-models-and-jev）：确认了 Jev 的技术规格——RLCD 训练方法、70–500ms 延迟、$0.042/MTok 定价、输出免费。明确了 Jev 不生成文本、不产生幻觉、并行采样架构。
4. LangChain 官方博客（https://www.langchain.com/blog/building-a-harness-with-jev）：补充了 Jev 的三种问题类型（Choice / Score / Noul），以及 LangChain TypeSafeClassifier 的集成方式作为对比参考。

交叉验证结论：

• TypeSafe 官方博客数据（194x faster, 445x cheaper）为"公司工作流评测的上限"，公司自己也声明"预期这在实际应用中处于高端"。这是合理的——实际加速比取决于任务复杂度，但 40x 以上的提升在决策类任务上有充分证据。
• Jev 不支持文本生成这一点来自两个独立来源（LangChain 博客 + TypeSafe 官方博客），结论一致。
• Pi SDK 的包结构通过 GitHub README 和 pi.dev 文档两个来源交叉确认一致。

无法核验处：教程中提到的"三个 Gate/Routing/Verifier 模式的具体实现代码"需登录 Academy playground 访问，X 帖仅给出教程链接而无内文代码片段。本攻略基于教程概述和 LangChain 同类教程推断模式逻辑，标注为"原帖主张"。

上手步骤

第一步：安装 Pi SDK

npm install --ignore-scripts
# 或按需安装单个包
npm install @earendil-works/pi-agent-core @earendil-works/pi-ai

第二步：安装 Jev SDK 并获取 API Key

Jev 通过 TypeSafe AI API 访问（目前是 Early Access）：

npm install @typesafe/ai-sdk  # 官方 SDK（如果已发布）
# 或直接调用 REST API

设置环境变量：

export TYPESAFE_API_KEY="your_key_here"

第三步：初始化 Jev Decision Client

import { TypeSafeClassifier } from "@typesafe/ai-sdk";

// 或者直接调 REST API
async function askJev(state: string, questions: Record<string, string>) {
  const response = await fetch("https://api.typesafe.ai/v1/jev", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TYPESAFE_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "jev-latest",
      state,
      questions
    }
  });
  return response.json();
}

第四步：实现 Gate 模式（工具门控）

在 Pi 的工具执行前插入 Jev 检查：

// 判断工具调用是否安全
const gateResult = await askJev(
  `User request: "${userMessage}"\nPlanned tool: ${toolName}\nTool args: ${JSON.stringify(toolArgs)}`,
  {
    is_dangerous: {
      type: "noul",
      instructions: "This tool call could harm the system, leak data, or perform an irreversible action"
    },
    needs_confirmation: {
      type: "noul", 
      instructions: "This action should require explicit user confirmation before proceeding"
    }
  }
);

if (gateResult.is_dangerous.noul > 0.7) {
  throw new Error("Tool call blocked by Jev gate");
}

第五步：实现 Routing 模式（模型路由）

根据任务类型自动选择最合适的模型：

const routingResult = await askJev(
  `Task: "${taskDescription}"\nAvailable models: fast-gpt, claude-3.5, gpt-4o`,
  {
    complexity: {
      type: "choice",
      options: ["fast-gpt", "claude-3.5", "gpt-4o"],
      instructions: "Which model best handles this task given its complexity and required quality?"
    }
  }
);

const selectedModel = routingResult.complexity.choice; // e.g. "fast-gpt"

第六步：实现 Verifier 模式（答案验证）

任务执行完毕后验证输出质量：

const verifyResult = await askJev(
  `Task: "${taskDescription}"\nLLM Response: "${llmResponse}"`,
  {
    is_accurate: {
      type: "noul",
      instructions: "The response correctly and completely answers the task"
    },
    quality_score: {
      type: "score",
      levels: ["poor", "acceptable", "good", "excellent"],
      instructions: "Rate the overall quality of this response"
    }
  }
);

if (verifyResult.is_accurate.noul < 0.8) {
  // 质量不够，重试或降级
  return retryWithModel(llmResponse, "claude-3.5");
}

第七步：运行完整 Harness

# 在 playground 中运行
# https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness

# 或本地运行
npm run build
./pi-test.sh

坑与适用边界

适用场景： - 构建自定义 Agent 循环（不用 LangChain / CrewAI 等现成框架） - 需要在每步做高频小决策（路由、门控、评分），但不想用贵的大模型 - 目标：把 Agent 决策成本从每次 ¥0.5+ 降到 ¥0.001 以下

不适用场景： - Jev 是纯决策模型，不能替代 LLM 做生成、推理、对话 - 复杂多步骤推理任务仍需要完整 LLM，Jev 只负责"旁边打分" - 目前 Jev 还在 Early Access，API 稳定性和用量配额需关注

Pi SDK 的安全边界（重要）：

Pi 默认不包含权限系统，以启动 Pi 的用户身份运行所有工具。若需隔离，用容器或沙箱（文档中有 Docker / Gondolin / OpenShell 三种方案）。

实测注意事项： - Jev 的"question in parallel"特性意味着一次问多个问题几乎不增加延迟，但 state 要够简洁（TypeSafe 建议短而密集的段落） - 概率阈值的设置需要根据业务场景调参，0.7 不是万能阈值

一句话结论

用 Pi SDK 搭 Harness、用 Jev 做每步决策检查，可以把 Agent 的"检查成本"从每次大模型调用的几毛钱降到毫秒级毫厘级，让每个工具调用、每个路由决策、每个答案验证都真正跑起来——这是构建可靠、生产级自定义 Agent 系统的核心架构模式。