先把结论放在前面：这篇笔记的主角是 Pi Agent 框架的运行时部分，上一篇我把框架的模块边界和入口启动流程捋了一遍，这篇把重点放在“一次任务进来之后，框架内部到底怎么跑的”这个问题上。也就是你把这个框架拿去做二次开发之前，最需要搞懂的那段代码路径。

之所以把这段单独拿出来讲，是因为 Agent 框架和普通业务框架的源码阅读路径差别很大：普通框架你关注的是接口、事务、中间件，而 Agent 框架的难点在运行时的状态流转和工具调用链。很多人在读这类源码时会觉得“类太多了，绕不清楚”，其实就是没抓住运行时这条主线。这篇笔记就是要把这条主线拆开给你看。

1. 先把主链路串一遍：一次任务从进来到落地，中间经过几个环节

Pi Agent 这类框架本质上不是一个算法库，而是一个“执行编排系统”。它不负责替模型思考，它负责让模型想做的事情能够被安全、稳定、可追踪地执行。这和人类的工作方式很像：老板给你派个活，你不会直接冲到打印间狂打一通，而是会先理解需求、拆解步骤、明确分工、然后执行，最后汇总。Pi Agent 的运行时做的就是这件事。

1.1 入口层：请求进来先排队，而不是直接调模型

看源码我习惯先看一个外部请求的“第一落脚点”。Pi Agent 的入口层不是一个简单的 HTTP Handler，而是一个带优先级和超时控制的任务队列。我在源码里看到的是：请求到达后先被包装成一个TaskRequest，这个对象里除了用户的原始输入，还携带了来源渠道、会话 ID、优先级标记、截止时间等元信息。

为什么要在入口做队列而不是直接同步处理？因为 Agent 任务和处理一个普通的 CRUD 请求完全是两码事。一个普通请求你在几百毫秒内就能返回，你可能不需要队列。但一个 Agent 任务可能涉及多轮思考、多次工具调用，耗时可能从几秒到几分钟不等，如果不做流量控制，一旦并发上来，模型服务和下游工具接口会被瞬间打爆。

这个队列实现里有一个让我印象很深的小设计：队列在取出任务时会做一次超时预检，如果任务在队列里等待太久，会被直接标记为“过期丢弃”，根本不会送到模型那边。这个设计避免了模型对一批早已失去时效性的请求做无用功，尤其是像“查询当前设备状态”这类强实时性的任务，过期任务执行了反而会产生误导。

1.2 中间层：先把用户的自然语言“结构化”，再做任务分解

任务从队列里被拿出来之后，并不会立刻丢给大模型去自由回答。Pi Agent 在这中间插了一个“意图解析”阶段。源码中的对应模块叫IntentParser，它负责把用户的自然语言输入转换成一个结构化的任务描述对象。这个转换依赖的是模型输出特定格式的 JSON，框架内部定义了一套固定的输出 Schema。

这套做法非常务实。很多人设计 Agent 时会走“端到端”路线：用户说一句话，模型直接输出最终结果。但 Pi Agent 选择的是“先解析、再规划、再执行”的流水线方式。原因也很简单：可观测性。如果模型直接输出结果，一旦答错了，你根本不知道它是在哪一步想岔的。有了结构化的任务描述之后，每一个环节都能被记录、被回放、被审计。你在排查问题的时候可以直接看到模型当时理解的子任务列表，以及它给每个子任务分配的权重。

任务分解这一步也很有意思。源码里调度层拿到意图对象之后，会把它拆分为一张有向图，节点是子任务，边是依赖关系。这种图状结构与幂等性约束在源码里写得很清晰：只有入度为 0 的子任务可以被立刻调度，依赖未完成的子任务必须等待。相当于框架底层把 Agent 的“规划能力”从模型手里接管了一部分，模型只需要做决策，不需要关心并发依赖、资源分配这些工程问题。

2. AgentRuntime：整个框架的执行引擎是怎么跑起来的

如果说入口层和意图解析层是 Agent 的“大脑皮层”，那AgentRuntime就是它的“脑干”，负责维持生命体征、协调所有器官。这部分源码我读了两遍才彻底看明白，因为它的很多行为是被状态机驱动的，而状态机里又藏了不少约定俗成的“隐性逻辑”，不跟着代码走一遍很容易误解。

2.1 状态机的定义：框架如何硬性约束 Agent 的生命周期

Pi Agent 的运行时核心是一个状态机。源码里对状态的定义并不复杂，我用下面的表来归纳：

这些状态和普通工作流引擎的逻辑看起来很相似，但有一点很关键：Pi Agent 的RUNNING状态内部，Agent 会反复横跳于“模型推理”和“工具调用”两个阶段，可对外表现的状态始终是RUNNING。也就是说，内部再折腾，状态机对外保持一个稳定的高可用接口。这个设计是刻意的，因为下游依赖方（比如定时任务系统、外部调用方）只需要关心最终结果，不需要知道 Agent 中间调了几次模型。

我在阅读源码时特别注意了状态迁移的触发位置。这个状态机的所有迁移都不是在模型代码里触发的，而是由 Runtime 内部的几个TransitionHandler触发的。模型只是一个“决策建议者”，它建议执行某工具或输出某段文本，但真正改变状态的一定是框架的代码。如果你做二次开发的时候让模型直接改了状态，那就绕过了框架最核心的安全约束，这是个很大的坑。

2.2 Runtime 的初始化链条：配置、依赖、组件如何被装配起来

Runtime 的初始化是我建议所有想深入这个框架的人重点研究的第二个地方。我在这部分看到了一个非常典型的“依赖注入 + 插件装配”的架构。核心入口是一个AgentRuntimeBuilder类，它接收配置文件、模型客户端、工具注册表、日志收集器等外部依赖，然后通过链式调用方式完成组装。

这种设计的优势是：测试特别好写。我在给框架写集成测试时，可以很方便地往 Builder 里注入一个 Mock 模型客户端或者 Mock 工具服务，跑一遍完整的执行链路，而不用去依赖真实的模型 API 和外部服务。如果框架把初始化过程写成一坨巨型构造函数，这种可测试性基本就没了。

初始化链里还有一个小细节：Runtime 启动时会执行一次“健康自检”，检查所有注册工具的 connectivity 状态。这个自检是异步的，不会阻塞主线程，但如果某个工具处于断连状态，框架会把该工具的权重降为 0，并且在日志里打一个明显的 WARN 标记。当时看到这里我愣了一下，后来仔细一想，这个设计特别适合生产环境：某个业务接口挂了不应该让整个 Agent 系统挂掉，而是动态地把故障工具从可用集合里摘掉，等它恢复之后再自动加回来。这个思路直接刷新了我对“高可用”这个概念的理解，不是靠熔断，而是靠调度层的自适应决策。

2.3 执行器门面：为什么框架把执行链路又包了一层

在 Runtime 的状态机嵌套之下，Pi Agent 还套了一层“执行器门面”，源码中对应的类是TaskExecutorFacade。一开始我觉得这层有点多余，直接调执行器不就完了？但后来我明白了，这一层解决的是“外部系统依赖”和“核心 Runtime 解耦”的问题。

比如两个 Agent 之间可能有互相调用的需求，也就是 Agent 与 Agent 通信，这在多智能体场景下非常普遍。如果核心 Runtime 直接持有另一个 Agent 的引用，耦合就会很深，一旦对方更新了内部实现，这边可能也要跟着改。门面模式把这种跨 Agent 的调用包装成一个标准动作，底层是同步还是异步、是本进程还是跨网络，调用方完全无感。你在源码里看到大量对ExecutorFacade的调用，几乎可以认为这就是整个运行时对外暴露的“统一总线”。

3. Worker 调度与协作机制：并行执行时如何不乱套

Agent 框架里另一个绕不开的话题是并发。一个复杂的 Agent 任务通常会被拆分成多个子任务，这些子任务如果串行执行，速度会很慢；如果并行执行，又会遇到资源竞争和结果合并的问题。Pi Agent 的 Worker 调度模块给出的答案是“独立 Slot + 统一合并”，这个设计我认为是整个框架里工程水平最高的地方之一。

3.1 Worker 的生命周期与调度策略

源码里对 Worker 的定义是“最小执行单元的执行载体”，每个 Worker 内部持有一个待执行的子任务、一个独立的上下文槽位、以及一个生命周期状态。调度器从就绪队列里取任务，按照“最闲优先”策略分配给空闲 Worker，这个优先级计算不是简单的看数量，而是看当前 Worker 的负载压力。

这套设计让我联想到操作系统的进程调度。Pi Agent 没有采用简单的 FIFO 队列，而是实现了一个最小堆来维护就绪任务集，堆顶是优先级最高或截止时间最近的任务。在源码里我还看到每个 Worker 绑定了一个独立的ContextSlot，子任务在执行过程中产生的所有临时信息都写在自己的槽位里，不会干扰其他 Worker。等到所有关联子任务都完成之后，调度器才会把各个 Slot 的结果拿出来做合并，生成完整的任务输出。

这个“各自干活、最后合并”的模式解决了一个容易踩坑的问题：如果多个执行单元共享同一个上下文对象，一旦出现脏写，你根本无法定位是谁把上下文搞坏的。而独立槽位让每个 Worker 的数据在合并前都是隔离的，排查问题时直接把每个 Slot 单独拿出来回放就行。我当时测试了一个并行任务，故意在一个子任务里往上下文里写了错误数据，最后在合并层一下就看出了问题来源，这种设计对调试太友好了。

3.2 子任务之间的协作协议与依赖约束

子任务之间不是完全孤立的，有些场景存在明确的依赖。我在源码里注意到一个协议对象TaskDependencyGraph，它定义了三种依赖关系：

• MUST_BEFORE：A 必须在 B 之前执行。
• CAN_PARALLEL：A 和 B 可以并行执行。
• WAIT_ANY：A 需要等待 B 或 C 中任意一个完成即可继续。

这套协议在调度器里被实现为一种“阀门机制”。调度器拿到一个子任务时，并不直接把它丢给 Worker，而是先检查它的依赖阀门是否全部打开。如果存在未完成的依赖任务，这个子任务会被放回等待队列，并且触发一个事件通知。依赖完成后节点会向调度器发送事件，调度器重新评估该子任务的可执行状态。

这个机制让我想到一个很常见的业务场景：一个报表生成任务，先要从数据库捞数据，再调用外部接口丰富数据，最后用模板引擎渲染 PDF。这三个步骤不能倒着执行，但第一步和第二步可以并行推进。这种图结构天然适合用 DAG 来建模，Pi Agent 在数据结构和事件通知上的实现可以直接借鉴到其他业务系统里。

3.3 并发安全：为什么不建议在工具回调里写全局状态

再提醒一次：工具执行回调里不要写全局状态。我在给一个工具写回调时，为了图省事直接在回调里更新了一个全局 Map，结果在高并发测试时出现了奇怪的数据串扰。后来排查才发现，Pi Agent 的并行 Worker 共享同一个进程空间，全局变量天然会被所有 Worker 看到。这个框架的正确姿势是使用工具回调里传入的ToolContext，所有的输出都写到这个上下文里，由框架在合并阶段统一取用。

4. 工具调用机制：Agent 的“手”是怎么被正确地接上的

Agent 区别于聊天机器人的核心能力是工具调用。如果说模型是 Agent 的大脑，那工具就是它的手。Pi Agent 的源码里，工具调用机制的实现非常有层次感。从“工具描述”到“参数校验”到“权限控制”再到“结果回填”，每一层都是一道防线。

4.1 工具描述体系：模型如何知道“有什么工具可以用”

最基础的问题是：模型怎么知道当前环境里有哪些工具？Pi Agent 的做法是将所有工具统一抽象为ToolDescriptor对象，包含 name、description、input_schema、lifecycle、security 等字段。在每次请求进入运行时后，框架会把这个请求对应的所有可用工具描述汇聚成一个列表，然后作为系统提示的一部分注入到模型的输入中。

这里有一个很关键的细节：工具描述列表不是所有工具都往上塞，而是按需筛选。Pi Agent 在源码里有一个ToolRegistrySelector组件，负责根据意图解析的结果从注册中心挑选出相关的工具子集。这个设计既节省了模型的上下文窗口，又降低了模型选错工具的概率。如果这个框架把所有工具的描述一次性全塞给模型，那上下文很容易爆炸，而且模型在太多选择面前更容易犯错。

4.2 工具调用的三层防线：参数、权限、结果

我仔细研究过源码中工具调用的执行路径，发现它至少叠加了三层控制：

第一层防线的实现很值得学习。模型在提出工具调用时，输出的是带结构化的 JSON 文本，框架会先用 JSON Schema 校验器做一次严格验证。如果参数缺了必填字段或者类型不对，框架不会强行执行，而是把错误信息转为“工具调用失败，原因是缺少参数 XXX，请补充后重试”的提示回传给模型。这种纠错回路的实质是把模型当成了一个会自我修正的参与者，这在语义上和“直接让整个流程失败”完全不同。

第二层的权限控制让我看到了这个框架在安全性上的认真程度。每个工具可以声明需要的 scope 列表，当一个任务执行工具调用时，框架会检查当前任务的SecurityScope是否覆盖该范围。这个安全检查不是放在工具实现里面的，而是放在了工具调用的通用代理层，这样即使工具实现者忘了做权限控制，框架也能兜底拦住。

4.3 工具回调与 MCP 的适配

在 Pi Agent 的工具注册表里，我注意到它内置了几个适配器，其中有一个是对 MCP 协议的支持。MCP 在工具生态里正在成为标准协议，支持 MCP 意味着任何遵循该协议的服务都可以以统一方式接入框架。适配器的实现思路很直白：把 MCP 服务的工具列表动态拉取并翻译成 Pi Agent 的ToolDescriptor格式，调用时再翻译回 MCP 协议格式。这个翻译层就是工具调用最值得参考的设计模式之一。

不过这里也有个需要谨慎的地方：工具适配器本身不能做太多业务逻辑。我在自己二次开发时曾试图在一个工具适配器里直接拼接复杂的 SQL，发现最后很难调试。后来把 SQL 生成逻辑移到了工具实现内部，适配器只负责参数格式转换，整个链路清晰了很多。

5. 记忆模块与上下文窗口的管理：Agent 的短期工作台和长期储藏室

Agent 如果记不住之前对话的内容，就很难谈得上连续性。Pi Agent 的记忆机制是我这次阅读中收获最大的部分，因为它的设计远比“把所有对话历史都塞给模型”要复杂。

5.1 短期记忆：上下文窗口的分层管理

Pi Agent 的短期记忆实现为一个分层窗口：原始输入、用户画像、中间推理片段、最后的输出草稿分别放在不同的缓存区域。模型真正看到的不是所有内容的机械拼接，而是经过“动态摘要 + 关键片段提取”之后的组合。

源码里对窗口管理有一个重要的参数：context_budget，它决定了当前请求允许的最大上下文 Token 数。当预期 Token 超出预算时，框架不会简单粗暴地截断最早的内容，而是对历史对话做摘要压缩。这个摘要压缩是在接收主任务前异步完成的，不会阻塞主链路。

这其实是很多第一次做 Agent 二次开发的人容易忽略的地方：上下文窗口不是越大越好。几十万 Token 的上下文看起来技术很强，但模型在处理远超其有效注意力范围的内容时，往往会忽略关键信息。Pi Agent 选择“够用但不冗余”的策略，这个思路和我在实际运行中观察到的结果是一致的。

5.2 长期记忆：什么时候写入，什么时候读取

长期记忆的部分，Pi Agent 的实现是目前 Agent 领域比较主流的方式：基于向量存储的语义记忆，在任务结束之后做异步写入。源码判断“这段信息值不值得写入长期记忆”的标准是：它是否包含可复用的知识、是否与当前任务主题强相关、是否涉及风险标记内容。

这套筛选机制非常实用。我最近在做一个“自动生成项目周报”的 Agent，最开始的设计是每个子任务结束后都尝试把内容写进长期记忆，结果向量库里存了大量低质量中间产物，检索时还严重干扰了真正有用的信息。后来我改用 Pi Agent 那种“任务结束时统一评估、只写入高质量信息”的策略之后，检索准确率明显提升。有一个核心心得：长期记忆是给模型用的，不是给你做日志备份用的。如果你想留痕，请用日志系统；长期记忆只存未来还可能有用的知识。

长期记忆的读取也不是简单查最近几条，而是通过查询向量库召回 Top-K 条最相关的历史记录，与当前输入拼接后一起交给模型。在实际测试中我看到，这个 Top-K 的值对输出质量影响很大，K 太大容易引入噪声，K 太小又可能丢掉关键上下文，一般设置为 5 到 8 之间体验比较好。

5.3 记忆操作与模型推理的协同

我再补充一个源码阅读中的细节：Pi Agent 将记忆的读写定义成了几个标准动作，这些动作被注册成了内部工具，模型可以在需要时显式调用它们。也就是说，记忆不是框架为模型自动准备的背景板，而是模型可以主动查询的外部资源。这种设计带来的优势是：模型可以根据当前任务的实际需要决定记忆检索的深度和时机。在多轮对话场景中，这种主动记忆查询比“每轮都塞进去大量历史”要高效得多。

6. 从源码里读到的几点设计哲学与可借鉴之处

这一节抛开具体的类和方法，聊一聊我看完源码后整体感受到的设计思路。如果你也想把一个 Agent 框架做到生产可用，我认为下面这几点很有参考价值。

6.1 框架不做决策，只约束决策的执行路径

Pi Agent 的源码给了一个非常重要的信号：它从来不试图替模型做判断，而是确保模型一旦做了某个判断，后续的执行路径是确定且安全的。比如，模型可以决定“去查询数据库”，但查询数据库的参数构造、操作权限、连接管理，全部由框架接管。这种“智能的部分交给模型，确定性的部分交给框架”的分工方式，我认为是 Agent 框架设计里最核心的哲学。

这也解释了为什么它的状态机如此严格。为了追求灵活性而放松状态约束，会导致 Agent 在运行时出现不可预期的行为，这在生产环境是致命的。我见过有些开源框架为了“让模型自由发挥”，把流程控制完全交给模型，结果做出来的 Agent 像脱缰野马，你根本猜不到它下一步会干什么。Pi Agent 用状态机把行为空间圈在一个合理范围内，这在工程上是更成熟的态度。

6.2 事件驱动带来的可扩展性

除了按需依赖之外，这个框架还大量用了事件驱动。调度器产生的任务状态变化、工具调用产生的生命周期事件、记忆模块的写入事件都会被广播到内部事件总线上。这个机制让日志、审计、指标监控变成了可插拔的组件，而不是硬编码在核心流程里的逻辑。

我试着做了一件事：通过监听任务状态变化事件，给内部管理后台加了一个实时任务看板。整个过程没有改动框架任何核心代码，只是在事件总线上注册了一个新监听器。这个体验让我意识到，设计框架时预留“非侵入式扩展点”的价值有多大。事件总线不只是为了解耦，更多时候是为了让周边的观察类需求不再挤压核心代码。

6.3 配置都是显式的，拒绝魔法值

Pi Agent 的源码里几乎没有魔法值。每个涉及资源大小、超时时间、调用次数的参数都暴露在配置文件中，并且带默认值和注释。对于二次开发的团队来说，这个特征太重要了。我第一次跑通框架时把 Worker 池配置错了，导致任务并发度极低。如果是硬编码，我可能得翻半天代码才能找到原因，但因为有显式配置，只要看归档日志中加载出的配置值，立刻就能发现问题。

7. 读源码过程中踩过的几个坑和排查思路

源码读多了你就会发现，“读懂代码”和“能把它用对、甚至二次开发”之间还有很长的路。这一节把我在 Pi Agent 上踩过的几个坑整理一下，对应的排查思路也一并写上。

7.1 看源码不要从目录结构开始读

我第一次读 Pi Agent 源码时，习惯性地从目录结构开始，想把所有包名和类名都记住。后来发现这是最低效的方式。正确的路径是找一个真实的业务场景，比如“处理一个工具调用”，然后在源码里从头追到尾，沿着调用链把相关的类全部拉出来。目录结构了解个大概即可，那些用不到的模块不会在你的场景里出现，先没有必要花大量时间去抠。

7.2 状态机跳转别只看当前类

状态机的跳转逻辑分散在多个TransitionHandler中，如果你只盯住当前类里面的实现，很容易得出错误结论。我的经验是，拿到状态机定义之后，先画一张完整的状态流转表，标出每个状态上挂哪些 Handler、由哪些事件触发迁移。我在第二次阅读时手写了这张表，几乎把大半的框架逻辑都串起来了，后来做调试时这张表成了我最重要的参考文档。

7.3 工具执行超时参数要单独设置

很多 Agent 任务在工具调用时并不是模型本身慢，而是工具执行很慢。如果一个 Agent 被设计成先查询多个接口再汇总，那么每个工具调用的超时不能设置得太小。实际上我在测试中发现，工具超时设成 3 秒时，任务经常因为某个外部服务响应慢而中断；调整到 10 秒后，服务基本稳定了。但这个超时也不应该全局统一，因为不同的工具有不同的响应特性。Pi Agent 允许按工具级别设置超时时间，在二次开发时一定要把这个参数用好。

7.4 日志拉链不要轻易关掉

Pi Agent 的日志系统是贯穿全链路的，从任务进入队列，到意图解析结果、再到每次工具调用的参数和返回值，都有结构化日志记录。在开发自测的时候可能觉得日志太啰嗦，但到了问题排查阶段，你才意识到这些日志有多重要。我遇到过一个诡异的情况：任务中途失败但错误信息不明确，后来翻日志发现是模型在一次工具调用中返回了超出预设长度的输出，导致模型响应解析器直接截断并报错。这种情况如果没有中间日志，几乎无法定位。所以我建议你在二次开发时，保持日志链路完整，尤其是模型输入输出和工具调用参数这两项，不要因为嫌量大数据大就随意丢弃。

最后分享一个小技巧

读 Agent 框架源码，比读普通框架更看重“跑起来”。你先跑通一个最小业务场景，然后在业务不变的情况下逐行打断点去看框架内部的执行过程，这种“带着真实数据去读源码”的方式比纯静态阅读高效很多。我自己读 Pi Agent 时是先让它跑一个包含两次工具调用的简单任务，然后跟着断点走了一遍主链路，再回来做知识归纳，整个脉络基本就刻在脑子里了。

我个人的习惯是：每次拿到一个框架，先强迫自己写出它核心链路十个关键类的名字和职责，写不出来就说明还没吃透，再回去读一遍。这套方法对所有源码阅读类工作都适用。希望这份笔记能帮你省下一些走弯路的时间。