← Pi Agents

没有编码智能体的模型访问

一个应用从模型那里需要的大多数东西是一次调用,而不是一个智能体:本章直接使用 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 章的那个循环,带着一个工具真实运行,而仍然看不到编码智能体。