从零到一解构AI Agent框架：为什么需要它，又如何选择？
深入剖析Agent框架如何解决大模型落地的真实痛点，并通过LangChain、Pi-Mono和DeerFlow的实战对比，揭示其核心设计哲学。
几乎所有AI Agent的底层逻辑都可以被抽象为一个简洁的ReAct推理循环 ：接收问题，大模型思考，根据预设的系统提示词（System Prompt）调用相应的工具获取信息，如此循环往复，直到获取所有必要信息后，生成最终结果。
既然逻辑如此"简单"，我们为何还需要一个专门的Agent框架？不同的框架之间又有何本质区别？本文将从真实痛点出发，结合对主流框架的深度对比与代码实践，为你一次讲透。
一、 框架要解决的真问题：屏蔽差异，提供"确定性"
一个成熟的Agent框架，首要任务是对LLM（大语言模型）生态中的各种"不一致"做统一的抽象处理，为上层应用提供稳定、可靠的开发体验。
1. 统一多模型的调用规范
目前，不同模型厂商的API规范五花八门。从OpenAI的 Completions API 和新的 Responses API，到Anthropic的 Message API，再到Google的 Generative AI API，各有标准。
更棘手的是，即使很多厂商声称兼容OpenAI的接口，其具体实现也存在细微差别：
- 参数差异 ：有的用
max_tokens，有的用max_completion_tokens。 - 功能差异 ：有的不支持系统提示词的
developer角色，有的不支持reasoning_effort参数。 - 返回格式差异 ：推理内容可能在不同字段中返回（如
reasoning_contentvsreasoning），流式返回的SSE格式和Token统计方式也不尽相同。
因此，框架的第一要务是构建一个统一的模型调用抽象层，让开发者能在不同模型间自由切换而无须修改业务代码。
2. 保证输出的确定性与类型安全
Agent的核心在于"行动"，而行动依赖于精准的信息传递。当我们需要模型返回一个结构化数据（如JSON）来调用函数时，模型的输出必须是确定且可靠的。
尽管有些模型原生支持JSON Schema或Function Calling，但更多模型并不具备此能力。一个合格的Agent框架必须能在应用层提供类型安全的工具定义能力（如通过TypeBox、Pydantic、JSON Schema等），将模糊的自然语言处理成确定的结构化指令，并可靠地解析模型的输出。
3. 提供可扩展的"上下文工程"能力
Agent的长期运行离不开对上下文（Context）和记忆（Memory）的精细化管理。这远不止是"保存聊天记录"，而是涉及：
- 会话持久化：如何高效存储和加载对话历史（JSONL、数据库等）。
- 上下文窗口管理：当对话历史超出模型上下文窗口限制时，如何进行自动压缩与摘要，同时不丢失关键信息。
- 生命周期干预 ：框架需要在每次请求模型前、后，以及工具调用前后提供Hooks或中间件（Middleware）扩展点，让开发者能灵活地修改提示词、过滤消息、审计工具调用等。
二、 两大主流框架对决：LangChain vs. Pi-Mono
理解了框架要解决的核心问题后，我们来看看目前市面上两种典型的设计哲学：以Python生态为代表的 LangChain/LangGraph ，和以TypeScript生态为代表的 Pi-Mono。
| 对比维度 | LangChain & LangGraph (Python) | Pi-Mono (TypeScript) |
|---|---|---|
| 设计哲学 | 大而全的"军火库"。提供从模型集成、链式调用、预设Agent到低级编排(LangGraph)的全套工具，生态丰富，概念较多。 | 分层、可拔插的"工具箱" 。从底层的模型调用(pi-ai)到完整的编码Agent(pi-coding-agent)，可以按需取用，设计极简。 |
| 核心抽象 | Agent、Tool、Middleware、Checkpointer 等，通过LangGraph的图（Graph）和状态（State）机制进行灵活编排。 |
明确的分层架构：pi-ai(模型抽象) -> pi-agent-core(Agent循环) -> pi-coding-agent(完整运行时)。 |
| 工具定义 | 基于 Pydantic 和 JSON Schema ，通过 @tool 装饰器定义，类型与描述清晰。 |
基于 TypeBox，同样能提供强类型和参数描述，且能享受TypeScript的类型推断。 |
| 上下文管理 | 通过 Checkpointer （如SqliteSaver）持久化状态，借助 Middleware （如SummarizationMiddleware）实现上下文压缩与修改。 |
原生支持 JSONL文件 做会话持久化，简单透明。通过Extension API暴露上下文重写、压缩等关键事件钩子。 |
| 流式处理 | 支持多种 stream_mode，可以监听Agent循环中的不同事件（如updates）。 |
提供统一的 streamSimple 函数，通过for await...of循环处理text_delta、done、error等事件。 |
Pi-Mono的哲学洞察： 其作者在文章中阐述，其设计目标是 "让简单的事情保持简单，让复杂的事情成为可能" 。它不像是一个"框架"，更像是一组配合默契的库。你可以只用 pi-ai 调用模型，也可以在此基础上用 pi-agent-core 构建自己的Agent循环，或直接使用功能完备的 pi-coding-agent。这种自下而上的分层设计赋予了开发者极大的灵活性。
三、 实战：从零手搓一个Agent
理论终须实践检验。我们分别用 Pi-Mono 和 LangGraph 的思维，快速构建一个可交互的AI助手。
1. 用Pi-Mono手搓一个终端Coding Agent
Pi-Mono 的优势在于其库可以像乐高积木一样自由组合。下面的代码片段展示了如何绕过其高级封装，直接使用核心模块构建一个带TUI（终端用户界面）的Coding助手。
代码结构（assistant-tui.ts）：
typescript
// 1. 引入核心模块
import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
import { getModel, Type, streamSimple } from "@mariozechner/pi-ai";
import { TUI, Editor, Markdown, ProcessTerminal } from "@mariozechner/pi-tui";
// 2. 定义自定义工具（如网页搜索）及其类型
const webSearchTool = {
name: "web_search",
label: "Web Search",
description: "Search the web for...",
parameters: Type.Object({ query: Type.String({ description: "..." }) }),
execute: async (params) => ({ content: [{ type: "text", text: `Results for ${params.query}...` }] })
};
// 3. 初始化模型与持久化会话
const model = getModel("minimax-cn", "MiniMax-M2.7");
const sessionManager = SessionManager.open("path/to/session.jsonl");
// 4. 创建Agent会话，注入自定义工具
const { session } = await createAgentSession({ model, sessionManager, customTools: [webSearchTool], thinkingLevel: "off" });
// 5. 初始化TUI组件（编辑器、Markdown渲染器等）
const tui = new TUI(new ProcessTerminal());
const editor = new Editor(tui, editorTheme);
// ... 为编辑器设置自动补全、提交处理等
// 6. 订阅Agent事件，驱动TUI更新
session.subscribe((event) => {
// 处理 agent_start, message_update, tool_execution_start, agent_end 等事件
// 动态更新TUI界面，如显示思考状态、流式输出、工具调用信息
});
// 7. 用户输入处理，调用 session.prompt(trimmed)运行效果 ：仅需一个 npx tsx assistant-tui.ts 命令，一个拥有流式对话、Markdown渲染、自定义工具调用、斜杠命令和持久化会话的终端Agent就跑起来了。这种极致的开发效率是Pi-Mono分层设计带来的直接优势。
2. 深度解析：字节跳动DeerFlow如何用LangGraph构建"超级助理"
DeerFlow 展示了另一种模式：如何在LangGraph的生态上，通过工程化手段打造一个功能全面、健壮的生产级Agent。
从1.0到2.0，DeerFlow实现了一个关键的思想跃迁：从依赖"硬编码流程图"执行任务，转变为依赖"模型能力+上下文工程"来动态决策。 1.0版本基于LangGraph构建了确定的Planner-Executor工作流，而2.0版本则基于LangChain的基础Agent循环，通过一套强大的中间件体系，赋予了Agent灵魂。
DeerFlow 2.0的核心组件包括：
- 精心设计的系统提示词 ：一个由XML标签精细组织的模板，动态注入了
<memory>(用户记忆)、<skill_system>(技能加载)、<subagent_system>(子任务分解)、<clarification_system>(主动澄清)等模块，将Agent的角色、能力和工作流定义得非常清晰。 - 强大的中间件（Middleware）体系 ：这是DeerFlow的精华所在。它在Agent的生命周期的各个环节挂载了18个中间件，解决了大量实际工程问题。以下是几个有代表性的中间件：
- SandboxMiddleware & SandboxAuditMiddleware ：提供基于虚拟路径映射的代码执行沙箱，并在执行前对高危命令（如
rm -rf /）进行安全审计和拦截。 - ClarificationMiddleware：拦截模型的澄清请求，中断当前执行流，等待用户明确需求后再继续，解决了Agent"自问自答"或"错误假设"的问题。
- SummarizationMiddleware：当对话上下文接近Token限制时，自动对历史消息进行摘要压缩，同时保留关键信息。
- MemoryMiddleware：一个异步、去抖动的长期记忆系统，能在多轮对话中沉淀用户信息，并在后续交互中动态注入提示词，实现个性化服务。
- LoopDetectionMiddleware：通过哈希和频率两层检测机制，发现并打破Agent陷入的工具调用死循环。
- SandboxMiddleware & SandboxAuditMiddleware ：提供基于虚拟路径映射的代码执行沙箱，并在执行前对高危命令（如
- 可插拔的工具体系 ：通过配置文件(
config.yaml)，可以灵活加载内置工具、沙箱工具、MCP工具和ACP工具，实现了高度的可扩展性。
Debug与可观测性：使用LangSmith可以清晰地追踪和分析Agent的整个思考与执行链路，这对于调试复杂的Agent行为至关重要。
四、 从框架到基座：以Claude Code SDK为底座的开发新范式
如果你的目标不是从零构建一个Agent框架，而是快速开发一个解决复杂任务的AI应用，那么直接以功能完善的Agent（如Claude Code）为基座进行二次开发，或许是最佳路径。
Claude Code等产品本身就是一个集成了顶级模型、强大工具链（文件操作、Bash）、MCP/Skills扩展和完善权限系统的Agent。它的SDK提供了：
- Hooks：在Agent生命周期的各个节点（如工具调用前后、用户提交前）注入自定义逻辑。
- Custom Tools & MCP：轻松扩展Agent的能力边界。
- Sub-agents：实现任务的分解与并行处理。
- Session & Permission：管理会话和精细化的权限控制。
这种范式的核心优势在于，让开发者从"如何让Agent思考与行动"的底层细节中解放出来，专注于"要解决什么业务问题"本身，直接将Claude Code作为一个可编程的、智能的AI基座，开发出针对特定工作流的深度应用。
总结
从Pi-Mono的极简分层，到LangChain/LangGraph的庞大生态与精密控制，再到DeerFlow生产级的中间件体系，我们看到了Agent框架演进的多样路径。
- 选择 Pi-Mono，意味着你认同"库优于框架"的哲学，追求按需组合的灵活性，并想在TypeScript生态中快速启动一个性能卓越的Agent。
- 选择 LangChain & LangGraph，意味着你拥抱Python生态的丰富性，需要对接海量的模型和工具集成，并通过可观察的工具(LangSmith)来驾驭复杂系统。
- 选择 Claude Code SDK，则是站在巨人的肩膀上，将顶级Agent能力作为基座，实现商业价值的最大化。
无论选择哪条路，深刻理解Agent框架要解决的 "统一、确定、管理" 这三大核心问题，以及"上下文工程远比模型本身更重要"这一原则，才是构建出色AI应用的关键。