使用 Pi 和 Jev 构建自定义工具链

AI 智能体是一个在循环中工作的语言模型。它读取任务，使用如“读取此文件”或“删除那个文件”等工具，查看结果，并持续工作直到任务完成。每次模型请求使用工具时，该请求被称为一个工具调用。

运行这个循环的代码被称为工具链。模型决定它想做什么，工具链执行它，并决定模型被允许做什么。

一个优秀的工具链会在过程中做出许多小决策。哪个模型应该处理这个请求？这个工具调用运行是否安全？这个答案是否足够好可以返回？大多数工具链通过向聊天模型提问并读取其回复来回答这些问题。这每次都耗费一次完整的模型调用，因此在实践中，大多数检查都被跳过了。

来自 TypeSafe AI 的 Jev 是一个专门为这些决策而构建的小型模型。你描述情况并提出几个问题，它用数字回答每个问题，从不生成文本。

这一点在你构建自定义工具链时最为重要——即你自己的智能体循环，而非使用现成的智能体。自定义工具链让你选择运行哪个模型、智能体可以接触什么、以及什么算作完成。Jev 使得这些选择背后的检查成本低廉，足以在每个步骤上运行。

在本教程中，你将使用 Pi SDK（一个用于构建智能体的 TypeScript 工具包）构建一个工具链，并在三个地方使用 Jev。最后，你将在一个实时沙盒中运行完成的工具链，并自己调整其设置。

访问完整的交互式教程和游乐场： https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness

本指南的灵感来源于 Sydney Runkle 在 LangChain 博客上的文章《使用 Jev 构建工具链》，该文章展示了模型路由和工具门控作为现成的 LangChain 中间件。在这里，你将在 Pi SDK 上自行构建相同的想法，然后添加另外两个模式来处理故障和检查答案。

你将构建什么

该工具链包含三个部分。每一部分在不同的时刻向 Jev 提问一个问答，本指南的其余部分将用这些名称来指代它们。

运行示例是一个在步道调查笔记文件夹中工作的智能体，每次外出活动一个文件。它可以读取、写入，甚至真正删除这些笔记，这就是门控如此重要的原因。

Jev 是什么

TypeSafe 称 Jev 为一个 System One 模型。这个名字来自心理学家丹尼尔·卡尼曼，他描述了两种思维模式。System One 是快速且自动化的，就像知道锅是热的一样。System Two 是缓慢且审慎的，就像做长除法一样。

在这个工具链中，常规语言模型执行阅读文件和撰写答案的缓慢工作。Jev 负责其周围快速的判断。Jev 足够便宜和快速，可以询问每一次工具调用，而不仅仅是你预期会有风险的那些。

每个数字都是一个 0 到 1 之间的概率值。0.83 表示 Jev 相当确信答案是肯定的。0.03 表示它相当确信答案是否定的。

三种问题类型

每个 Jev 请求都有两部分。状态是你希望被判断的情况，例如一个工具调用或用户的请求。问题是关于它你想知道什么。Jev 在一次调用中同时回答所有问题，因此问三个问题所需时间与问一个问题差不多。

Jev 支持三种问题。第一种，Jev 称之为 noul，是一个是否问题。

Jev 只知道你告诉它什么，所以请用清晰的语言描述每个选项和每个级别。这些描述就是提示。

设置

Jev 可以通过 OpenRouter 获得，这是一个提供众多 AI 模型的服务，只需一个 API 密钥。这个密钥同时涵盖语言模型和 Jev。安装两个 Pi 包并设置你的密钥。

Jev 有其自己的网址，与常规聊天地址分开。请始终指定确切的版本，例如 typesafe/jev-1.13。整个 Jev 客户端就是一个 fetch 调用。

智能体在 Jev 回答时会等待，因此调用会在两秒后放弃。正常的回答需要 200 到 400 毫秒。

Jev 插入的位置

Pi 的 Agent 类为你运行循环。它允许你自己的代码在该循环的特定时刻运行。这些点被称为钩子。工具链为它的三个部分各使用一个钩子。

第一道门控

从最小可用版本的门控开始。在每次工具调用前，向 Jev 问一个是否问题，如果答案看起来是肯定的，则阻止该调用。

0.65 是一个阈值，是工具链停止信任调用的临界点。Jev 评分等于或高于该阈值的任何调用都会被阻止。

现在，一个试图删除你的笔记的智能体在删除发生前就会停止。删除笔记的评分约为 0.83，而读取一个评分为 0.01。然而，门控是粗糙的。写入一个全新文件的评分约为 0.70，所以这也会被阻止。

询问的成本非常低。Jev 每百万输入代币收费 0.042 美元，低于本工具链使用的两种模型中更便宜的 GLM 5.3 Flash 输入价格的三分之一。

从第一道门控到完整工具链

第一道门控有效，但它留下了四个缺口。

• 阈值隐藏在钩子内部，因此难以调整或测试。
• 每个请求无论难易都在同一个模型上运行。
• 没有说明如果无法联系到 Jev 会发生什么。
• 没有检查最终答案是否足够好。

以下编号部分中的每一部分都弥补了一个缺口。

1. 将阈值集中管理

本节改进门控。

阈值决定了智能体可以做什么，一旦你看到实际结果，你将会频繁调整它们。因此，将它们从钩子中移出，放入一个普通的函数 decideGate() 中。它接受 Jev 的数字并返回一个裁决：工具链对调用的最终决定。将这些规则集中管理被称为策略。

策略还增加了一个中间选项。一个阈值只能表示允许或阻止。两个阈值则提供三种裁决。

• 等于或高于 blockAt，调用被阻止。
• 低于 askAt，调用运行。
• 介于两者之间，调用等待人员批准。

这个中间范围捕获了 Jev 不确定的调用，而单一的截断点可能会错误地处理这些调用（无论是允许还是阻止）。

由于它是一个普通函数，你可以通过传入类似上面的数字来测试它，而无需使用实时模型。

2. 为每个请求选择模型

本节添加路由器。

有些请求很容易，比如读取一个文件。有些很难，比如追踪某物为什么坏了。在所有情况下都运行最强大的模型会浪费金钱，而在所有情况下都运行廉价模型则会为困难的请求提供薄弱的答案。路由器将每个请求匹配到正确的层级，即快速便宜的模型或强大昂贵的模型。

在请求开始之前，路由器在一次调用中向 Jev 提出两个问题。一个选项选择层级，一个分数评估请求的复杂度。

路由器的策略这样使用这两个答案。

• 如果复杂度分数很高，使用强大的模型，即使 Jev 选择了快速模型。
• 如果 Jev 对其选择不自信，使用强大的模型以确保安全。
• 否则，使用 Jev 选择的模型。

这是一个策略示例。你的策略可以根据你的领域以不同方式权衡答案，例如，对于大批量作业倾向于便宜模型，或者对于任何涉及生产环境的请求总是升级处理。Jev 只提供答案；你的代码决定如何处理它们。

为什么只选择一次

路由器在请求开始时选择一次模型，并在请求完成前保持该模型。这是由于提示缓存。

每当智能体迈出一步，模型都会重新阅读整个对话历史。AI 提供商会存储最近阅读过的对话，以便重新阅读时成本较低。但每个模型都有自己的存储。中途切换模型意味着新模型必须以全价重新阅读所有内容。

Jev 创始人在一篇关于编码智能体的设计文档中详细计算了这些数字。在一个长会话中，从 Claude Opus 切换到更便宜的 Sonnet 再切回来，比全程使用 Opus 多花了大约 50%。因此，在对话还很短时选择模型，并坚持使用它。

3. 为 Jev 故障做准备

本节同时改变门控和路由器。

一旦工具链为每次工具调用询问 Jev，智能体就依赖于 Jev。像任何在线服务一样，Jev 可能会变慢或宕机。提前决定当它无法得到答案时，每个部分该做什么。每个部分的正确选择是不同的。

门控阻止调用。 如果门控无法询问 Jev，它不知道调用是否安全。让它通过可能会删除文件，因此门控拒绝执行。工程师称之为失败关闭，就像断电时锁上的门。

路由器使用强大的模型。 如果路由器无法询问 Jev，它不知道请求有多难。强大的模型可以处理任何事情，因此请求仍然能得到良好的答案，你只需多付一点钱。这是失败开放，让工作继续进行。

4. 验证答案

本节添加验证器。在智能体工具链中，验证器是在工作被计为完成之前检查智能体工作的步骤。

智能体可能以一个遗漏信息或声称它从未实际检查文件中的事项的答案结束。阅读者通常无法分辨。在返回答案之前检查它，可以在智能体仍能再次尝试时捕捉到这一点。

验证器将完成的答案连同它所依据的文件和工具结果一起发送给 Jev。Jev 为答案的质量打分，并说明其主张是否有根据，即由智能体实际阅读的内容支持。

两条规则防止智能体无限重试。总共最多尝试两次。当 Jev 对自己的评分不自信时，工具链接受该答案，而不是支付另一次尝试的费用。

安全与日志

Jev 提供一个概率值，而概率可能出错。因此，任何普通代码能确切检查的事情都应在代码中检查。在这个工具链中，每个文件工具都拒绝项目文件夹之外的任何路径，无论 Jev 怎么说。将 Jev 留给代码无法做出的判断性决策。

门控只查看工具调用本身，即工具的名称及其输入。这有助于对抗提示注入，即隐藏在文件或网页中的文本诱骗模型执行有害操作。门控从未看到诱饵，但它仍然看到它导致的有害调用。

记录每个决策及其背后的数字。日志解释了某事被阻止的原因，并显示了用于设置阈值的实际数字。工具链将每个决策写入名为 decisions.jsonl 的文件一行。门控看到智能体尝试做的一切，因此日志会隐藏电子邮件地址和密钥，并缩短长输入。

试用

下面的沙盒运行本教程中完成的工具链，连接到真实的 Jev。它处理步道调查笔记文件夹，其 delete_path 工具确实可以删除它们。

试用地址：https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness

为什么要构建自己的工具链

现成的智能体使用自己的内置规则来做出这些决策。自定义工具链将这些决策放在你的代码中。你选择模型，设置阈值，决定何时需要人员介入，并从日志中准确读取每个调用被做出的原因。

Jev 是使其变得实用的关键。每次决策耗时几百毫秒，成本仅为一小部分美分，因此你可以在工作需要的任何地方添加检查，而不仅仅是在你能负担得起一次完整模型调用的地方。本教程中的三个部分是一个起点。为你领域定制的自定义工具链可以向 Jev 提出在那里重要的任何问题。

其他用途

这三个部分同样适用于编码智能体之外。

• 代码审查机器人。 为每个建议的更改评分，只向人展示值得阅读的那些。
• 记录清理。 在合并两条记录之前，询问它们是否描述了同一件事，并将不确定的配对留给人员处理。
• 文档管道。 为每个提取的页面评分，并仅重新运行低分页面。
• 审批队列。 只有处于“询问人员”范围内的调用才会到达人工审查员。

在每种情况下，语言模型执行开放式工作，Jev 回答其周围的小问题。

本教程中的问题、阈值和策略是用于学习的示例，而非经过调优的生产设置。我们正在基准测试这些工具链更改对成本和答案质量的影响，包含这些结果的后续指南即将推出。

我花了整个晚上与 Opus 5.5 一起整理本指南和沙盒。如果你遇到任何问题，请给我发私信。欢迎复制这篇文章并将其提供给你的智能体，以继续实验这些想法。