1. 项目概述当极简主义遇上 Agent 基础设施最近在折腾 AI Agent 项目发现一个挺有意思的现象很多框架为了追求“大而全”恨不得把 RAG、工作流、多模态、复杂编排全塞进去结果上手门槛高得吓人代码也臃肿不堪。这让我想起一个老生常谈的哲学Less is More。恰好我在 GitHub 上看到了一个名为Pi的项目它的副标题直接点明了核心——“一个极简主义的 agent harness”。最吸引我的是它宣称自己只提供了4 个 tool。在如今动辄几十上百个内置工具的 Agent 框架生态里这个数字简直是一股清流。这个“Pi”项目和我们熟知的 Raspberry Pi树莓派或者数学常数 π 没有直接关系。它是一个用 TypeScript 编写的、采用 monorepo 架构的 AI Agent 基础设施层Harness。它的设计理念非常明确不做 Agent 的大脑只做 Agent 的骨架和关节。你可以把它理解为一套高度抽象、极度克制的 SDK 或中间件专门用来包裹和赋能你自定义的 Agent 核心推理逻辑比如基于 OpenAI GPT、Claude 或本地大模型的推理循环。那么一个只有 4 个工具的 Harness能干什么它解决了什么问题简单说它试图解决 Agent 开发中的“胶水代码”困境。当你让大模型调用工具Tool Calling时你需要处理大量繁琐但必要的基础工作工具的定义与注册、调用的解析与验证、执行时的上下文管理、流式输出的处理、错误的重试与回退、状态的持久化等等。Pi 把这些脏活累活打包成一个轻量、专注的层让你能专注于设计 Agent 的“思考”策略和业务工具本身。这种极简主义恰恰是为了给复杂留出空间。2. 核心架构与设计哲学拆解2.1 Harness 与 Agent 的职责边界在深入 Pi 的四个工具之前必须厘清一个关键概念Harness基础设施层和Agent代理核心的区别。这是理解 Pi 设计哲学的基础。网络上有很多讨论比如“llm、agent、rag、harness是按什么层级架构构成一个ai的”。我们可以这样类比LLM大语言模型是“肌肉”和“知识库”提供基础的认知和生成能力。Agent是“大脑”和“决策中枢”它基于目标、上下文和可用工具进行规划、推理和决策。RAG是“外部记忆”或“参考资料库”为大脑提供实时、精准的信息补充。Harness则是“神经系统”和“运动系统”。它不负责思考“为什么要去拿水杯”这是Agent的职责但它负责把“拿水杯”这个指令分解为“移动手臂肌肉群、控制手指抓握”等一系列可执行、可监控、可恢复的底层操作。Pi 就是一个典型的 Harness。它不包含任何预设的 Agent 推理策略如 ReAct、Plan-and-Execute 等也不提供向量数据库或检索器RAG。它的工作仅仅是当你定义好工具并给出一个任务时它确保这些工具能够被可靠、可控、可观测地调用和执行。这种关注点分离Separation of Concerns的设计使得 Pi 能够保持极致的轻量和灵活。2.2 Monorepo 与 TypeScript 的技术选型Pi 项目采用monorepo架构并使用TypeScript开发这两个选择与其极简主义理念一脉相承。为什么是 TypeScript对于基础设施类库稳定性和开发者体验至关重要。TypeScript 提供的静态类型检查能在编译阶段就捕获大量潜在的错误比如工具函数入参类型不匹配、返回数据结构错误等。这对于构建需要与多种 LLM API 和复杂业务逻辑交互的 Harness 来说是巨大的安全保障。同时现代 AI 开发栈如 LangChain.js、Vercel AI SDK也广泛使用 TypeScript生态兼容性好。为什么是 Monorepo查看 Pi 的源码结构它通常会将核心包pi/core、适配不同 LLM 供应商的包如pi/adapter-openai、示例应用examples/等放在同一个仓库中管理。这样做的好处代码共享与版本同步所有包共享同一套工具链eslint, prettier, jest和类型定义修改核心 API 时能立刻在所有适配器和示例中检测到破坏性变更。简化依赖管理内部包之间通过workspace:*引用避免了发布到 npm 再安装的繁琐流程便于一体化开发和测试。体现架构清晰度monorepo 的目录结构本身就是一个清晰的架构文档开发者一眼就能看出核心、适配器、应用之间的层次关系。这种技术选型为目标用户——那些需要构建稳定、可维护的 AI 应用的中高级开发者——提供了坚实的工程基础。2.3 “4个Tool”的极简主义体现这是 Pi 最引人注目的特点。在大多数框架疯狂增加内置工具从计算器、天气查询到数据库操作的背景下Pi 反其道而行之只提供最最基础、原子性的 4 个工具。这并非功能薄弱而是高度的抽象。这4个工具构成了 Harness 控制工具执行生命周期的最小完备集。它们可能类似于具体名称可能不同但功能范畴一致工具注册/查询工具用于 Agent 动态发现当前可用的工具列表及其模式Schema。工具执行工具接收工具调用请求Tool Call执行对应的函数并返回结果。状态管理/上下文工具用于读写当前会话或任务链的上下文状态实现工具间的信息传递。流程控制工具例如“终止任务”、“跳转到某一步”等允许 Agent 或外部系统对执行流进行干预。通过仅提供这4个Pi 将“工具能做什么”的决定权完全交给了开发者。你需要一个网络搜索工具自己去实现searchWeb函数然后用 Pi 提供的机制把它“挂载”上去。Pi 只关心这个函数如何被规范地调用、执行和监控。这种设计极大地减少了框架本身的概念负担和学习成本开发者只需要理解这4个核心原语就能掌控整个工具调用流程。3. 核心工具深度解析与实现原理下面我们来逐一拆解这4个核心工具可能的设计与实现。虽然无法看到 Pi 的确切源码但基于其“极简 Harness”的定位我们可以推断出每个工具的必要性、接口设计和内部逻辑。3.1 Tool Registry工具的注册与发现中心这是整个系统的起点。Agent 需要知道“我手头有什么工具可以用”。Pi 的 Tool Registry 工具就是提供这个清单的。核心职责注册工具接收开发者定义的工具函数及其 JSON Schema 描述。维护清单在内存或持久化存储中保存所有可用工具的描述。提供清单响应 Agent或LLM的查询返回一个符合 OpenAI Tool Calling 或类似规范的工具描述列表。实现要点与注意事项// 伪代码示例工具定义接口 interface PiTool { name: string; // 唯一工具名如 “get_weather” description: string; // 给LLM看的自然语言描述 schema: z.ZodSchema; // 使用 Zod 等库定义严格的输入参数模式 handler: (args: any, context: ToolContext) Promiseany; // 工具执行函数 } // 注册过程 harness.registerTool({ name: “calculate”, description: “执行数学计算”, schema: z.object({ expression: z.string().describe(“数学表达式如 ‘(5 3) * 2’”) }), handler: async ({ expression }, ctx) { // 安全警告直接 eval 极其危险此处仅为示例。 // 真实场景应使用沙箱或数学表达式解析库如 math.js。 try { const result eval(expression); return { result: 表达式“${expression}”的计算结果是${result} }; } catch (error) { return { error: 计算失败: ${error.message} }; } } });注意工具执行函数handler的安全性是重中之重。如上例中的eval在生产环境中是绝对禁止的。必须对输入进行严格的净化和校验或使用受限的沙箱环境来执行不可信代码。实操心得Schema 即契约工具的模式定义Schema要尽可能精确和详细。好的description和参数describe能极大提升 LLM 调用工具的准确率。命名规范化工具名最好使用snake_case并保持动词名词的语义清晰如search_web,update_database_record这符合大多数 LLM 的训练数据格式。上下文注入handler函数应能接收到一个ToolContext对象其中包含当前会话 ID、用户信息、之前的对话历史等这对于实现有状态的工具交互至关重要。3.2 Tool Executor工具调用的执行引擎当 LLM 返回一个形如{“tool_calls”: [{“id”: “call_123”, “type”: “function”, “function”: {“name”: “get_weather”, “arguments”: “{\”city\“: \”北京\“}”}}]}的响应时Tool Executor 就该上场了。核心职责解析与验证解析 LLM 返回的 Tool Call 对象验证工具名是否存在参数是否符合 Schema。执行与超时控制调用对应的handler函数并设置合理的超时时间防止某个工具调用卡死整个 Agent。结果格式化将handler返回的结果封装成标准的 Tool Call Result 格式以便返回给 LLM 进行下一轮推理。错误处理捕获执行过程中的异常网络错误、逻辑错误、权限错误等并将其转化为 LLM 能理解的错误信息格式。实现要点class ToolExecutor { private toolRegistry: ToolRegistry; async executeToolCall(toolCall: ParsedToolCall): PromiseToolResult { const tool this.toolRegistry.get(toolCall.name); if (!tool) { return { tool_call_id: toolCall.id, error: 未知工具: ${toolCall.name} }; } // 1. 参数验证 const parseResult tool.schema.safeParse(toolCall.arguments); if (!parseResult.success) { return { tool_call_id: toolCall.id, error: 参数验证失败: ${parseResult.error.message} }; } // 2. 创建执行上下文 const context this.createToolContext(toolCall); // 3. 执行带超时 try { const result await Promise.race([ tool.handler(parseResult.data, context), new Promise((_, reject) setTimeout(() reject(new Error(“工具执行超时”)), 30000) ) ]); return { tool_call_id: toolCall.id, output: result }; } catch (error) { // 4. 错误处理与转换 const errorMessage error instanceof Error ? error.message : ‘未知错误’; return { tool_call_id: toolCall.id, error: 执行失败: ${errorMessage} }; } } }常见问题与排查LLM 不调用工具首先检查registerTool时提供的description是否清晰LLM 是根据描述来决定是否以及如何调用工具的。其次检查返回给 LLM 的工具列表格式是否与其 API 要求一致如 OpenAI 的tools字段。参数总是解析失败这通常是 Schema 定义与 LLM 实际生成内容不匹配。LLM 可能生成{“city”: “Beijing”}但你的 Schema 期望的是{“location”: “Beijing”}。需要调整 Schema 或通过更清晰的描述和示例来引导 LLM。工具执行慢为每个handler设置独立的超时时间并考虑引入并发执行。如果多个 Tool Call 之间没有依赖关系Pi 这样的 Harness 应该支持并行执行以提高效率。3.3 Context Manager状态管理与信息传递桥梁Agent 在完成复杂任务时需要记住之前步骤的结果。例如先调用search_web找到了某公司的电话然后需要调用make_phone_call。电话号码就需要在两个工具间传递。这就是 Context Manager 的职责。核心职责会话状态存储为每个对话或任务链提供一个键值存储空间。工具间共享数据允许一个工具将输出写入上下文供后续工具读取。上下文注入自动将相关的上下文信息作为提示词的一部分提供给 LLM帮助其做出更准确的决策。设计模式 Pi 的 Context Manager 可能提供类似以下接口的工具set_context(key: string, value: any): 设置上下文值。get_context(key: string): any: 获取上下文值。append_to_context(key: string, value: any): 向一个数组类型的上下文追加内容常用于保存历史消息。实操技巧结构化上下文不要胡乱存储。可以设计固定的上下文结构如{ “user_preferences”: {}, “conversation_history”: [], “task_results”: {} }便于管理。避免上下文膨胀LLM 的上下文窗口是有限的。需要设计策略来摘要Summarize或淘汰Evict旧的、不重要的上下文信息。Pi 可能提供一个工具或钩子hook来让你实现自定义的上下文窗口管理逻辑。安全性上下文可能包含用户敏感信息。确保在持久化或传输时进行加密并遵守数据隐私规范。3.4 Flow Controller执行流程的调控器这是赋予 Harness 灵活性和可控性的关键。一个简单的 Agent 可能是线性的思考 - 调用工具 - 再思考。但复杂场景需要暂停、重试、跳转、人工审核介入。Flow Controller 就提供了这些基础原语。可能提供的工具或能力暂停/继续pause_task(taskId),resume_task(taskId)。允许外部系统如人工坐席中断自动流程进行检查或干预。重试retry_tool_call(toolCallId)。当某个工具调用因临时网络问题失败时可以触发重试而不是直接让整个任务失败。终止terminate_task(taskId, reason)。在满足某些条件如用户取消、策略违规时安全地终止整个 Agent 执行。跳转goto_step(stepLabel)。在某些工作流引擎中允许根据条件跳转到不同的步骤。实现考量 Flow Controller 的实现通常与 Harness 的核心事件循环Event Loop或状态机紧密耦合。它需要维护每个任务Task或会话Session的状态运行中、已暂停、已终止、已完成并暴露 API 供外部调用或供其他工具内部触发。应用场景人工在环Human-in-the-loop当 Agent 需要确认一个高风险操作如发送邮件、支付时可以调用pause_task并通知人工审核。审核通过后再调用resume_task。条件性重试在Tool Executor捕获到可重试错误如 5xx 服务器错误时可以自动或通过策略调用重试逻辑。超时保护如果一个任务运行时间过长一个监控进程可以调用terminate_task来防止资源耗尽。4. 从零开始基于 Pi 理念构建一个简易 Harness理解了四大核心组件的原理后我们可以尝试抛开 Pi 的具体实现用 TypeScript 模拟其理念构建一个自己的极简 Harness。这将帮助我们更深刻地体会其设计精妙之处。4.1 项目初始化与核心类型定义首先我们创建一个 monorepo 风格的 TypeScript 项目。mkdir my-minimal-harness cd my-minimal-harness npm init -y npm install typescript ts-node types/node zod npx tsc --init创建核心类型定义文件src/types.tsimport { z } from “zod”; // 工具调用请求来自LLM export interface ToolCall { id: string; name: string; arguments: string; // JSON string } // 工具调用结果返回给LLM export interface ToolResult { tool_call_id: string; output?: any; error?: string; } // 工具定义 export interface ToolDefinitionTInput any, TOutput any { name: string; description: string; inputSchema: z.ZodSchemaTInput; execute: (args: TInput, context: ExecutionContext) PromiseTOutput; } // 工具执行上下文 export interface ExecutionContext { sessionId: string; getState: T(key: string) T | undefined; setState: (key: string, value: any) void; // 可以扩展用户信息、日志器等 } // Harness 核心状态 export interface HarnessState { tools: Mapstring, ToolDefinition; sessionStates: Mapstring, Mapstring, any; // sessionId - (key - value) }这个类型系统定义了数据流动的契约是保证整个系统类型安全的基础。4.2 实现核心工具类接下来我们实现三个核心类对应前文分析的 Registry、Executor 和 Context Manager。Flow Controller 的概念我们暂时融入到 Executor 和主循环中。1. ToolRegistry (工具注册中心) -src/ToolRegistry.tsimport { ToolDefinition, HarnessState } from “./types”; export class ToolRegistry { private state: HarnessState; constructor(state: HarnessState) { this.state state; } register(tool: ToolDefinition): void { if (this.state.tools.has(tool.name)) { throw new Error(工具 ‘${tool.name}’ 已存在); } this.state.tools.set(tool.name, tool); console.log([ToolRegistry] 工具 ‘${tool.name}’ 注册成功); } getTool(name: string): ToolDefinition | undefined { return this.state.tools.get(name); } // 生成供LLM使用的工具描述列表 getToolDescriptors(): Array{name: string; description: string; parameters: any} { return Array.from(this.state.tools.values()).map(tool ({ name: tool.name, description: tool.description, parameters: tool.inputSchema._def // 简化处理实际需转换为JSON Schema })); } }2. ContextManager (上下文管理器) -src/ContextManager.tsimport { ExecutionContext, HarnessState } from “./types”; export class ContextManager { private state: HarnessState; constructor(state: HarnessState) { this.state state; } createExecutionContext(sessionId: string): ExecutionContext { // 确保该会话的状态Map存在 if (!this.state.sessionStates.has(sessionId)) { this.state.sessionStates.set(sessionId, new Map()); } const sessionState this.state.sessionStates.get(sessionId)!; return { sessionId, getState: T(key: string): T | undefined { return sessionState.get(key) as T; }, setState: (key: string, value: any): void { sessionState.set(key, value); } }; } // 可选提供全局上下文清理等方法 cleanupSession(sessionId: string): void { this.state.sessionStates.delete(sessionId); } }3. ToolExecutor (工具执行器) -src/ToolExecutor.tsimport { ToolCall, ToolResult, ToolDefinition, ExecutionContext } from “./types”; import { ToolRegistry } from “./ToolRegistry”; import { ContextManager } from “./ContextManager”; export class ToolExecutor { constructor( private toolRegistry: ToolRegistry, private contextManager: ContextManager ) {} async execute(toolCall: ToolCall, sessionId: string): PromiseToolResult { const tool this.toolRegistry.getTool(toolCall.name); if (!tool) { return { tool_call_id: toolCall.id, error: 工具 ‘${toolCall.name}’ 未找到 }; } // 1. 解析参数 let parsedArgs: any; try { parsedArgs JSON.parse(toolCall.arguments); } catch { return { tool_call_id: toolCall.id, error: “参数不是有效的JSON格式” }; } // 2. 验证参数 const validation tool.inputSchema.safeParse(parsedArgs); if (!validation.success) { return { tool_call_id: toolCall.id, error: 参数验证失败: ${validation.error.message} }; } // 3. 创建执行上下文 const context this.contextManager.createExecutionContext(sessionId); // 4. 执行工具 try { const output await tool.execute(validation.data, context); return { tool_call_id: toolCall.id, output }; } catch (error) { const errorMsg error instanceof Error ? error.message : String(error); return { tool_call_id: toolCall.id, error: 工具执行异常: ${errorMsg} }; } } // 批量执行并行 async executeAll(toolCalls: ToolCall[], sessionId: string): PromiseToolResult[] { const promises toolCalls.map(call this.execute(call, sessionId)); return Promise.all(promises); } }4.3 组装 Harness 与主事件循环最后我们将这些组件组装起来并模拟一个简单的 Agent 运行循环。src/Harness.tsimport { HarnessState } from “./types”; import { ToolRegistry } from “./ToolRegistry”; import { ContextManager } from “./ContextManager”; import { ToolExecutor } from “./ToolExecutor”; // 模拟一个极简的LLM客户端实际应替换为 OpenAI、Anthropic 等 SDK class MockLLMClient { async chat(messages: any[], tools: any[]): Promise{tool_calls?: ToolCall[]} { // 这里是模拟逻辑如果用户消息提到“计算”就调用计算器工具 const lastMessage messages[messages.length - 1]?.content || “”; if (lastMessage.includes(“计算”)) { return { tool_calls: [{ id: “call_” Date.now(), name: “calculate”, arguments: JSON.stringify({ expression: “(10 20) * 2” }) // 模拟LLM生成的参数 }] }; } // 否则正常回复 return { content: “我是一个模拟的LLM你说了: “ lastMessage }; } } export class MinimalHarness { private state: HarnessState { tools: new Map(), sessionStates: new Map() }; private toolRegistry: ToolRegistry; private contextManager: ContextManager; private toolExecutor: ToolExecutor; private llmClient: MockLLMClient; constructor() { this.toolRegistry new ToolRegistry(this.state); this.contextManager new ContextManager(this.state); this.toolExecutor new ToolExecutor(this.toolRegistry, this.contextManager); this.llmClient new MockLLMClient(); } getToolRegistry(): ToolRegistry { return this.toolRegistry; } // 核心运行循环 async runSession(sessionId: string, initialInput: string): Promisevoid { const messages [{ role: “user”, content: initialInput }]; let maxTurns 5; // 防止无限循环 while (maxTurns-- 0) { // 1. 获取当前可用工具描述 const availableTools this.toolRegistry.getToolDescriptors(); // 2. 调用LLM传入对话历史和工具列表 const llmResponse await this.llmClient.chat(messages, availableTools); // 3. 处理LLM响应 if (llmResponse.content) { console.log([Agent]: ${llmResponse.content}); messages.push({ role: “assistant”, content: llmResponse.content }); // 如果没有工具调用对话可能结束或继续 break; // 简化处理假设一次工具调用后结束 } if (llmResponse.tool_calls llmResponse.tool_calls.length 0) { console.log([LLM 决定调用工具]:, llmResponse.tool_calls); // 4. 执行工具调用 const results await this.toolExecutor.executeAll(llmResponse.tool_calls, sessionId); // 5. 将工具执行结果作为消息追加供LLM下一轮推理 messages.push({ role: “assistant”, content: null, tool_calls: llmResponse.tool_calls }); results.forEach(result { messages.push({ role: “tool”, tool_call_id: result.tool_call_id, content: result.error ? 错误: ${result.error} : JSON.stringify(result.output) }); }); console.log([工具执行结果]:, results); } } } }4.4 编写示例工具并运行测试现在我们创建一个示例文件src/index.ts来使用这个自制的 Harnessimport { MinimalHarness } from “./Harness”; import { z } from “zod”; async function main() { const harness new MinimalHarness(); const registry harness.getToolRegistry(); // 注册一个计算器工具模拟 Pi 的 4个工具之一 registry.register({ name: “calculate”, description: “执行一个数学表达式并返回结果。确保表达式是安全的。”, inputSchema: z.object({ expression: z.string().min(1).describe(“数学表达式例如 ‘3 5 * 2’”) }), execute: async (args, context) { // 警告生产环境请使用 math.js 等安全库 // 这里仅为演示。 console.log([工具 calculate] 正在执行表达式: ${args.expression}, 会话: ${context.sessionId}); try { // 极其简化的安全示例只允许数字和基础运算符 if (!/^[\d\s\-*/().]$/.test(args.expression)) { throw new Error(“表达式包含不安全字符”); } const result Function(“use strict”; return (${args.expression}))(); context.setState(“last_calculation”, result); // 演示上下文存储 return { success: true, result }; } catch (error) { return { success: false, error: (error as Error).message }; } } }); // 注册一个获取上下文的工具模拟另一个核心工具 registry.register({ name: “get_context”, description: “获取当前会话中存储的指定键的值。”, inputSchema: z.object({ key: z.string().describe(“要获取的上下文键名”) }), execute: async (args, context) { const value context.getState(args.key); return { key: args.key, value }; } }); // 运行一个会话 console.log(“ 开始 Harness 演示会话 ”); await harness.runSession(“session_123”, “请帮我计算一下 (10 20) * 2 等于多少”); console.log(“ 演示结束 ”); } main().catch(console.error);运行npx ts-node src/index.ts你会看到类似以下的输出 开始 Harness 演示会话 [ToolRegistry] 工具 ‘calculate’ 注册成功 [ToolRegistry] 工具 ‘get_context’ 注册成功 [LLM 决定调用工具]: [ { id: ‘call_…’, name: ‘calculate’, arguments: ‘{“expression”:”(10 20) * 2”}’ } ] [工具 calculate] 正在执行表达式: (10 20) * 2, 会话: session_123 [工具执行结果]: [ { tool_call_id: ‘call_…’, output: { success: true, result: 60 } } ] 演示结束 通过这个从零构建的过程你可以清晰地看到一个极简 Harness 的核心骨架是如何搭建的。Pi 项目的价值在于它将这些核心组件设计得更健壮、更可扩展例如支持流式响应、更复杂的状态管理、插件化等并且提供了开箱即用的、与流行 LLM API 兼容的适配器。5. 进阶探讨在真实项目中应用与避坑指南当你理解了 Pi 这类极简 Harness 的核心理念后就可以在真实项目中应用它或者将其思想融入现有架构。这里分享一些进阶经验和常见陷阱。5.1 工具设计的最佳实践与反模式最佳实践单一职责每个工具只做一件事并且做好。send_email工具就只负责发邮件不要在里面又去查数据库验证用户。复杂的逻辑应该由 Agent 的多次工具调用来编排。无状态性尽可能让工具函数是无状态的Stateless。状态应该通过ExecutionContext来管理和传递。这有利于工具的重用和测试。充分的错误信息工具执行失败时返回的错误信息应该对 LLM 友好。例如不要只返回“Error 500”而应该返回“调用天气API失败可能服务暂时不可用请稍后再试。”这能帮助 LLM 进行下一步决策如重试或告知用户。输入验证与净化这是安全生命线。除了用 Zod Schema 做类型验证对于执行命令、访问文件、操作数据库的工具必须对输入进行严格的净化和权限检查。常见反模式工具过于庞大一个工具做十件事导致 Schema 复杂无比LLM 难以正确调用且难以维护。工具依赖隐藏状态工具内部依赖全局变量或外部可变状态导致在并发或分布式环境下行为不可预测。工具副作用不明确一个名为get_user_info的工具却在内部偷偷修改了用户数据。这会让 Agent 的推理逻辑混乱。5.2 与现有生态的集成策略你很少会从零开始。Pi 这样的 Harness 需要与现有生态集成。与 LLM SDK 集成你需要编写一个薄薄的适配层Adapter将 Harness 管理的工具列表转换成 OpenAI、Anthropic、Google Gemini 等 SDK 要求的格式并将 SDK 返回的 Tool Call 解析成 Harness 能处理的格式。Pi 的 monorepo 里通常就包含了pi/adapter-openai这样的包。与后端框架集成如果你的 Agent 是 Web 服务的一部分如 Express.js、Next.js、FastAPI需要将 Harness 实例封装成服务并提供相应的 HTTP 端点或 GraphQL Resolver 来处理对话请求。与状态存储集成上述示例中上下文状态存在内存里这不利于水平扩展和持久化。在生产中你需要将HarnessState中的sessionStates替换为 Redis、PostgreSQL 或任何你喜欢的数据库客户端。与监控和可观测性集成在每个工具执行的开始和结束、以及关键决策点埋点将日志、指标和追踪数据发送到像 OpenTelemetry、Datadog、Sentry 这样的平台。这对于调试复杂 Agent 行为至关重要。5.3 性能优化与扩展性考量当工具调用量大或工具本身是 IO 密集型如网络请求时需要考虑性能。并行执行如果 LLM 一次性返回多个独立的 Tool Call应该并行执行它们。我们的ToolExecutor.executeAll已经用了Promise.all。超时与熔断为每个工具设置独立的超时。对于频繁失败的外部服务工具可以考虑实现简单的熔断器Circuit Breaker模式暂时阻止对其的调用。异步流式输出对于执行时间较长的工具如生成报告可以支持流式返回部分结果Partial Output让 LLM 或前端能实时看到进度提升用户体验。这需要 Harness 和 LLM API 都支持流式响应。工具的热加载在不停机的情况下动态注册或注销工具。这可以通过在ToolRegistry中实现相关方法并配合一个文件监听器或配置中心来实现。5.4 调试与问题排查实战记录开发 Agent 应用大部分时间都在调试。以下是一些实战中遇到的问题和排查思路问题一LLM 总是忽略某个工具不调用它。排查首先检查该工具的description是否清晰、无歧义并且确实与用户问题相关。用一些测试问题直接问 LLM“为了回答这个问题你会使用哪些工具为什么” 观察其推理。其次检查返回给 LLM 的工具列表格式是否正确特别是parameters的 JSON Schema 是否符合 API 规范。解决重写工具描述使其更符合 LLM 的“思维习惯”。可以提供少量示例Few-shot在系统提示词中。如果问题依旧可能是该工具的功能本身就可以被 LLM 的内在能力所替代如简单计算这时需要考虑这个工具是否必要。问题二工具执行成功但返回的结果 LLM 无法理解或错误使用。排查检查工具返回的数据结构。是否过于复杂嵌套是否包含了 LLM 无法解析的二进制数据或特殊符号返回的文本是否清晰、完整解决简化输出结构优先返回纯文本或简单的 JSON 对象。在返回中增加一些自然语言描述。例如不要只返回{“temp”: 22, “unit”: “C”}而是返回“当前温度是 22 摄氏度。”或者至少是{“result”: “当前温度是 22 摄氏度。”, “data”: {“temp”: 22, “unit”: “C”}}。问题三在多轮对话中Agent “忘记”了之前工具调用的结果。排查检查对话历史messages是否被正确维护。确保每一轮的工具调用和工具输出都被正确地以role: “assistant”(带tool_calls) 和role: “tool”的形式追加到了消息列表中。同时检查ExecutionContext中的状态是否在工具间正确传递。解决实现一个健壮的会话管理器Session Manager确保对话历史的完整性和长度管理避免超出上下文窗口。对于关键信息除了放在上下文状态中也可以让工具将其以自然语言总结的形式追加到对话历史里确保 LLM 能“看到”。问题四在分布式部署下同一个会话的请求被路由到不同实例导致上下文丢失。排查这是典型的有状态服务扩展问题。内存中的sessionStates在实例间不共享。解决必须引入外部共享存储如 Redis。将ContextManager的底层存储替换为 Redis client。同时需要考虑会话状态的序列化/反序列化以及可能的并发写冲突问题可以使用乐观锁或分布式锁。Pi 这样的极简主义 Agent Harness其力量不在于它提供了多少功能而在于它清晰地定义了边界并提供了坚实、可组合的基础。它让你从繁琐的基础设施代码中解脱出来专注于让 Agent 变得更智能、更可靠。当你真正需要处理复杂编排、长期记忆、动态工具链时你可以基于这个稳固的底层按需引入更高级的组件而不是被一个庞大框架的既定范式所束缚。这或许就是“少即是多”在 AI 工程领域的最佳诠释。 极简AI Agent基础设施：Pi项目4个核心工具解析与TypeScript实现
1. 项目概述当极简主义遇上 Agent 基础设施最近在折腾 AI Agent 项目发现一个挺有意思的现象很多框架为了追求“大而全”恨不得把 RAG、工作流、多模态、复杂编排全塞进去结果上手门槛高得吓人代码也臃肿不堪。这让我想起一个老生常谈的哲学Less is More。恰好我在 GitHub 上看到了一个名为Pi的项目它的副标题直接点明了核心——“一个极简主义的 agent harness”。最吸引我的是它宣称自己只提供了4 个 tool。在如今动辄几十上百个内置工具的 Agent 框架生态里这个数字简直是一股清流。这个“Pi”项目和我们熟知的 Raspberry Pi树莓派或者数学常数 π 没有直接关系。它是一个用 TypeScript 编写的、采用 monorepo 架构的 AI Agent 基础设施层Harness。它的设计理念非常明确不做 Agent 的大脑只做 Agent 的骨架和关节。你可以把它理解为一套高度抽象、极度克制的 SDK 或中间件专门用来包裹和赋能你自定义的 Agent 核心推理逻辑比如基于 OpenAI GPT、Claude 或本地大模型的推理循环。那么一个只有 4 个工具的 Harness能干什么它解决了什么问题简单说它试图解决 Agent 开发中的“胶水代码”困境。当你让大模型调用工具Tool Calling时你需要处理大量繁琐但必要的基础工作工具的定义与注册、调用的解析与验证、执行时的上下文管理、流式输出的处理、错误的重试与回退、状态的持久化等等。Pi 把这些脏活累活打包成一个轻量、专注的层让你能专注于设计 Agent 的“思考”策略和业务工具本身。这种极简主义恰恰是为了给复杂留出空间。2. 核心架构与设计哲学拆解2.1 Harness 与 Agent 的职责边界在深入 Pi 的四个工具之前必须厘清一个关键概念Harness基础设施层和Agent代理核心的区别。这是理解 Pi 设计哲学的基础。网络上有很多讨论比如“llm、agent、rag、harness是按什么层级架构构成一个ai的”。我们可以这样类比LLM大语言模型是“肌肉”和“知识库”提供基础的认知和生成能力。Agent是“大脑”和“决策中枢”它基于目标、上下文和可用工具进行规划、推理和决策。RAG是“外部记忆”或“参考资料库”为大脑提供实时、精准的信息补充。Harness则是“神经系统”和“运动系统”。它不负责思考“为什么要去拿水杯”这是Agent的职责但它负责把“拿水杯”这个指令分解为“移动手臂肌肉群、控制手指抓握”等一系列可执行、可监控、可恢复的底层操作。Pi 就是一个典型的 Harness。它不包含任何预设的 Agent 推理策略如 ReAct、Plan-and-Execute 等也不提供向量数据库或检索器RAG。它的工作仅仅是当你定义好工具并给出一个任务时它确保这些工具能够被可靠、可控、可观测地调用和执行。这种关注点分离Separation of Concerns的设计使得 Pi 能够保持极致的轻量和灵活。2.2 Monorepo 与 TypeScript 的技术选型Pi 项目采用monorepo架构并使用TypeScript开发这两个选择与其极简主义理念一脉相承。为什么是 TypeScript对于基础设施类库稳定性和开发者体验至关重要。TypeScript 提供的静态类型检查能在编译阶段就捕获大量潜在的错误比如工具函数入参类型不匹配、返回数据结构错误等。这对于构建需要与多种 LLM API 和复杂业务逻辑交互的 Harness 来说是巨大的安全保障。同时现代 AI 开发栈如 LangChain.js、Vercel AI SDK也广泛使用 TypeScript生态兼容性好。为什么是 Monorepo查看 Pi 的源码结构它通常会将核心包pi/core、适配不同 LLM 供应商的包如pi/adapter-openai、示例应用examples/等放在同一个仓库中管理。这样做的好处代码共享与版本同步所有包共享同一套工具链eslint, prettier, jest和类型定义修改核心 API 时能立刻在所有适配器和示例中检测到破坏性变更。简化依赖管理内部包之间通过workspace:*引用避免了发布到 npm 再安装的繁琐流程便于一体化开发和测试。体现架构清晰度monorepo 的目录结构本身就是一个清晰的架构文档开发者一眼就能看出核心、适配器、应用之间的层次关系。这种技术选型为目标用户——那些需要构建稳定、可维护的 AI 应用的中高级开发者——提供了坚实的工程基础。2.3 “4个Tool”的极简主义体现这是 Pi 最引人注目的特点。在大多数框架疯狂增加内置工具从计算器、天气查询到数据库操作的背景下Pi 反其道而行之只提供最最基础、原子性的 4 个工具。这并非功能薄弱而是高度的抽象。这4个工具构成了 Harness 控制工具执行生命周期的最小完备集。它们可能类似于具体名称可能不同但功能范畴一致工具注册/查询工具用于 Agent 动态发现当前可用的工具列表及其模式Schema。工具执行工具接收工具调用请求Tool Call执行对应的函数并返回结果。状态管理/上下文工具用于读写当前会话或任务链的上下文状态实现工具间的信息传递。流程控制工具例如“终止任务”、“跳转到某一步”等允许 Agent 或外部系统对执行流进行干预。通过仅提供这4个Pi 将“工具能做什么”的决定权完全交给了开发者。你需要一个网络搜索工具自己去实现searchWeb函数然后用 Pi 提供的机制把它“挂载”上去。Pi 只关心这个函数如何被规范地调用、执行和监控。这种设计极大地减少了框架本身的概念负担和学习成本开发者只需要理解这4个核心原语就能掌控整个工具调用流程。3. 核心工具深度解析与实现原理下面我们来逐一拆解这4个核心工具可能的设计与实现。虽然无法看到 Pi 的确切源码但基于其“极简 Harness”的定位我们可以推断出每个工具的必要性、接口设计和内部逻辑。3.1 Tool Registry工具的注册与发现中心这是整个系统的起点。Agent 需要知道“我手头有什么工具可以用”。Pi 的 Tool Registry 工具就是提供这个清单的。核心职责注册工具接收开发者定义的工具函数及其 JSON Schema 描述。维护清单在内存或持久化存储中保存所有可用工具的描述。提供清单响应 Agent或LLM的查询返回一个符合 OpenAI Tool Calling 或类似规范的工具描述列表。实现要点与注意事项// 伪代码示例工具定义接口 interface PiTool { name: string; // 唯一工具名如 “get_weather” description: string; // 给LLM看的自然语言描述 schema: z.ZodSchema; // 使用 Zod 等库定义严格的输入参数模式 handler: (args: any, context: ToolContext) Promiseany; // 工具执行函数 } // 注册过程 harness.registerTool({ name: “calculate”, description: “执行数学计算”, schema: z.object({ expression: z.string().describe(“数学表达式如 ‘(5 3) * 2’”) }), handler: async ({ expression }, ctx) { // 安全警告直接 eval 极其危险此处仅为示例。 // 真实场景应使用沙箱或数学表达式解析库如 math.js。 try { const result eval(expression); return { result: 表达式“${expression}”的计算结果是${result} }; } catch (error) { return { error: 计算失败: ${error.message} }; } } });注意工具执行函数handler的安全性是重中之重。如上例中的eval在生产环境中是绝对禁止的。必须对输入进行严格的净化和校验或使用受限的沙箱环境来执行不可信代码。实操心得Schema 即契约工具的模式定义Schema要尽可能精确和详细。好的description和参数describe能极大提升 LLM 调用工具的准确率。命名规范化工具名最好使用snake_case并保持动词名词的语义清晰如search_web,update_database_record这符合大多数 LLM 的训练数据格式。上下文注入handler函数应能接收到一个ToolContext对象其中包含当前会话 ID、用户信息、之前的对话历史等这对于实现有状态的工具交互至关重要。3.2 Tool Executor工具调用的执行引擎当 LLM 返回一个形如{“tool_calls”: [{“id”: “call_123”, “type”: “function”, “function”: {“name”: “get_weather”, “arguments”: “{\”city\“: \”北京\“}”}}]}的响应时Tool Executor 就该上场了。核心职责解析与验证解析 LLM 返回的 Tool Call 对象验证工具名是否存在参数是否符合 Schema。执行与超时控制调用对应的handler函数并设置合理的超时时间防止某个工具调用卡死整个 Agent。结果格式化将handler返回的结果封装成标准的 Tool Call Result 格式以便返回给 LLM 进行下一轮推理。错误处理捕获执行过程中的异常网络错误、逻辑错误、权限错误等并将其转化为 LLM 能理解的错误信息格式。实现要点class ToolExecutor { private toolRegistry: ToolRegistry; async executeToolCall(toolCall: ParsedToolCall): PromiseToolResult { const tool this.toolRegistry.get(toolCall.name); if (!tool) { return { tool_call_id: toolCall.id, error: 未知工具: ${toolCall.name} }; } // 1. 参数验证 const parseResult tool.schema.safeParse(toolCall.arguments); if (!parseResult.success) { return { tool_call_id: toolCall.id, error: 参数验证失败: ${parseResult.error.message} }; } // 2. 创建执行上下文 const context this.createToolContext(toolCall); // 3. 执行带超时 try { const result await Promise.race([ tool.handler(parseResult.data, context), new Promise((_, reject) setTimeout(() reject(new Error(“工具执行超时”)), 30000) ) ]); return { tool_call_id: toolCall.id, output: result }; } catch (error) { // 4. 错误处理与转换 const errorMessage error instanceof Error ? error.message : ‘未知错误’; return { tool_call_id: toolCall.id, error: 执行失败: ${errorMessage} }; } } }常见问题与排查LLM 不调用工具首先检查registerTool时提供的description是否清晰LLM 是根据描述来决定是否以及如何调用工具的。其次检查返回给 LLM 的工具列表格式是否与其 API 要求一致如 OpenAI 的tools字段。参数总是解析失败这通常是 Schema 定义与 LLM 实际生成内容不匹配。LLM 可能生成{“city”: “Beijing”}但你的 Schema 期望的是{“location”: “Beijing”}。需要调整 Schema 或通过更清晰的描述和示例来引导 LLM。工具执行慢为每个handler设置独立的超时时间并考虑引入并发执行。如果多个 Tool Call 之间没有依赖关系Pi 这样的 Harness 应该支持并行执行以提高效率。3.3 Context Manager状态管理与信息传递桥梁Agent 在完成复杂任务时需要记住之前步骤的结果。例如先调用search_web找到了某公司的电话然后需要调用make_phone_call。电话号码就需要在两个工具间传递。这就是 Context Manager 的职责。核心职责会话状态存储为每个对话或任务链提供一个键值存储空间。工具间共享数据允许一个工具将输出写入上下文供后续工具读取。上下文注入自动将相关的上下文信息作为提示词的一部分提供给 LLM帮助其做出更准确的决策。设计模式 Pi 的 Context Manager 可能提供类似以下接口的工具set_context(key: string, value: any): 设置上下文值。get_context(key: string): any: 获取上下文值。append_to_context(key: string, value: any): 向一个数组类型的上下文追加内容常用于保存历史消息。实操技巧结构化上下文不要胡乱存储。可以设计固定的上下文结构如{ “user_preferences”: {}, “conversation_history”: [], “task_results”: {} }便于管理。避免上下文膨胀LLM 的上下文窗口是有限的。需要设计策略来摘要Summarize或淘汰Evict旧的、不重要的上下文信息。Pi 可能提供一个工具或钩子hook来让你实现自定义的上下文窗口管理逻辑。安全性上下文可能包含用户敏感信息。确保在持久化或传输时进行加密并遵守数据隐私规范。3.4 Flow Controller执行流程的调控器这是赋予 Harness 灵活性和可控性的关键。一个简单的 Agent 可能是线性的思考 - 调用工具 - 再思考。但复杂场景需要暂停、重试、跳转、人工审核介入。Flow Controller 就提供了这些基础原语。可能提供的工具或能力暂停/继续pause_task(taskId),resume_task(taskId)。允许外部系统如人工坐席中断自动流程进行检查或干预。重试retry_tool_call(toolCallId)。当某个工具调用因临时网络问题失败时可以触发重试而不是直接让整个任务失败。终止terminate_task(taskId, reason)。在满足某些条件如用户取消、策略违规时安全地终止整个 Agent 执行。跳转goto_step(stepLabel)。在某些工作流引擎中允许根据条件跳转到不同的步骤。实现考量 Flow Controller 的实现通常与 Harness 的核心事件循环Event Loop或状态机紧密耦合。它需要维护每个任务Task或会话Session的状态运行中、已暂停、已终止、已完成并暴露 API 供外部调用或供其他工具内部触发。应用场景人工在环Human-in-the-loop当 Agent 需要确认一个高风险操作如发送邮件、支付时可以调用pause_task并通知人工审核。审核通过后再调用resume_task。条件性重试在Tool Executor捕获到可重试错误如 5xx 服务器错误时可以自动或通过策略调用重试逻辑。超时保护如果一个任务运行时间过长一个监控进程可以调用terminate_task来防止资源耗尽。4. 从零开始基于 Pi 理念构建一个简易 Harness理解了四大核心组件的原理后我们可以尝试抛开 Pi 的具体实现用 TypeScript 模拟其理念构建一个自己的极简 Harness。这将帮助我们更深刻地体会其设计精妙之处。4.1 项目初始化与核心类型定义首先我们创建一个 monorepo 风格的 TypeScript 项目。mkdir my-minimal-harness cd my-minimal-harness npm init -y npm install typescript ts-node types/node zod npx tsc --init创建核心类型定义文件src/types.tsimport { z } from “zod”; // 工具调用请求来自LLM export interface ToolCall { id: string; name: string; arguments: string; // JSON string } // 工具调用结果返回给LLM export interface ToolResult { tool_call_id: string; output?: any; error?: string; } // 工具定义 export interface ToolDefinitionTInput any, TOutput any { name: string; description: string; inputSchema: z.ZodSchemaTInput; execute: (args: TInput, context: ExecutionContext) PromiseTOutput; } // 工具执行上下文 export interface ExecutionContext { sessionId: string; getState: T(key: string) T | undefined; setState: (key: string, value: any) void; // 可以扩展用户信息、日志器等 } // Harness 核心状态 export interface HarnessState { tools: Mapstring, ToolDefinition; sessionStates: Mapstring, Mapstring, any; // sessionId - (key - value) }这个类型系统定义了数据流动的契约是保证整个系统类型安全的基础。4.2 实现核心工具类接下来我们实现三个核心类对应前文分析的 Registry、Executor 和 Context Manager。Flow Controller 的概念我们暂时融入到 Executor 和主循环中。1. ToolRegistry (工具注册中心) -src/ToolRegistry.tsimport { ToolDefinition, HarnessState } from “./types”; export class ToolRegistry { private state: HarnessState; constructor(state: HarnessState) { this.state state; } register(tool: ToolDefinition): void { if (this.state.tools.has(tool.name)) { throw new Error(工具 ‘${tool.name}’ 已存在); } this.state.tools.set(tool.name, tool); console.log([ToolRegistry] 工具 ‘${tool.name}’ 注册成功); } getTool(name: string): ToolDefinition | undefined { return this.state.tools.get(name); } // 生成供LLM使用的工具描述列表 getToolDescriptors(): Array{name: string; description: string; parameters: any} { return Array.from(this.state.tools.values()).map(tool ({ name: tool.name, description: tool.description, parameters: tool.inputSchema._def // 简化处理实际需转换为JSON Schema })); } }2. ContextManager (上下文管理器) -src/ContextManager.tsimport { ExecutionContext, HarnessState } from “./types”; export class ContextManager { private state: HarnessState; constructor(state: HarnessState) { this.state state; } createExecutionContext(sessionId: string): ExecutionContext { // 确保该会话的状态Map存在 if (!this.state.sessionStates.has(sessionId)) { this.state.sessionStates.set(sessionId, new Map()); } const sessionState this.state.sessionStates.get(sessionId)!; return { sessionId, getState: T(key: string): T | undefined { return sessionState.get(key) as T; }, setState: (key: string, value: any): void { sessionState.set(key, value); } }; } // 可选提供全局上下文清理等方法 cleanupSession(sessionId: string): void { this.state.sessionStates.delete(sessionId); } }3. ToolExecutor (工具执行器) -src/ToolExecutor.tsimport { ToolCall, ToolResult, ToolDefinition, ExecutionContext } from “./types”; import { ToolRegistry } from “./ToolRegistry”; import { ContextManager } from “./ContextManager”; export class ToolExecutor { constructor( private toolRegistry: ToolRegistry, private contextManager: ContextManager ) {} async execute(toolCall: ToolCall, sessionId: string): PromiseToolResult { const tool this.toolRegistry.getTool(toolCall.name); if (!tool) { return { tool_call_id: toolCall.id, error: 工具 ‘${toolCall.name}’ 未找到 }; } // 1. 解析参数 let parsedArgs: any; try { parsedArgs JSON.parse(toolCall.arguments); } catch { return { tool_call_id: toolCall.id, error: “参数不是有效的JSON格式” }; } // 2. 验证参数 const validation tool.inputSchema.safeParse(parsedArgs); if (!validation.success) { return { tool_call_id: toolCall.id, error: 参数验证失败: ${validation.error.message} }; } // 3. 创建执行上下文 const context this.contextManager.createExecutionContext(sessionId); // 4. 执行工具 try { const output await tool.execute(validation.data, context); return { tool_call_id: toolCall.id, output }; } catch (error) { const errorMsg error instanceof Error ? error.message : String(error); return { tool_call_id: toolCall.id, error: 工具执行异常: ${errorMsg} }; } } // 批量执行并行 async executeAll(toolCalls: ToolCall[], sessionId: string): PromiseToolResult[] { const promises toolCalls.map(call this.execute(call, sessionId)); return Promise.all(promises); } }4.3 组装 Harness 与主事件循环最后我们将这些组件组装起来并模拟一个简单的 Agent 运行循环。src/Harness.tsimport { HarnessState } from “./types”; import { ToolRegistry } from “./ToolRegistry”; import { ContextManager } from “./ContextManager”; import { ToolExecutor } from “./ToolExecutor”; // 模拟一个极简的LLM客户端实际应替换为 OpenAI、Anthropic 等 SDK class MockLLMClient { async chat(messages: any[], tools: any[]): Promise{tool_calls?: ToolCall[]} { // 这里是模拟逻辑如果用户消息提到“计算”就调用计算器工具 const lastMessage messages[messages.length - 1]?.content || “”; if (lastMessage.includes(“计算”)) { return { tool_calls: [{ id: “call_” Date.now(), name: “calculate”, arguments: JSON.stringify({ expression: “(10 20) * 2” }) // 模拟LLM生成的参数 }] }; } // 否则正常回复 return { content: “我是一个模拟的LLM你说了: “ lastMessage }; } } export class MinimalHarness { private state: HarnessState { tools: new Map(), sessionStates: new Map() }; private toolRegistry: ToolRegistry; private contextManager: ContextManager; private toolExecutor: ToolExecutor; private llmClient: MockLLMClient; constructor() { this.toolRegistry new ToolRegistry(this.state); this.contextManager new ContextManager(this.state); this.toolExecutor new ToolExecutor(this.toolRegistry, this.contextManager); this.llmClient new MockLLMClient(); } getToolRegistry(): ToolRegistry { return this.toolRegistry; } // 核心运行循环 async runSession(sessionId: string, initialInput: string): Promisevoid { const messages [{ role: “user”, content: initialInput }]; let maxTurns 5; // 防止无限循环 while (maxTurns-- 0) { // 1. 获取当前可用工具描述 const availableTools this.toolRegistry.getToolDescriptors(); // 2. 调用LLM传入对话历史和工具列表 const llmResponse await this.llmClient.chat(messages, availableTools); // 3. 处理LLM响应 if (llmResponse.content) { console.log([Agent]: ${llmResponse.content}); messages.push({ role: “assistant”, content: llmResponse.content }); // 如果没有工具调用对话可能结束或继续 break; // 简化处理假设一次工具调用后结束 } if (llmResponse.tool_calls llmResponse.tool_calls.length 0) { console.log([LLM 决定调用工具]:, llmResponse.tool_calls); // 4. 执行工具调用 const results await this.toolExecutor.executeAll(llmResponse.tool_calls, sessionId); // 5. 将工具执行结果作为消息追加供LLM下一轮推理 messages.push({ role: “assistant”, content: null, tool_calls: llmResponse.tool_calls }); results.forEach(result { messages.push({ role: “tool”, tool_call_id: result.tool_call_id, content: result.error ? 错误: ${result.error} : JSON.stringify(result.output) }); }); console.log([工具执行结果]:, results); } } } }4.4 编写示例工具并运行测试现在我们创建一个示例文件src/index.ts来使用这个自制的 Harnessimport { MinimalHarness } from “./Harness”; import { z } from “zod”; async function main() { const harness new MinimalHarness(); const registry harness.getToolRegistry(); // 注册一个计算器工具模拟 Pi 的 4个工具之一 registry.register({ name: “calculate”, description: “执行一个数学表达式并返回结果。确保表达式是安全的。”, inputSchema: z.object({ expression: z.string().min(1).describe(“数学表达式例如 ‘3 5 * 2’”) }), execute: async (args, context) { // 警告生产环境请使用 math.js 等安全库 // 这里仅为演示。 console.log([工具 calculate] 正在执行表达式: ${args.expression}, 会话: ${context.sessionId}); try { // 极其简化的安全示例只允许数字和基础运算符 if (!/^[\d\s\-*/().]$/.test(args.expression)) { throw new Error(“表达式包含不安全字符”); } const result Function(“use strict”; return (${args.expression}))(); context.setState(“last_calculation”, result); // 演示上下文存储 return { success: true, result }; } catch (error) { return { success: false, error: (error as Error).message }; } } }); // 注册一个获取上下文的工具模拟另一个核心工具 registry.register({ name: “get_context”, description: “获取当前会话中存储的指定键的值。”, inputSchema: z.object({ key: z.string().describe(“要获取的上下文键名”) }), execute: async (args, context) { const value context.getState(args.key); return { key: args.key, value }; } }); // 运行一个会话 console.log(“ 开始 Harness 演示会话 ”); await harness.runSession(“session_123”, “请帮我计算一下 (10 20) * 2 等于多少”); console.log(“ 演示结束 ”); } main().catch(console.error);运行npx ts-node src/index.ts你会看到类似以下的输出 开始 Harness 演示会话 [ToolRegistry] 工具 ‘calculate’ 注册成功 [ToolRegistry] 工具 ‘get_context’ 注册成功 [LLM 决定调用工具]: [ { id: ‘call_…’, name: ‘calculate’, arguments: ‘{“expression”:”(10 20) * 2”}’ } ] [工具 calculate] 正在执行表达式: (10 20) * 2, 会话: session_123 [工具执行结果]: [ { tool_call_id: ‘call_…’, output: { success: true, result: 60 } } ] 演示结束 通过这个从零构建的过程你可以清晰地看到一个极简 Harness 的核心骨架是如何搭建的。Pi 项目的价值在于它将这些核心组件设计得更健壮、更可扩展例如支持流式响应、更复杂的状态管理、插件化等并且提供了开箱即用的、与流行 LLM API 兼容的适配器。5. 进阶探讨在真实项目中应用与避坑指南当你理解了 Pi 这类极简 Harness 的核心理念后就可以在真实项目中应用它或者将其思想融入现有架构。这里分享一些进阶经验和常见陷阱。5.1 工具设计的最佳实践与反模式最佳实践单一职责每个工具只做一件事并且做好。send_email工具就只负责发邮件不要在里面又去查数据库验证用户。复杂的逻辑应该由 Agent 的多次工具调用来编排。无状态性尽可能让工具函数是无状态的Stateless。状态应该通过ExecutionContext来管理和传递。这有利于工具的重用和测试。充分的错误信息工具执行失败时返回的错误信息应该对 LLM 友好。例如不要只返回“Error 500”而应该返回“调用天气API失败可能服务暂时不可用请稍后再试。”这能帮助 LLM 进行下一步决策如重试或告知用户。输入验证与净化这是安全生命线。除了用 Zod Schema 做类型验证对于执行命令、访问文件、操作数据库的工具必须对输入进行严格的净化和权限检查。常见反模式工具过于庞大一个工具做十件事导致 Schema 复杂无比LLM 难以正确调用且难以维护。工具依赖隐藏状态工具内部依赖全局变量或外部可变状态导致在并发或分布式环境下行为不可预测。工具副作用不明确一个名为get_user_info的工具却在内部偷偷修改了用户数据。这会让 Agent 的推理逻辑混乱。5.2 与现有生态的集成策略你很少会从零开始。Pi 这样的 Harness 需要与现有生态集成。与 LLM SDK 集成你需要编写一个薄薄的适配层Adapter将 Harness 管理的工具列表转换成 OpenAI、Anthropic、Google Gemini 等 SDK 要求的格式并将 SDK 返回的 Tool Call 解析成 Harness 能处理的格式。Pi 的 monorepo 里通常就包含了pi/adapter-openai这样的包。与后端框架集成如果你的 Agent 是 Web 服务的一部分如 Express.js、Next.js、FastAPI需要将 Harness 实例封装成服务并提供相应的 HTTP 端点或 GraphQL Resolver 来处理对话请求。与状态存储集成上述示例中上下文状态存在内存里这不利于水平扩展和持久化。在生产中你需要将HarnessState中的sessionStates替换为 Redis、PostgreSQL 或任何你喜欢的数据库客户端。与监控和可观测性集成在每个工具执行的开始和结束、以及关键决策点埋点将日志、指标和追踪数据发送到像 OpenTelemetry、Datadog、Sentry 这样的平台。这对于调试复杂 Agent 行为至关重要。5.3 性能优化与扩展性考量当工具调用量大或工具本身是 IO 密集型如网络请求时需要考虑性能。并行执行如果 LLM 一次性返回多个独立的 Tool Call应该并行执行它们。我们的ToolExecutor.executeAll已经用了Promise.all。超时与熔断为每个工具设置独立的超时。对于频繁失败的外部服务工具可以考虑实现简单的熔断器Circuit Breaker模式暂时阻止对其的调用。异步流式输出对于执行时间较长的工具如生成报告可以支持流式返回部分结果Partial Output让 LLM 或前端能实时看到进度提升用户体验。这需要 Harness 和 LLM API 都支持流式响应。工具的热加载在不停机的情况下动态注册或注销工具。这可以通过在ToolRegistry中实现相关方法并配合一个文件监听器或配置中心来实现。5.4 调试与问题排查实战记录开发 Agent 应用大部分时间都在调试。以下是一些实战中遇到的问题和排查思路问题一LLM 总是忽略某个工具不调用它。排查首先检查该工具的description是否清晰、无歧义并且确实与用户问题相关。用一些测试问题直接问 LLM“为了回答这个问题你会使用哪些工具为什么” 观察其推理。其次检查返回给 LLM 的工具列表格式是否正确特别是parameters的 JSON Schema 是否符合 API 规范。解决重写工具描述使其更符合 LLM 的“思维习惯”。可以提供少量示例Few-shot在系统提示词中。如果问题依旧可能是该工具的功能本身就可以被 LLM 的内在能力所替代如简单计算这时需要考虑这个工具是否必要。问题二工具执行成功但返回的结果 LLM 无法理解或错误使用。排查检查工具返回的数据结构。是否过于复杂嵌套是否包含了 LLM 无法解析的二进制数据或特殊符号返回的文本是否清晰、完整解决简化输出结构优先返回纯文本或简单的 JSON 对象。在返回中增加一些自然语言描述。例如不要只返回{“temp”: 22, “unit”: “C”}而是返回“当前温度是 22 摄氏度。”或者至少是{“result”: “当前温度是 22 摄氏度。”, “data”: {“temp”: 22, “unit”: “C”}}。问题三在多轮对话中Agent “忘记”了之前工具调用的结果。排查检查对话历史messages是否被正确维护。确保每一轮的工具调用和工具输出都被正确地以role: “assistant”(带tool_calls) 和role: “tool”的形式追加到了消息列表中。同时检查ExecutionContext中的状态是否在工具间正确传递。解决实现一个健壮的会话管理器Session Manager确保对话历史的完整性和长度管理避免超出上下文窗口。对于关键信息除了放在上下文状态中也可以让工具将其以自然语言总结的形式追加到对话历史里确保 LLM 能“看到”。问题四在分布式部署下同一个会话的请求被路由到不同实例导致上下文丢失。排查这是典型的有状态服务扩展问题。内存中的sessionStates在实例间不共享。解决必须引入外部共享存储如 Redis。将ContextManager的底层存储替换为 Redis client。同时需要考虑会话状态的序列化/反序列化以及可能的并发写冲突问题可以使用乐观锁或分布式锁。Pi 这样的极简主义 Agent Harness其力量不在于它提供了多少功能而在于它清晰地定义了边界并提供了坚实、可组合的基础。它让你从繁琐的基础设施代码中解脱出来专注于让 Agent 变得更智能、更可靠。当你真正需要处理复杂编排、长期记忆、动态工具链时你可以基于这个稳固的底层按需引入更高级的组件而不是被一个庞大框架的既定范式所束缚。这或许就是“少即是多”在 AI 工程领域的最佳诠释。