Agent ToolCall 循环怎么定制？PI Extension 与 DeepAgents Middleware 两条岔路深度对比

当你想给 Agent 的 tool_call 循环挂自定义逻辑——拦截、改写、重试、注入工具——会发现两个明星框架选了两条互不重合的范式：PI 用"事件订阅"，DeepAgents 用"中间件洋葱"。这篇把它们放在一起对比，告诉你根因在哪、各自的天花板在哪、你的项目该选哪种。

导语：同一个 Loop，两套范式

Agent 的核心循环长这样：

用户输入 → 构造 Prompt → 调 LLM → 拿到 ToolCall → 执行 Tool → 把结果回灌给 LLM → 再来一轮

无论 PI（@earendil-works/pi-coding-agent）还是 DeepAgents（langchain-ai/deepagents），它们的 agent loop 形态完全一样。但当你想"在 tool_call 这段挂点自己的逻辑"时，两边的 API 长得完全不同：

• • PI：pi.on("tool_call", handler)——熟悉的 EventEmitter 写法。
• • DeepAgents：def wrap_tool_call(self, request, handler)——熟悉的 Koa 中间件写法。

差别不在"能不能做"，而在"开放定制的范式"。这篇就把这条岔路一次讲清楚。

一、Agent ToolCall 循环：从一张图说起

1.1 共有的循环骨架

不管哪个框架，主循环都是固定的几个节点：User Input → Build Prompt → LLM Call → Tool Call → Tool Result → 回到 LLM Call，循环到模型 emit stop 为止。

用户的所有定制需求，本质上都落在每个节点的"前后"。

1.2 聚焦 tool_call：8 类典型诉求

把目光放到 tool_call 这一段，你会看到 8 类几乎所有 Agent 工程都会遇到的需求：

两个框架都能覆盖这 8 类——差别在"用什么形状的 API 让用户写出来"。

二、PI Extension：事件订阅式插件

2.1 心智模型：宿主 emit，插件 on

PI 把 agent loop 上所有关键时机做成命名事件：tool_call、tool_result、before_agent_start、context、before_provider_request …

插件用 pi.on("event_name", handler) 订阅。宿主在主循环跑到对应时机，按既定策略（fire-and-forget / bail / waterfall）串行派发：

• • tool_call：bail 策略——任一插件返回 {block: true} 立即短路，拒绝执行。
• • tool_result：waterfall 策略——上一个插件的输出作为下一个的输入，链式改写。
• • tool_execution_*：fire-and-forget——只为埋点、UI 更新，不影响主流程。

2.2 tool_call 上的钩子表面

2.3 代码：在 PI 里拦 bash 工具 + 脱敏（约 18 行 TS）

// ~/.pi/agent/extensions/safety.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // 1) 调用前拦截 — bail 语义
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "User denied" };
    }
  });

  // 2) 结果回灌前脱敏 — waterfall 语义
  pi.on("tool_result", async (event) => {
    const redacted = event.content.map(c =>
      c.type === "text"
        ? { ...c, text: c.text.replace(/sk-[a-z0-9]+/gi, "sk-***") }
        : c
    );
    return { content: redacted };
  });
}

关键点：tool_call 与 tool_result 是两个独立的事件名，分别有不同的派发策略。"前"和"后"的拆分由框架硬编码，你只能选时机、不能改派发语义。

三、DeepAgents Middleware：洋葱式中间件

3.1 心智模型：包住 handler，自己决定调不调

DeepAgents 借用了 langchain.agents.middleware.AgentMiddleware 基类。每个 middleware 是一个 Python 类，通过覆盖 wrap_tool_call(request, handler) 这样的方法接入主循环。

多个 middleware 按 list 顺序嵌成洋葱——每一层显式决定要不要、要几次地调 handler(request)：

• • 不调 handler → 短路（拦截）
• • 调一次 handler → 常规执行
• • 调多次 handler → 重试 / A-B 比较
• • try / except 包住 handler → fallback
• • handler 前后改 request/response → 改参数 / 改结果

3.2 tool_call 上的钩子表面

3.3 代码：等价的 bash 拦截 + 脱敏（约 22 行 Python）

# my_safety_middleware.py
from typing import Callable
from langchain.agents.middleware import AgentMiddleware
from langchain.tools.tool_node import ToolCallRequest
from langchain_core.messages import ToolMessage
from langgraph.types import Command, interrupt


class SafetyMiddleware(AgentMiddleware):
    def wrap_tool_call(
        self,
        request: ToolCallRequest,
        handler: Callable[[ToolCallRequest], ToolMessage | Command],
    ) -> ToolMessage | Command:
        call = request.tool_call

        # 1) 调用前拦截 — 不调 handler 即 short-circuit
        if call["name"] == "bash" and "rm -rf" in call["args"].get("command", ""):
            ok = interrupt({"prompt": "Allow rm -rf?"})
            if not ok:
                return ToolMessage(
                    content="Blocked by SafetyMiddleware",
                    name=call["name"], tool_call_id=call["id"], status="error",
                )

        # 2) 真实执行
        result = handler(request)

        # 3) 结果回灌前脱敏
        if isinstance(result, ToolMessage) and isinstance(result.content, str):
            result.content = redact_secrets(result.content)
        return result

关键点：拦截 / 改写 / 重试 / fallback 全部在一个方法里表达，靠"调不调 handler()、调几次、改 request 还是改 response"来区分语义。多个 middleware 自动嵌成洋葱（list 顺序 = 由外到内）。

四、把同一个需求写两遍：体感对比

光看 API 表面还不够。我们换一个稍微复杂的真实需求体感一下：

需求：给 bash 工具加 3 次重试，每次失败 sleep 1 秒；如果最后还是失败、且命令包含 git，自动 fallback 到本地 subprocess.run(['git', 'status']) 给一个兜底输出。

DeepAgents 写起来很自然

class GitRetryMiddleware(AgentMiddleware):
    def wrap_tool_call(self, request, handler):
        if request.tool_call["name"] != "bash":
            return handler(request)

        last_err = None
        for _ in range(3):
            try:
                return handler(request)
            except Exception as e:
                last_err = e
                time.sleep(1)

        if "git" in request.tool_call["args"].get("command", ""):
            out = subprocess.run(["git", "status"], capture_output=True, text=True)
            return ToolMessage(
                content=out.stdout, name="bash",
                tool_call_id=request.tool_call["id"],
            )
        raise last_err

"调几次 handler" 在洋葱模型里就是一个普通的 for 循环，自然到不需要思考。

PI 写起来非常违和

PI 的 on("tool_call", ...) 钩子的语义是"通知插件 LLM 要调用 tool 了"，它不是执行点。插件这里没有"重跑 tool"的入口（emitToolCall 是 hook，不是 exec）。

所以 PI 上要做这个需求，你只剩两条路：

1. 1. 放弃 PI 的 emit 机制，新写一个工具 bash_with_retry 完全替代 bash，把重试 / fallback 逻辑塞进新 tool 内部；
2. 2. fork PI core，自己改 AgentSession 里 tool 执行的那一段代码。

结论：「重试 / fallback / 多次调用」不是 PI 缺 feature，而是范式天花板。事件订阅模型天生只能描述"在某时机做某事"，描述不了"包住某次执行"。

五、逐项对比：核心 8 维

一句话总结这张表

PI 把"在哪儿插"做成了 API（命名事件）；DeepAgents 把"怎么插"做成了 API（包 handler 的方法）。

六、各自的优劣分析

PI Extension

优势

• • 心智成本低：pi.on("tool_call", fn) 就是"装个监听器"，前端工程师 5 分钟上手。
• • 热加载：把文件丢进 ~/.pi/agent/extensions/，/reload 立即生效。
• • 一文件一切：events + tools + commands + UI + theme 都能塞同一个文件。
• • UI 一等公民：ctx.ui.confirm/custom/setFooter/... 直接接 TUI，做"问一下用户"非常顺手。
• • 错误天然隔离：handler 抛错只产生 diagnostic，主流程不挂。

劣势

• • 派发策略硬编码：bail / waterfall / fire-and-forget 由框架决定，你想"在 tool_call 上也走 waterfall"？做不到。
• • 前后人为割裂：要同时拦前和改后，得写两个 on，自己用闭包/Map 串联状态。
• • 不擅长重试：没有"调 handler 多次"的概念，重试要自己包一层。
• • 组合性弱：两个 extension 想"先脱敏再截断"，顺序由加载顺序决定，不容易显式编排。

DeepAgents Middleware

优势

• • 一处搞定前后：wrap_tool_call 同时表达 before/after/around，天然支持重试、cache、fallback、circuit-breaker。
• • 组合显式：middleware=[A, B, C] 即洋葱由外到内，谁先谁后一目了然。
• • 状态托管：借 LangGraph 的 state + checkpointer，跨步骤状态、断点续跑、time-travel debug 直接可用。
• • 子代理一等公民：SubAgentMiddleware / AsyncSubAgentMiddleware 把多代理、远程执行做成内置能力。
• • 生态对齐：所有 middleware 都能跑在 LangGraph / LangSmith / LangChain Studio，自带 trace、replay、debug。

劣势

• • 心智门槛高：要懂 LangGraph 状态机、洋葱模型、Channel/Reducer 才能写出正确的 middleware。
• • UI 不在 SDK 里：弹窗 / 进度条 / 主题要到 CLI 包（Textual）里去写，SDK 层只有 interrupt() 这种抽象 HITL 信号。
• • 调试栈深：错误堆栈穿透 LangGraph 多个节点 + 多层 middleware，定位问题比 PI 的 emit 路径费劲。
• • 无内置热加载：middleware 是 Python 类，改完得重启进程。
• • 分发重：标准路径是发 PyPI，不像 PI 一个文件 scp 过去就能用。

七、为什么各自选这条路？根因在"宿主形态"

这是这次对比里最值得记一笔的观察：

扩展机制不是独立设计选项，而是被"宿主长什么样"反推出来的。

PI 选 Extension 的根因

PI 的宿主是 AgentSession——一个写死流程的 TypeScript 类，循环展开成顺序代码。在这种宿主上开放定制，最自然的方式就是「在关键时机喊一嗓子让插件知道」——也就是 EventEmitter 风格的命名事件。它根本没有"重新编排循环"的可能，所以 bail / waterfall 这种合并策略只能由宿主硬编码。

PI 沿袭的范式都是事件订阅系：

• • Node EventEmitter
• • Fastify hooks（onRequest / preHandler）
• • Hapi.js server.ext()
• • Probot app.on("issues.opened")
• • VSCode 扩展 context.subscriptions.push(workspace.onDidSaveTextDocument(...))

DeepAgents 选 Middleware 的根因

DeepAgents 的宿主是 LangGraph StateGraph——agent loop 是一张运行时编译的图，每个 middleware 编译进图节点。在这种宿主上开放定制，最自然的方式就是「让你的 middleware 也成为图的一部分」——也就是 Koa 风格的洋葱包装。handler 是 LangGraph 给你的"下一个节点"，你可以选不调（短路）、多调（重试）、并行调（fork-join），都还在图模型里。

DeepAgents 沿袭的范式都是中间件链系：

• • Connect / Express / Koa middleware
• • Django middleware
• • Webpack tapable AsyncSeriesWaterfallHook
• • Rollup 插件 transform hook
• • LangChain v0 CallbackHandler

这不是哪边更先进，是哪边更顺手

PI 的开发者大概率来自前端 / 工具链 / VSCode 扩展圈，自然写出事件订阅；DeepAgents 的开发者来自 LangChain / Python 后端圈，自然写出中间件。

底座一旦选定，扩展模型几乎就被锁死。

事件驱动 → 用命名事件订阅；图驱动 → 用节点中间件。

八、该选哪种？决策矩阵

一句话判据

优先级三条建议

1. 1. 场景驱动选型，不要先选框架再迁就业务。判据见上表，一句话版本：「我在某个固定时机插一段」→ Extension；「我要包住某段执行，能不调或多次调」→ Middleware。
2. 2. 如果团队走 Python + 生产服务：默认 DeepAgents。需要的不只是 tool_call 定制，还有 checkpoint、replay、trace、子代理这些只有 LangGraph 系才能开箱给你的能力。
3. 3. 如果是 TypeScript 单兵 / Coding Agent CLI 二开：默认 PI。把 .ts extension 放进 ~/.pi/agent/extensions/ 即用，/reload 调试节奏快。一旦发现自己在写"重试包一层"或"多 middleware 显式编排"的代码，再考虑迁移。

演进路径建议

• • 从 PI 起步、未来可能迁 DeepAgents 的项目：保持 extension 的"单一职责"——一个文件管一件事，避免 mutate state 跨多个事件；将来翻成 middleware 类时成本最低。
• • 从 DeepAgents 起步、缺 UI 的项目：把 UI 层独立做（Textual / Web），通过 LangGraph 的 interrupt 把 HITL 信号传出去，避免把 UI 逻辑塞进 middleware。
• • 既要 PI 的 UI 又要 DeepAgents 的组合表达力：可考虑把 DeepAgents 当 backend（Python 服务），PI 当 frontend harness（CLI），通过 ACP / 自定义 RPC 衔接。

九、结论：一句话浓缩

PI 把"在哪儿插"做成了 API（命名事件）；DeepAgents 把"怎么插"做成了 API（包 handler 的方法）。 前者强在低门槛 + UI 直觉 + 热加载，是单兵作战工具的最优解； 后者强在组合表达 + 平台化 + 可观测，是构建产品级 Agent 平台的最优解。

两者并非互斥——它们其实展示了"Node 生态 vs Python 后端生态"在 Agent 这个新场景下的两条惯性路径：

• • 从 VSCode / Fastify / Probot 走出来的人，自然会写出 PI 风格的事件总线；
• • 从 Django / Koa / LangChain Callbacks 走出来的人，自然会写出 DeepAgents 风格的中间件栈。

当你要做"定制 tool_call 循环"这件事时，记住一个判断标准：

• • "我要在某个固定时机干件事" → 事件模型更顺；
• • "我要包住某个执行，并能选择性地多次/不调它" → 中间件模型更顺。

这条标准比"哪个框架更好"靠谱得多——它直接决定了你接下来要写多少胶水代码。

延伸阅读

涉及代码版本：

• • PI f2b105dd（@earendil-works/pi-coding-agent）
• • DeepAgents 2ac7d415（langchain-ai/deepagents）
• • LangChain v1 d0d78f1aeb（DeepAgents middleware 基类来源）

外部参照范式：

• • Webpack tapable
• • Fastify Hooks
• • VSCode Extension API
• • Koa middleware（洋葱模型）