没有编码智能体的模型访问
一个应用从模型那里需要的大多数东西是一次调用,而不是一个智能体:本章直接使用 pi-ai,从一次模型调用拿到一个类型化的结果,没有循环、没有会话、没有终端。
到目前为止,一切都运行在一个编码智能体内部。你一直在使用的是一个会读文件、会跑命令、会保持会话的工具,而你一直在往它上面挂接。那是一个正确的起点,因为 Pi 的宿主就是大多数人遇见 Pi 的地方。
它是一个错误的终点,因为一个应用从模型那里需要的大多数东西并不是一个智能体。它是一个问题和一份答案:这个论断有这份证据支持吗? 一个输入,一个类型化的结果,没有什么要运行,也没有什么要记住。
为此,最便宜的正确工具是一次单模型调用。本章展示如何用 Pi 已发布的最低层做出一次调用,不需要循环、会话、工具集或终端。它也是第五部分那个贯穿始终的示例开始的地方。
各层,按正确的方向画出来
第 1 章画过整个栈。这里是界面之下的五级,并把依赖方向直说出来,因为它对接下来的一切都重要:一个智能体位于模型层之上、赋予它目的的那个应用之下。
application / host 智能体的用途所在;权限所在之处
│ uses
agent application 会话、压缩策略、扩展、工作流
│ uses
agent core 循环、消息、状态、工具执行、事件
│ uses
model / provider access 对某一个模型发出一次请求,再流式返回
│ uses
provider Anthropic、OpenAI、一个本地服务器
在 Pi 的包里,中间那几层有名字:
pi-coding-agent 智能体应用 (终端、JSON、RPC、SDK)
pi-agent-core 智能体内核 (这仍然是 Pi,只是没有了编码智能体)
pi-ai 模型访问 (没有循环、没有要运行的工具、没有会话)
前面两句话现在有了具体的含义。第 1 章说智能体内核"在一个没有终端、没有应用、也没有特定于某个 provider 的模型的情况下运行。“第 11 章说要使用能够解决问题的最弱机制。本章就是把那条规则应用到代码上:一次模型调用位于一个智能体之下,所以先伸手去拿它。
接下来要构建的东西的形状
第五部分分六步构建,而这个顺序本身就是论证,不是图方便。
flowchart TD
A["36 一次请求,一个类型化的值<br/>pi-ai"] --> B["37 单独运行的循环<br/>pi-agent-core"]
B --> C["38 作为类型化函数的随机一步"]
C --> D["39 每一个钩子,以及每一个还能改变什么"]
D --> E["40 在不把一切都变成智能体的前提下组合操作"]
E --> F["41 测试包含模型的软件"]
一次调用给出的类型化值,是一个模型能给你的最窄的东西,而它已经值得拥有:第 36 至 38 章讲的是在循环介入之前你能得到多少结构。第 39 章接着把智能体打开,追问每一个钩子还能改变哪些决策——而第 40 章随后针对这个问题做组合。第 41 章收尾,追问这一切要如何被测量,包括本书还没有做过的那个测量。
pi-ai 给了你什么
pi-ai 的 README 开篇把它称为一个统一的 LLM API,带有 provider 集合、自动认证解析,以及 token 与成本跟踪。有四个观念承载了其余的一切。
一个 Models 集合持有 provider 以及它们提供的模型。你在它里面查找一个模型,并通过它发出请求。在本章使用的这个 API 里,没有需要先配置的全局注册表。(该包仍然为旧代码附带了一个全局的 compat 入口;本章讲的是集合形式。)
一个 Context 就是普通数据。 一个系统提示词、一个消息列表,以及一份工具声明列表。README 把它描述为易于序列化、可在模型之间传递。在这里声明一个工具,意味着告诉模型它存在。pi-ai 里没有任何东西会运行它。
complete() 与 stream() 把一个 context 发给模型,并给你返回一个 AssistantMessage,要么是完整的,要么以事件形式。简单变体 completeSimple() 和 streamSimple() 增加了一个统一的 reasoning 选项。
失败是一个值。 README 明确说,一个在流返回之后失败的请求从不抛出异常。最终的消息带有 stopReason: "error" 或 "aborted",以及一个 errorMessage。你要自己去检查,因为没有任何东西强迫你。
1.0.4 声明中的 StopReason 有七个值:pending(流式输出期间的一条部分消息)、stop、length、toolUse、error、aborted 和 deferred。一次单独的 complete() 通常会返回的五个是 stop、length、toolUse、error 和 aborted。deferred 是成功与失败之外的第六样东西:答案还不在这里,而 Models.streamDeferred 和 DeferredHandle 是你稍后收集它的方式。本章不使用它。一次返回 toolUse 的模型调用还没有结束。它在向你要某样东西,而本章里你会故意利用这一点。
什么时候你要的是模型调用而不是智能体
就这项任务问三个问题。
模型可能需要做的事,其集合是否事先已知? 是 -> 一次调用
轮次的数量是否已知(这里:一轮)? 是 -> 一次调用
模型决定的任何事情,是否会对答案之外产生影响? 否 -> 一次调用
如果三条都成立,那么一个智能体会给你增加一个你不需要的循环、一条你不使用的工具执行流水线,以及一份你会扔掉的转录记录。判断一个论断是否被你已有的证据支持,这三条全都通过。
只要有任意一条不成立,你要的就是下一章。
一个问题,一个类型化的答案
这就是全部。结果类型才是这个文件的重点,所以它排在最前面,而其他一切都是为了让模型恰好产出那个东西:
import {
Type,
validateToolCall,
type Context,
type Model,
type Models,
type Static,
type Tool,
} from "@earendil-works/pi-ai";
// The result we want from the model. Everything downstream depends on this
// shape, not on the model's prose.
export const EvidenceAssessment = Type.Object({
verdict: Type.Union([Type.Literal("supported"), Type.Literal("contradicted"), Type.Literal("insufficient")]),
confidence: Type.Number({ minimum: 0, maximum: 1 }),
citations: Type.Array(Type.String(), { description: "Evidence items relied on, quoted exactly." }),
reason: Type.String({ description: "One or two sentences." }),
});
export type EvidenceAssessment = Static<typeof EvidenceAssessment>;
const submit: Tool = {
name: "submit_assessment",
description: "Submit your assessment of the claim. Call this exactly once.",
parameters: EvidenceAssessment,
};
// One model call, no loop, no session. Input in, typed value out.
export async function assess(
models: Models,
model: Model<any>,
claim: string,
evidence: string[],
): Promise<EvidenceAssessment> {
const context: Context = {
systemPrompt: "Decide whether the evidence supports the claim. Use only the evidence given.",
messages: [
{
role: "user",
content: `Claim: ${claim}\n\nEvidence:\n${evidence.map((e, i) => `${i + 1}. ${e}`).join("\n")}`,
timestamp: Date.now(),
},
],
tools: [submit],
};
const reply = await models.complete(model, context);
if (reply.stopReason === "error" || reply.stopReason === "aborted") {
throw new Error(`model call failed: ${reply.errorMessage ?? reply.stopReason}`);
}
// toolChoice is only "auto" | "none", so the model is asked to call the tool,
// not forced to. Check that it did.
const call = reply.content.find((block) => block.type === "toolCall");
if (!call) throw new Error("the model answered in prose instead of calling submit_assessment");
// Throws if the arguments do not match the schema.
return validateToolCall([submit], call) as EvidenceAssessment;
}
这个模式是 pi-ai 在不使用特定于某个 provider 的特性时,让你拿到结构化输出的唯一方式:**声明一个工具、要求模型调用它、然后验证那些参数。**那个"工具"从不被运行。它是一个由模型填写的 schema。validateToolCall() 依据它检查那些参数,不匹配时就抛出。
模型是被请求,不是被强迫
看看这次调用之后的那个检查:
const call = reply.content.find((block) => block.type === "toolCall");
if (!call) throw new Error("the model answered in prose instead of calling submit_assessment");
那个检查之所以存在,是因为 pi-ai 里的 toolChoice 只接受 "auto" 和 "none"。没有 "required"。你无法强迫一个模型调用工具。你可以请求,然后你必须处理它没有调用的情况。有三件事可能出错,而示例对这三件的处理各不相同:
| 发生了什么 | 它如何显现 | assess() 做什么 |
|---|---|---|
| 请求失败了 | stopReason 是 "error" 或 "aborted" |
抛出,并带上 provider 的消息 |
| 模型用散文回答 | content 里没有 toolCall 块 |
抛出,并点出问题 |
| 参数破坏了 schema | validateToolCall() 抛出 |
让它抛出 |
三者都变成你函数边界上的一个异常。越过那条线,你的程序其余部分持有的就是一个 EvidenceAssessment,没有别的。模型的可变性被遏制在一个函数里,而正是整个第五部分被构建出来要交给你的那个性质。
受约束采样是相关的,但它是另一个特性。一个工具可以设置 constrainedSampling: { type: "json_schema", strict: "prefer" },一个有能力的 provider 会在生成时强制执行该 schema。README 列出了哪些 provider 支持它,并说 strict: "prefer" 在模型无法遵守它时会回退到普通的工具调用。你有它就用它。但不要因此删掉验证:它是一个请求,而请求是可以被拒绝的。
不用密钥运行它
本章的测试运行在 pi-ai 的 faux provider 上,它会重放脚本化的响应。它是已发布包的一部分,README 把它描述为一种构建"用于测试和演示的脚本化响应"的方式:
function setup() {
const faux = fauxProvider();
const models = createModels();
models.setProvider(faux.provider);
return { faux, models, model: faux.getModel() };
}
test("arguments that break the schema are rejected, not passed on", async () => {
const { faux, models, model } = setup();
faux.setResponses([
fauxAssistantMessage(
[fauxToolCall("submit_assessment", { verdict: "maybe", confidence: 7, citations: [], reason: "" })],
{ stopReason: "toolUse" },
),
]);
await assert.rejects(assess(models, model, "claim", []), /./);
});
一个 "maybe" 的裁定和一个 7 的置信度都在 schema 之外,而 assess() 拒绝了它们。这是针对 pi-ai 1.0.4 运行的,在本书旁边那个锁定的 examples 项目里。见下面的"自己验证”。
把它指向一个真实模型
assess() 里没有任何东西知道是哪个 provider 在回答。把 faux provider 换成一个真实的,只会改变你如何构建 models,别的什么都不变:
import { builtinModels } from "@earendil-works/pi-ai/providers/all";
const models = builtinModels();
const model = models.getModel("anthropic", "claude-sonnet-5")!;
const result = await assess(models, model, claim, evidence);
这个代码块是有文档记载且未运行的,本书的示例没有运行它,因为它需要一个凭据。builtinModels() 和 getModel() 展示在 pi-ai README 的快速上手里,而认证通过 provider 解析,默认来自环境变量。请对着你账户的 models.getModels() 核对该模型标识符,而不要相信这一个。
有两个细节值得带上。一条回复带有 usage,包括按该模型目录价计算的 cost 明细,所以像 assess() 这样的函数能告诉它的调用者它花了多少。而 usage.reasoning 已经在 usage.output 里面了,所以不要把两者相加。
更便宜的一级:分类
在你去拿 complete() 之前,还有一个更弱的机制。pi-ai 有一个单独的分类 API。一个分类器模型不聊天。它回答关于 JSON 状态的带类型问题:在几个选项中选一个、回答是或否,或者给一个分数,每一项都带概率。
const model = models.getModelOfType("classifier", "typesafe", "jev-latest")!;
const result = await models.classify(model, {
state: { message: "The change works perfectly, thanks." },
questions: {
approved: {
type: "bool",
instructions: "Does the user approve?",
criteria: { true: "Approval", false: "No approval" },
},
},
});
console.log(result.answers);
同样有文档记载且未运行:它需要一个分类器 provider 和一个密钥。它在这里是为了那个决策的形状。一个分类器有固定的输出空间,所以它不能用散文回答、编造一个字段,或者调用工具。它是 Pi 所拥有的最弱的模型机制,而对于一个封闭的问题(这是正面的吗,这四条路线是哪一条),第 11 章规则选的就是它。classify() 的 promise 也从不 reject:就像一次聊天请求,失败会以 stopReason: "error" 的形式回来。
要带走的排序与本书其余部分不断画出的那一条相同:
classify 封闭的答案,固定的输出空间
complete + tool 开放的答案,由 schema 塑形,由你验证
Agent 开放的任务,未知数量的轮次,在世界中产生效果
每一步代价更高、能做的也更多。拿第一个能解决问题的。
那个贯穿始终的示例
第五部分构建一个小应用,并且不更换它的主题:
给定一个技术论断和一些证据,判断该论断是否被支持。
它是刻意中立的。它小到能装进你的脑子,它有清晰的类型化结果,它还具有让智能体工作变得困难的所有那些性质:模型可能出错、可能编造一条引用、可能拒绝以你要求的形状回答,也可能周二对、周四错。在本章里它是一次调用。接下来五章把它变成一个智能体、强制它的输出、守护它的工具、把它与其他步骤组合,并测量它有多可靠。
你能断言什么、不能断言什么
有文档记载:Models 集合、complete()、stream()、completeSimple()、stopReason、validateToolCall()、faux provider、受约束采样、classify(),以及 toolChoice 是 "auto" | "none" 这一点(pi-ai README 与 types.d.ts,1.0.4)。
已观察:examples/ch36-model-access/ 下的三个测试在 pi-ai 1.0.4 上通过。它们展示的是脚本化响应下的行为。它们不展示一个真实模型多久调用一次该工具,那是另一个问题,是第 41 章的主题。
*本书提出:*用一个只含 schema 的工具作为从一次直接调用拿到结构化输出的方式,以及 classify、complete 和 Agent 的三级梯子。它们由有文档记载的 API 推得,是本书的推荐,而不是 Pi 做出的契约。
自己验证
cd examples
npm install
npm run verify-examples
examples/package.json 把 @earendil-works/pi-ai、pi-agent-core 和 pi-coding-agent 精确锁定到 1.0.4。这正是这个文件夹的意义:这一部分的代码就是运行过的代码,针对的是本书所声明的那个发布版本,而不是碰巧全局安装着的任何东西。
下一章
现在你能从一次调用拿到一个类型化的答案了。一次单独的调用做不到的,是决定自己需要更多信息然后去拿到它。为此,模型必须能够要某样东西、收到它、然后再要一次,而这就是一个循环。
第 37 章把同一个任务放进 pi-agent-core 的 Agent 里:第 1 章的那个循环,带着一个工具真实运行,而仍然看不到编码智能体。