读懂Agent框架源码：Pi Agent核心循环与上下文管理实战

我最初接触 Pi Agent其实带着一点抵触情绪。市面上主流的 agent 框架已经很多了LangChain、CrewAI、AutoGen 各有各的拥趸文档和教程一搜一大把。但真到自己上手做项目我发现了一个尴尬的问题文档越厚的框架出问题时越难定位。框架帮你把 80% 的重复劳动省掉了剩下 20% 的异常处理你根本不知道它内部发生了什么。所以这篇文章不是我写给你的教程而是我作为一个普通的大模型应用开发工程师决定不再黑盒使用框架之后认认真真啃 Pi Agent 框架源码的第一阶段笔记。内容包括我为什么选它、怎么搭建一个能断点调试的环境、核心执行循环怎么运转、记忆和上下文又是如何管理的最后会附上我自己踩过的一些坑。如果你也在做 Agent 开发或者对框架内部机制有好奇心这篇文章应该能帮你少走不少弯路。1. 为什么我放着现成的Agent框架不用非要自己啃源码这个决定看起来有点反主流但我有很现实的理由。我在做的项目需要给大模型接入一批外部工具让它自动完成多步骤任务对稳定性和可控性的要求远高于花哨的功能。市面上的重型框架确实功能齐全可一旦运行结果不符合预期排查链路会非常痛苦。1.1 主流框架让我头疼的三个问题先说 LangChain。它的抽象层级非常多从 Chain、Runnable 到 AgentExecutor每一层都包了一层方便你扩展的接口。框架设计者当然是一片好心但当你需要调试一个三层嵌套的 Agent 调用时你会在 callback 回调的迷宫里转晕。我曾经为了定位一个简单的上下文传递 bug花了整整一个下午打日志。最后发现是一个继承类没有调用父类的__init__。CrewAI 走的是角色协作路线Agent、Task、Crew 三个概念设计得确实漂亮适合做团队模拟、流程编排。但对于单个Agent 外部工具 稳定执行这种偏底层的需求来说它的抽象太重了。你想改一个很底层的环节比如修改模型推理过程中的 prompt 拼装逻辑框架会告诉你请使用模板覆盖然后你翻文档发现模板结构比你想改的东西还复杂。AutoGen 的双 Agent 对话机制也很有意思但它把用户消息和 Agent 内部消息混在一起管理执行链路的追踪相对复杂。在我实际使用中多 Agent 之间的自动对话经常绕进意料之外的死循环而它内置的终止条件在这类场景下表现得不够直接。当然我不能一棍子打死这些框架它们各自的生态和社区都很成熟。只是在把框架内部逻辑彻底弄明白这件事上它们的体量不适合作为起点。所以我开始寻找更轻量、更透明、核心逻辑集中的框架。1.2 Pi Agent 打动我的几个特质我是在 GitHub 上翻到 Pi Agent 这个项目的。一开始吸引我的就是项目结构比较清爽没有动辄几十个模块的宏大抽象。几个让我最终选它的原因核心代码量不大主要执行逻辑集中在一两个文件里意味着我可以用一个下午读完主干依赖少不需要为跑通最小示例装一大堆插件式组件底层模型接口走的是 OpenAI 兼容协议市面上绝大多数模型服务都能直接接工具调用的设计思路很直白没有在函数和模型之间引入太多中间层。还有一点很关键——它支持源码方式安装。这意味着我可以直接改源码、在源码里打断点每一行代码的执行路径都能亲眼看到。这对源码阅读来说是非常重要的前提条件不是所有框架都愿意把代码组织得这么干净。1.3 我给自己定的源码阅读目标我读 Fan Agent 源码并不是为了重新造一个轮子而是有非常务实的三个目标。第一掌握核心循环。弄清楚一次用户请求进来之后框架在内部走了哪些步骤每一步的数据结构是怎么流转的。第二获得定位问题的能力。以后业务里再出现工具调用异常、上下文被截断、模型疯狂重试这类问题我能直接通过源码定位根源而不是到处搜索社区里有没有人遇到同样的问题。第三找到扩展点。我需要知道哪些地方可以安全地做定制哪些地方是核心逻辑不能乱动。这三个目标决定了我的阅读方式并不是从头到尾通读源码而是带着问题去追踪执行路径。2. 从Clone到跑通搭建可断点调试的源码阅读环境源码阅读的第一步不是读而是让代码在你的机器上真正跑起来。跑不起来的话你看到的很多逻辑都是抽象的、空洞的。只有当你看到一个请求走完整个流程、日志一行行打出来代码与行为之间才第一次建立起真实的对应关系。2.1 环境准备与源码安装我用 Python 3.11 和uv作为虚拟环境工具。如果你习惯 conda 或者 venv也完全没有问题核心是保证环境干净。第一步是把项目 clone 到本地然后进入项目根目录源码安装git clone https://github.com/pi-agent/pi-agent.git cd pi-agent uv venv source .venv/bin/activate uv pip install -e .这里我强烈建议用-e也就是 editable 模式安装。这样 Python 解释器会直接引用你 clone 的源码目录你在 IDE 里改的任何代码都会立刻生效断点也能正常触发。如果你跑去pip install pi-agent那装进 site-packages 的是打包后的副本断点调试时经常出现路径对不上、源码改不动的问题非常影响阅读体验。装好之后还需要确认依赖是否齐全。我 read 的时候项目核心依赖只有pydantic和openai两个非常友好。如果你在安装过程中发现还有别的依赖缺失直接按报错补装即可。2.2 用最小示例建立执行基线环境装好后不要急着读代码。先跑一个最小的示例让这个框架完成一次最简单的思考 调用工具流程。我写了一个天气查询工具只做模拟返回不接真实 APIfrom pi_agent import Agent from pi_agent.tools import tool tool def get_weather(city: str) - str: 获取指定城市的当前天气 return f{city} 当前晴26℃适合出门 agent Agent(modelgpt-4o-mini, tools[get_weather]) result agent.chat(杭州今天需要带伞吗) print(result.message)第一次跑通之后我做了这么几件事记录模型名、工具名、用户问题把返回值里除了正常回答之外的所有日志输出保存下来确认这次调用总共产生了多少个内部步骤。这份基线非常重要。因为后续读源码时我会频繁修改框架内部逻辑来验证假设。每次改动后我都要重新跑这个最小示例确认行为和基线一致。如果没有基线你根本分不清某个输出是框架的正常行为还是你改 bug 时引入的异常行为。2.3 让断点打在框架心脏位置最小示例跑通之后我打开 PyCharm在agent.py的核心循环入口函数打上了第一个断点然后以 Debug 模式重新运行。这一步的意义在于我亲眼看到了代码走到了框架内部核心路径上而不是只停在用户代码层。如果项目里只有用户代码断点只会在你调用的agent.chat()函数处命中想要深入框架内部就必须找到框架真正的执行入口。我的做法是全局搜索def run或者def chat找到Agent类的主方法然后在方法第一行打断点。调试过程中最值得观察的不是某个变量的值而是messages列表在每一轮循环前后的变化。你会看到用户消息被追加、模型返回消息被追加、工具执行结果被追加每一步都是对上下文的一次扩充。这个视角比任何文档都直观。2.4 第一眼印象目录结构跑通最小示例后我花了一些时间看项目整体目录。我 clone 的这份源码大体结构长这样pi_agent/ ├── agent/ │ ├── agent.py # Agent核心循环 │ └── context.py # 上下文管理 ├── llm/ │ ├── base.py # 模型接口抽象 │ ├── openai.py # OpenAI兼容实现 │ └── schemas.py # 请求/响应数据结构 ├── tools/ │ ├── base.py # 工具基类 │ └── parser.py # 函数转JSON Schema ├── memory/ │ ├── chat_memory.py # 会话消息存储 │ └── truncate.py # 上下文裁剪策略 └── types/ ├── message.py # 消息模型 └── events.py # 回调事件定义第一次看到这个目录我心里就有底了。核心逻辑集中在agent/agent.py模型接入在llm/openai.py工具机制在tools/记忆相关在memory/。模块划分非常清晰没有为了架构而架构的冗余设计。我当时的判断是按照工具 - 模型 - 核心循环 - 记忆的顺序逐个模块读最终一定能建立起完整认知。实际读下来这个判断基本准确。顺序上可以再优化这一点我放在第五节详细说。3. 核心执行循环一次完整推理的运转过程Agent 框架的灵魂是这个不断循环的推理-行动-观察过程。理解了这个循环你就理解了 Agent 为什么会自动化地完成多步任务。3.1 从入口看 Agent 的启动过程当你调用agent.chat(杭州今天需要带伞吗)时第一步并不是直接把问题扔给模型。框架先做了一次消息的标准化把你的原始字符串包装成内部定义的Message对象标记roleuser然后把它放进一个消息列表里。这个列表的第一条通常是system消息里面写着 Agent 的系统提示词比如你是智能助手之类的。如果你在调试器里观察会发现messages列表的初始结构大约是[ {role: system, content: 你是智能助手...}, {role: user, content: 杭州今天需要带伞吗} ]这一步看似简单但它是后续所有轮次的基础。Agent 内部永远不直接操作字符串而是操作结构化的消息对象。这个设计保证了多轮对话和工具调用结果能被模型正确理解。接下来封装好的消息列表会传给llm模块。框架在这里构造一个符合 OpenAI 协议格式的请求指定模型名、消息内容、工具定义等参数。我看的这份代码里请求构造的逻辑非常直观没有做额外的缓存或拦截是开箱即用的标准做法。3.2 模型响应与工具调用的分流判断请求发送到模型后模型会返回一个响应对象。关键的逻辑分流点出现在这里框架要判断模型到底是想结束对话还是想调用工具。模型返回的响应通常包含两类内容content是给用户看的文本回复tool_calls是模型发起的工具调用请求里面包含函数名和参数。判断方法很直接if response.tool_calls: # 进入工具执行分支不结束循环 else: # 返回最终回复给用户循环结束这一步是整个执行循环的大脑。如果模型想调用工具框架不会立刻把工具结果返回给用户而是进入下一轮。我把这个循环简化一下就是这样while round max_rounds: response llm.call(messages) if not response.tool_calls: return response.content messages.append(response.message) for call in response.tool_calls: result execute_tool(call) messages.append(tool_message(call.id, result))我一开始以为这个循环里会有复杂的优先级判断、路由规则之类。实际读了源码才发现和大多数 agent 循环的思路高度一致——它没那么神秘核心就是不断的请求-判断-执行-追加消息。3.3 工具执行中的边界处理工具执行是用户最容易踩坑的地方所以我重点读了这一块。首先是函数到 JSON Schema 的转换。框架通过解析函数的类型注解和 docstring自动生成模型所需的工具定义。比如我的get_weather(city: str)会被转换成这样一个 schema{ name: get_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { city: {type: string} }, required: [city] } }这里的实现细节很有意思。框架使用pydantic做了参数校验这意味着如果你的函数参数有复杂类型比如list[int]或者自定义枚举生成的 schema 也能自动保持结构正确。这一点对于工具函数的可维护性非常重要你不需要手写 JSON Schema只要保证 Python 函数签名规范schema 就能正确生成。其次是工具执行的异常处理。当你注册的工具内部抛异常时框架并不是把异常直接抛给上层中断整个流程而是把这个异常转换成一条工具结果消息交给模型来决定下一步怎么做。try: result tool_func(**arguments) except Exception as e: result f执行失败{e}这个设计我非常喜欢。因为模型具有理解错误并调整策略的能力你给模型一个工具报错了的信息它可能会换一种调用方式或者直接告诉用户哪里出了问题。这比框架直接炸掉要优雅得多。我在阅读时也验证过把工具内部故意写错Agent 会回复类似工具返回错误我换个方式再试试的下一步动作。最后是最大迭代轮数。所有 agent 框架都面临一个风险模型陷入调用死循环。比如模型反复调用同一个工具结果永远不满足退出条件。Pi Agent 的默认轮数设置得比较保守。我在业务里通常会根据任务复杂度调高但设置一个上限是必须的这个限制可以避免极端情况下 token 成本失控和响应时间过长。3.4 流式输出与过程可观测性现在主流大模型接口都支持流式输出agent 框架内部也需要支持逐 token 返回否则用户延迟体验会很差。我在阅读中发现框架通过回调事件的方式来透出执行进度dataclass class AgentEvent: type: str # tool_call, tool_result, message data: Any你可以在agent.chat(..., on_eventhandler)中注册一个回调每一轮的工具调用、工具结果、模型消息都会被推送给这个 handler。我的具体用法是把事件推给前端前端就能滚动展示 Agent 正在做什么——先是正在调用天气工具然后是工具返回结果最后是生成答案。这种透明度既是用户体验的一部分也是排查问题的重要抓手。当你发现某个 Agent 行为异常时事件流会告诉你问题出在第几轮、是工具返回了意外结果还是模型决策出了问题。4. 记忆与上下文管理框架如何应对Token膨胀读完核心循环紧接着要解决的一个现实问题是上下文一直涨token 终会爆。我在实际项目里踩过坑所以对框架处理上下文的方式特别敏感。这一节我带你看看 Pi Agent 在这块的设计思路和取舍。4.1 消息存储的基本结构框架里的记忆并不是什么玄学底层就是一个按顺序增长的消息列表。每一轮用户输入、模型回复、工具结果都会被追加到同一个列表里。结构上有一个非常直观的设计——消息对象里带上了tool_call_id这样的关联字段保证模型能够知道某条工具结果消息是对应哪一次调用请求的。这个列表在 Python 里就是一个内存对象不会自动持久化到数据库。如果你需要跨会话记忆得自己接外部存储。很多刚接触 agent 开发的同事常问我这个框架存记忆吗我的回答是框架只负责当前会话内的上下文管理能力长期记忆是应用层的职责。把持久化和清洗交给专门的数据库或向量库才是对系统稳定性负责的做法。4.2 Token 裁剪与摘要机制的实际观察我重点验证了memory/truncate.py里的逻辑。思路也直接设定一个max_tokens预算每次组装请求给模型前统计当前消息列表的总 token 数。如果超了就按从早到晚的顺序丢弃非系统消息直到总 token 数回到预算以内。这个策略的优点是实现简单、零额外模型调用成本缺点也很明显——早期对话的关键信息可能会被直接丢弃。比如用户在第一步说我想查杭州的天气到了第三轮框架裁剪时这条消息可能直接被当作不重要的历史丢掉了导致模型后续行为脱离原始意图。我看代码时还特别确认了一件事:框架目前没有内置自动摘要能力。所谓摘要就是把早期对话交给模型生成一个精简总结用一小段摘要文本替代完整历史。这是很多长上下文场景中更优雅的方案但实现成本高——每一步都需要额外调用一次模型。Pi Agent 选择把这块留给开发者自己扩展。这其实是一个很好的设计边界框架提供基础兜底能力不强行绑定成本较高的高级能力。4.3 记忆分层设计的现实意义很多 agent 框架把记忆分成短期记忆和长期记忆两层。短期记忆就是当前会话的消息列表长期记忆则是向量化的历史知识通过检索取回相关片段放回上下文。Pi Agent 这个版本给我的感觉是核心循环和工具调用已经打磨得比较成熟但在记忆分层上只做了基础层。这不算缺陷反而是轻量框架的定位使然。我的实际经验是长期记忆的能力需要与具体业务强耦合——存什么、怎么切分、什么时候检索、检索结果怎么注入这些问题很依赖场景。框架做成可插拔的反而更干净。我自己的做法是在业务代码里接入向量库做外部记忆检索在每次组装请求前把检索结果作为额外的 context 消息注入进去。这样既不破坏框架内部逻辑又能获得长期记忆能力。如果你直接改造框架源码往消息列表里塞假历史短期看能跑后期会非常难受——因为框架的裁剪策略不会考虑你的假历史结构可能会截出互不关联的碎片。5. 源码阅读方法论我踩过的坑和沉淀的技巧读源码这件事方法比努力重要。这一节我整理了自己在阅读 Pi Agent 过程中真正有用的技巧以及踩过的一些坑。如果你打算自己读源码这部分应该能帮你避免不少无效劳动。5.1 最有效的阅读顺序不是从README开始大多数人的直觉是从 README 开始看目录结构然后从上往下逐行读。我试过效率很低。原因是文件顶部通常是配置读取、日志初始化、常量定义这些信息对理解核心逻辑毫无帮助而且非常枯燥。我最终采用的方法是从执行路径反推。具体来说先找到最小示例的入口函数比如agent.chat()在 debugger 里单步进入让运行轨迹带着你走完整个主干流程旁观每一轮循环时 messages 结构的变化遇到分支逻辑再去跳转阅读对应模块比如工具执行异常处理读完全部主干流程后再回到目录结构补看哪些文件还没覆盖到。这个方法理论上相当于让代码当导游每个模块、每个文件的定位都是基于真实调用链触发的你记得会很深。如果你直接从头读很可能陷入读了半天不知道这段代码有什么用的挫败感。5.2 依赖版本冲突与接口变化我把环境搭好、跑最小示例时也栽过跟头。最常见的是pydantic版本冲突。现在很多框架底层都依赖 pydantic 做数据校验但 pydantic v2 和 v1 的 API 差异非常大。如果项目里其他依赖用的是 v1 写法同时又升级了 v2 兼容层很容易出现字段验证失败这种奇怪的报错。我当时的排查过程是先看完整 stack trace定位是哪一行 pydantic 代码抛错再检查项目中 pydantic 的版本。最后通过创建独立虚拟环境、确认安装顺序后才解决。这里我的建议是读这个框架源码时最好在全新虚拟环境中进行尽量不要依赖公司项目里已有的 Python 环境。因为已有环境通常装了不同版本的各种包环境冲突会浪费你大量排查时间。另一个坑是openaiSDK 版本。OpenAI 官方对 Python SDK 做过几次大升级函数签名和响应对象结构都变过。如果你使用的版本和框架作者当时开发的版本相差太大框架可能需要做一些兼容调整。遇到这种情况最快的方式是去看llm/openai.py的导入和调用位置确认框架实际使用的字段。不要盲目升级 SDK 版本否则可能连锁引发更多不兼容。5.3 记录源码笔记的正确姿势读源码不做笔记等于白读。一周之后你根本想不起当时是怎么理解某个模块的。但笔记不是抄代码我推荐用数据结构变化追踪 调用链记录的方式来做笔记。所谓数据结构变化追踪就是记录消息对象在每一步的形态变化。比如用户输入进来是什么结构模型返回是什么结构工具调用后追加的消息长什么样。这比抄写函数实现有用得多。因为每个模块的任务本质上都是把一种数据结构变成另一种数据结构你理解了数据结构沿着链条如何演化就理解了整个框架的数据流。我还会记录每个核心类的最小结构图只列关键字段和方法名不写实现。比如Agent - __init__(model, tools, ...) - chat(messages, on_event) - _run(messages) - final_message - _execute_tool(call) - result这种笔记的优点是复看成本极低。你不需要重新通读几千行代码只需要看自己的记录就能迅速回忆整个框架的核心脉络。5.4 遇到读不懂的代码怎么办读源码过程中一定会遇到暂时无法理解的代码我的应对有三板斧。第一招搜索测试。框架的测试用例是理解代码语义的最好说明书。测试里的断言告诉你某个函数预期的输入输出。我在理解工具 schema 生成逻辑时就是先看了测试文件才明白它如何处理参数默认值和复杂嵌套类型。第二招看 Git 提交历史。如果某段代码写法很绕极有可能是为了修复某个特殊 bug。去git log -- file看对应文件的提交记录很多时候提交信息里会写明fix: 处理工具返回空字符串的问题这个背景信息能让代码瞬间变得合理。第三招去 issue 里搜索。框架的 issue 列表里往往有使用者讨论过的行为边界问题。这些问题比官方文档更贴近真实场景。比如有人问工具返回的文本太长会不会被截断维护者的回答里经常会透露设计意图。我用这三招解决了很多最初难以理解的代码。说句实话遇到读不明白的地方不用慌这通常不是你的能力问题而是你缺少了某个背景信息。最后分享一个我自己的体会源码阅读是很笨但非常有效的方式。市面上框架更新得太快了今天学完一个框架的用法明天可能就出了替代品。但框架底层的 Agent 循环思维——请求、判断、执行、反馈——是相对稳定的。你把它吃透了换任何框架上手成本都极低。这篇文章记录的是我读 Pi Agent 的第一阶段重点集中在了核心循环、工具调用和上下文管理。下一步我打算深入看它的多 Agent 协作和事件流转机制因为那些部分对构建复杂应用更有挑战。如果你也想动手读框架源码我的建议很简单先跑通最小示例然后在断点里跟着执行路径走一遍。你会发现那些看起来高深莫测的 Agent 框架内部的原理其实并不复杂。