1. 从一次工具调用超时说起Pi Agent 为什么要给 MCP 做三种模式上周帮朋友排查一个 Pi Agent 的线上问题现象很典型Agent 在调用某个 MCP 工具时卡了整整 40 秒最后超时返回用户侧看到的就是一句冷冰冰的工具执行失败。翻日志发现这个工具其实只需要读一个本地配置文件理论上 200 毫秒就能返回但它走的是默认的同步阻塞链路中间还夹着一层网络往返。问题不在工具本身而在工具被挂载到 Agent 上的方式。这件事让我重新审视了 Pi Agent 把 MCP 加进核心之后引入的那套工具模式设计。很多人第一次看到direct、deferred这些词的时候第一反应是这不就是懒加载吗但实际用下来会发现这三种模式解决的根本不是同一个问题。它们分别对应了工具调用生命周期里的三个不同阶段发现、绑定、执行。搞混了这三个阶段就会出现我朋友那种明明很简单的工具却慢得离谱的情况。先把结论摆在这儿Pi Agent 把 MCP 纳入核心之后工具模式大致分成三类——direct直接模式、deferred延迟模式以及介于两者之间的混合/按需模式。这三种模式的差别不在于功能能不能用而在于工具在什么时机被加载、被谁持有、以及调用时走哪条路径。选错了模式轻则响应变慢重则整个 Agent 的上下文被工具描述撑爆。这篇文章适合三类人看一是正在用 Pi Agent 接 MCP 工具、但被模式选择搞晕的开发者二是想把现有 MCP 服务迁移进 Pi Agent 核心的团队三是单纯想搞明白工具模式这个词到底在说什么的技术爱好者。我会把每种模式的适用场景、底层逻辑、实操配置和踩坑经验都摊开讲尽量让你看完就能对着自己的项目做判断。2. 三种工具模式的核心差异拆解2.1 direct 模式工具描述常驻调用路径最短direct 模式的逻辑最直白Agent 启动的时候把所有 MCP 工具的描述name、description、input schema一次性拉进上下文之后每次调用都直接命中已经绑定好的工具实例。你可以把它理解成开机就把所有工具箱搬到工作台上用的时候伸手就够得着。这种模式最大的优势是调用延迟最低。因为工具描述已经在上下文里了模型在规划阶段就能直接看到工具签名不需要额外的发现步骤。对于高频调用、参数结构稳定的工具direct 模式几乎是唯一合理的选择。比如一个专门做时间戳转换的 MCP 工具或者一个查询内部用户信息的工具这类工具在整个会话里可能被调用几十次每次省下几百毫秒的发现开销累积起来就很可观。但 direct 模式的代价也很明显上下文占用是固定的、前置的。假设你接了 30 个 MCP 工具每个工具的描述加 schema 平均 200 token那就是 6000 token 常驻在上下文里。这 6000 token 不管你这次会话用不用得上都得占着。对于上下文窗口本来就紧张的模型来说这是实打实的浪费。我见过一个项目接了 50 多个工具光工具描述就吃掉了将近 1 万 token导致真正留给对话历史的空间被严重压缩。所以 direct 模式的适用边界很清楚工具数量少建议 10 个以内、调用频率高、描述精简。超过这个范围就该考虑 deferred 了。2.2 deferred 模式按需加载用空间换时间deferred 模式走的是另一条路Agent 启动时不加载任何工具描述只保留一个工具目录的索引。当模型判断需要某个能力时先通过一次轻量的检索或匹配把相关工具的描述动态注入上下文然后再执行调用。这个设计思路其实和数据库的索引很像。你不会把整张表加载到内存里而是先查索引定位到行再回表取数据。deferred 模式就是给工具集建了个索引用的时候才回表。它的好处是上下文占用是动态的、后置的。50 个工具在 deferred 模式下启动时可能只占几百 token 的索引开销只有真正被调用的那两三个工具才会把完整描述加载进来。对于工具数量多、但单次会话只用到少数几个的场景这种模式能省下大量上下文空间。代价则是多了一次发现步骤。每次调用前都要先做一次工具匹配这个匹配可能是基于关键词的也可能是基于向量检索的无论哪种都比 direct 模式多一个环节。如果匹配逻辑写得不好还可能出现该调的工具没匹配上的尴尬情况。我实测下来deferred 模式的单次调用延迟通常比 direct 高 100 到 500 毫秒具体取决于检索实现。2.3 混合模式把选择权交给运行时混合模式不是第三种独立的加载策略而是允许在同一个 Agent 实例里对不同工具采用不同模式。比如把高频的核心工具设为 direct把长尾的、低频的工具设为 deferred。Pi Agent 把 MCP 加进核心之后这套混合能力是内置的你可以在工具注册的时候逐个指定模式。这种做法的价值在于精细化的资源分配。一个典型的 Agent 可能同时具备查询天气高频direct、发送邮件中频direct、生成 PDF 报表低频deferred、调用内部审批流低频deferred。把前两个设为 direct 保证响应速度后两个设为 deferred 节省上下文整体达到一个平衡。下面这张表把三种模式的关键差异列清楚方便你对照自己的场景做判断维度direct 模式deferred 模式混合模式工具描述加载时机Agent 启动时全量加载调用前按需加载按工具逐个配置上下文占用固定、前置、较高动态、后置、较低介于两者之间单次调用延迟最低较高多一次发现取决于该工具的模式适用工具数量少10 个以内多几十上百任意实现复杂度低中需检索逻辑中高需配置管理典型场景高频核心工具长尾低频工具真实生产环境2.4 为什么不是越懒越好模式选择的本质是权衡很多人有个直觉deferred 既然省上下文那全用 deferred 不就行了这个想法我一开始也有但实测下来会踩坑。问题出在发现步骤的可靠性上。deferred 模式依赖一次工具匹配而匹配本身是有误差的。如果模型在规划阶段没能准确描述出它需要什么能力检索就可能漏掉正确的工具。direct 模式没有这个问题因为所有工具都摆在明面上模型自己就能看到哪个合适。所以模式选择的本质是在上下文成本和发现可靠性之间做权衡。高频、关键路径上的工具宁可多占点上下文也要保证 direct 的可靠性长尾、容错性高的工具用 deferred 省空间更划算。这个判断没有标准答案得结合你的具体工具集和调用分布来定。3. 底层机制MCP 工具在 Pi Agent 里是怎么被挂载的3.1 MCP 协议本身只定义了能力没定义加载策略要理解 Pi Agent 的三种模式得先搞清楚 MCP 协议本身管什么、不管什么。MCPModel Context Protocol定义的是工具如何被描述、如何被调用、结果如何返回这一套通信规范。它规定了tools/list用来列出工具tools/call用来执行工具但它没有规定这些工具应该在什么时机被加载进模型上下文。这个空白正是 Pi Agent 三种模式发挥作用的地方。MCP 负责工具长什么样、怎么调Pi Agent 负责工具什么时候进上下文、以什么方式进。两者是分层的关系MCP 是能力层工具模式是调度层。理解这一点很关键因为它意味着工具模式是 Pi Agent 的实现选择不是 MCP 的强制要求。你在别的 Agent 框架里可能看到不同的模式命名但底层要解决的问题是一样的。3.2 direct 模式的绑定过程direct 模式的绑定发生在 Agent 初始化阶段大致流程是这样的Agent 启动读取配置里标记为 direct 的 MCP 服务列表对每个服务发起tools/list请求拿到完整工具清单把工具描述转换成模型能理解的格式通常是 JSON Schema 加自然语言描述把这些描述拼接到系统提示或工具定义区完成绑定后续调用直接走tools/call不再有发现步骤这个流程里有个容易被忽略的细节第 2 步的tools/list是启动时同步执行的。如果某个 MCP 服务响应慢整个 Agent 的启动就会被拖住。我遇到过启动要等 8 秒的情况就是因为其中一个 direct 工具的服务端在做冷启动。所以 direct 模式对 MCP 服务的启动速度是有要求的服务端最好能快速响应tools/list。3.3 deferred 模式的检索与注入deferred 模式的流程复杂一些核心在于检索这一步怎么实现。常见的有两种做法基于关键词的检索把工具名和描述做分词建立倒排索引调用时用模型输出的意图关键词去匹配。实现简单但对同义表达的鲁棒性差。比如用户说帮我看看明天热不热工具描述里写的是查询气温关键词匹配可能就漏了。基于向量检索把工具描述做 embedding调用时把模型意图也做 embedding算相似度取 top-k。鲁棒性好但需要额外的 embedding 服务和向量存储实现成本高。Pi Agent 核心内置的 deferred 实现据我观察更偏向第一种但留了扩展点让你接入自己的检索逻辑。实际项目里如果你的工具命名规范、描述清晰关键词检索其实够用了如果工具描述比较随意那向量检索的收益会明显一些。检索到候选工具后deferred 模式会把它们的完整描述注入当前轮的上下文然后模型再基于这些描述决定调哪个。注意这里有个两阶段决策先决定我需要哪类能力再决定具体调哪个工具。direct 模式只有后一阶段。3.4 混合模式的配置管理混合模式的复杂度主要在配置管理上。你需要维护一张工具到模式的映射表并且在 Agent 启动时按这张表分别处理。Pi Agent 的做法是在工具注册接口里加一个mode字段取值direct或deferred不填则走默认值。这里有个实践中的坑同一个 MCP 服务下的不同工具可以配不同的模式吗答案是可以但要小心。因为tools/list是按服务粒度请求的如果你把一个服务里的工具 A 设为 direct、工具 B 设为 deferred那启动时你还是得把这个服务的工具列表全拉一遍只是 B 的描述不注入上下文而已。这省的是上下文不是网络请求。所以更彻底的做法是按服务粒度划分模式把高频服务整体设为 direct低频服务整体设为 deferred。4. 实操在 Pi Agent 里配置三种模式的完整流程4.1 环境准备与 MCP 服务接入假设你已经有一个跑起来的 Pi Agent 实例现在要接入两个 MCP 服务一个是内部的用户信息查询服务高频一个是报表生成服务低频。先确认你的 Pi Agent 版本支持 MCP 核心集成这个能力是在较新的版本里才进核心的老版本可能需要单独装插件。接入 MCP 服务的基本配置长这样以常见的配置文件形式为例{ mcpServers: { user-info: { command: node, args: [./servers/user-info/index.js], mode: direct }, report-gen: { command: python, args: [./servers/report-gen/main.py], mode: deferred } } }注意mode字段就是 Pi Agent 加进核心之后新增的配置项。不写的话走默认值默认值通常是direct但这个默认值在不同版本里可能变过建议显式写清楚别依赖默认。4.2 direct 模式的配置要点与验证配好之后启动 Agent观察启动日志。direct 模式的工具应该在启动阶段就完成tools/list并注入上下文。你可以通过一个简单的验证方法确认在对话里直接问 Agent你有哪些工具可用如果 direct 工具被正确加载Agent 应该能列出它们的名字。direct 模式配置时有几个参数值得关注启动超时tools/list的等待时间默认可能是 5 秒。如果你的 MCP 服务启动慢需要调大但调大意味着 Agent 启动变慢权衡着来。描述精简direct 工具的描述建议控制在 100 token 以内。描述越长常驻上下文占用越大。把详细说明放到工具的参数描述里而不是工具本身的 description 里。schema 收敛input schema 里不要放太多可选参数每个参数都会增加 token。能用枚举就别用自由字符串。我实测过一个对比同一个工具描述写 50 token 和写 200 token在 20 个 direct 工具的场景下上下文占用差了 3000 token。这个差距在长会话里会明显影响可用轮数。4.3 deferred 模式的检索配置与调优deferred 模式的配置重点在检索环节。Pi Agent 核心提供了一套默认的关键词检索但你可以通过配置调整匹配策略{ mcpServers: { report-gen: { command: python, args: [./servers/report-gen/main.py], mode: deferred, retrieval: { strategy: keyword, topK: 3, minScore: 0.3 } } } }topK是每次检索返回的候选工具数量minScore是匹配分数阈值。这两个参数直接影响 deferred 模式的表现topK太小可能漏掉正确工具太大注入的上下文又变多失去 deferred 的意义。一般 3 到 5 比较合适。minScore太高匹配过于严格容易漏太低会引入不相关的工具干扰模型判断。0.3 是个常见的起点具体得根据你的工具描述质量调。调优的方法论是准备一批真实的用户意图样本跑一遍检索看正确工具是否稳定出现在 topK 里。如果经常漏先检查工具描述是不是写得太抽象再考虑调低 minScore 或换向量检索。4.4 混合模式的落地一张配置表管到底真实项目里我建议直接上混合模式按下面这张思路表来分配工具类型调用频率推荐模式理由身份/权限查询每轮几乎都调direct高频延迟敏感时间/日期工具高频direct描述极短占用可忽略业务数据查询中频direct关键路径可靠性优先报表/导出低频deferred描述长用得少第三方集成低频deferred数量多长尾实验性工具极低deferred不值得占常驻上下文按这张表配下来通常能把常驻上下文控制在合理范围同时保证关键路径的响应速度。我手上一个接了 40 多个工具的项目用混合模式之后常驻工具描述从 9000 token 降到了 2500 token 左右而高频工具的调用延迟没有变化。5. 踩坑实录三种模式最容易出问题的地方5.1 direct 模式上下文被工具描述悄悄吃光这是最常见的坑而且很隐蔽。因为工具描述是启动时注入的你不会在对话过程中感知到它的存在直到某天发现怎么聊了几轮就提示上下文超限了。排查方法在 Agent 启动后打印一次完整的系统提示或工具定义区数一下工具描述占了多少 token。如果超过总窗口的 20%就该考虑把部分工具迁到 deferred 了。另一个相关的坑是工具描述里的示例代码。有些开发者喜欢在工具 description 里塞一大段使用示例觉得这样模型更容易理解。但这段示例是常驻的每个 direct 工具都塞一段累积起来非常可观。我的建议是示例放在参数描述里或者干脆不放靠清晰的参数命名让模型自己推断。5.2 deferred 模式该调的工具没被检索到deferred 模式最典型的故障就是工具明明存在但 Agent 说它没有这个能力。根因通常是检索没匹配上。排查思路分三步第一确认工具确实注册成功了可以手动触发一次tools/list看返回第二看检索日志确认模型输出的意图关键词是什么和工具描述的匹配分数是多少第三如果分数确实低要么改工具描述让它更容易被匹配要么调低 minScore。我遇到过一个案例工具叫generate_monthly_report描述写的是生成月度报表。用户说帮我出一下上个月的经营分析关键词匹配里经营分析和月度报表没有重叠词分数很低没匹配上。后来在描述里补了一句也用于经营分析、业绩汇总等场景问题就解决了。deferred 模式下工具描述不只是给模型看的也是给检索器看的得兼顾两者的理解习惯。5.3 混合模式模式切换后的缓存不一致混合模式因为同时存在两种加载路径容易出现缓存层面的不一致。具体表现是某个工具从 direct 改成 deferred 之后Agent 行为没有立即变化还在用旧的加载方式。这通常是因为 Agent 有工具描述的缓存机制。改配置之后需要清缓存并重启不能只热重载配置。Pi Agent 核心在这块的处理是启动时构建工具注册表运行时不动态变更所以改模式必须重启。这一点在文档里不一定写得很显眼但实操中必须记住。5.4 一张速查表收尾常见问题现象可能原因排查方向解决方式启动特别慢direct 服务tools/list慢看启动日志各服务耗时调大超时或改 deferred上下文很快超限direct 工具描述过多统计工具描述 token 占比迁移部分工具到 deferred工具调不到deferred 检索未命中看检索日志匹配分数改描述或调低 minScore改模式不生效缓存未清确认是否重启清缓存后重启调用偶发超时工具执行本身慢看tools/call耗时与模式无关优化工具实现6. 我的选择建议什么场景用哪种模式6.1 小工具集、高频调用无脑 direct如果你的 Agent 总共就接五六个工具而且都是高频调用的核心能力别犹豫全上 direct。这个规模下上下文占用完全可控deferred 带来的那点空间节省不值得你多维护一套检索逻辑。简单直接出问题的概率也最低。6.2 大工具集、调用分散deferred 为主关键工具 direct工具数量上了二三十个调用又比较分散这时候 deferred 是主力。但别全 deferred把其中调用最频繁、最不能出错的那几个拎出来设成 direct。这个关键少数通常不超过 5 个但它们决定了 Agent 的基础体验。6.3 不确定的时候先 direct观察后再迁如果你对工具的调用分布还没摸清楚我的建议是先全 direct 上线同时埋点统计每个工具的调用次数。跑一两周之后把调用次数排在后 50% 的工具迁到 deferred。这样迁移是有数据支撑的不会拍脑袋。这个渐进式的方法比一上来就搞复杂配置要稳得多。我见过太多项目在还没搞清楚工具使用情况的时候就上了复杂的混合配置结果调优调了半天收益还不如先把工具描述精简一遍。6.4 一个容易被忽略的维度工具描述的稳定性除了调用频率工具描述的变更频率也影响模式选择。direct 工具的描述是启动时加载的改了描述必须重启 Agent 才生效。如果你的某个工具描述还在频繁迭代把它放 deferred 会更灵活因为 deferred 是调用时加载改完描述下次调用就能生效不用重启。这个维度在选型时经常被忽略但在快速迭代阶段很实用。等工具描述稳定了再考虑迁到 direct 优化延迟。7. 关于 MCP 工具模式我踩过之后想说的几句回到开头那个 40 秒超时的案例。最后查出来的原因是那个读本地配置的工具被设成了 direct但它所在的 MCP 服务启动时要做一次远程鉴权鉴权服务当时在抖动导致tools/list卡住进而拖慢了整个 Agent 的启动和首次调用。解决方案很简单——把这个工具迁到 deferred让它的加载和 Agent 启动解耦同时给鉴权加了本地缓存。改完之后Agent 启动从 8 秒降到 1 秒出头工具调用也回到了 200 毫秒级别。这件事让我更确信一个判断工具模式的选择本质上是在管理加载时机和故障传播路径。direct 模式把工具的加载绑在了 Agent 启动上好处是调用快坏处是工具的启动问题会传染给整个 Agent。deferred 模式把加载推迟到调用时隔离了启动故障代价是每次调用多一步。混合模式让你可以按工具的重要性分别决定把关键路径和长尾路径分开管理。如果你现在正在给 Pi Agent 接 MCP 工具我的建议是先把工具清单列出来标上调用频率和描述长度然后按第 4 节那张表过一遍。别一上来就追求最优配置先跑起来用真实数据驱动调整。工具模式这东西没有放之四海皆准的答案只有贴合你场景的答案。
