演示 23 · 图编译循环与 Hook 链（编译期确定

🏗 图编译循环架构 —— 点组件看职责；播放 ⚡光点沿图流动

⏺ STARTentryNode 循环入口

▼

① beforeAgent Hook 链日志/权限前置（每轮前）

▼

② beforeModel Hook 链loopEntryNode 汇聚点 · 工具注入

▼

🤖 AGENT_MODEL · LLM 调用读 messages 返回 text / tool_calls

▼

③ afterModel Hook 链（反向）洋葱模型 · 最后注册最先看到 raw

▼

⚖️ 条件路由 makeModelToTools()loopExitNode · jump_to→tool→end→model

🔄 有 tool_calls → 工具执行 → 回 beforeModel（第②节点）继续循环

④ AGENT_TOOL · 工具执行并行工具 · 结果回写全局状态

▼ return_direct 或无 tool_calls → 走向出口

⑤ afterAgent Hook 链审计/收尾

▼

⏹ ENDexitNode 出口

💡 这不是 while 循环——循环结构是编译产物（`loopEntry → MODEL → 路由 → TOOL → loopEntry` 显式成环），Checkpoint 每节点自动存盘、可中断恢复、可审计。

🔀 流转详情（当前步骤）—— 例："帮我查北京天气，写入 report.txt"

---

⚙️ 谁在做

🏠 在哪个环境

💾 数据落点

🧩 挂载机制

⤵ 输入-

⤴ 输出-

💡 点左侧组件看职责；播放/步进沿编译图走。

⚡ 加载完成 · 播放或步进

⚙️ 框架侧

🤖 LLM 侧

🔧 工具侧

🏁 出口

🧅 洋葱模型演示 —— 注册正向 H1→H2→H3，afterModel 执行反向（类比 Spring Interceptor postHandle）

① 注册顺序（正向）：H1 日志记录 → H2 内容编辑 → H3 安全拦截（最后注册）

H1 日志记录→H2 内容编辑→H3 安全拦截

② 原始模型输出进来时，最后注册的 H3 最先执行（离 raw 最近），H1 最后看到最终版本

raw 输出
可能含危险指令 →H3 安全拦截
最先看到 raw · 拦截/校验 →H2 内容编辑 →H1 日志记录 →最终输出

▶ 点播放洋葱动画，看 H3→H2→H1 反向流

💡 安全 Hook 必须最后注册——它要第一个看到 raw output。注册反了 = 安全拦截看到的是别人处理过的版本，可能放行危险内容（坑 2）。

⚖️ 条件路由 makeModelToTools() 与 4 个关键节点

路由优先级（整个循环的控制中枢）：
① jump_to → Hook 运行时声明强制跳转（state.put("jump_to","end") 强制终止）
② 有 tool_calls → 走 AGENT_TOOL（工具执行）
③ isToolResponse 且 allReturnDirect → end
④ 否则 → model（继续循环）

4 个关键节点（initGraph 第 11 步确定）：

entryNode

循环入口 —— beforeAgent 之前，图的起点

loopEntryNode

每轮汇聚点 —— 工具执行后跳回，重新进入 beforeModel

loopExitNode

循环出口判断 —— 条件路由所在，决定"继续还是退出"

exitNode

整体出口 —— afterAgent 之后，图的终点

💡 循环结构是编译产物不是运行时状态——这让"死循环风险"可以在编译期静态环检测就发现，比 while 循环的运行时计数更早。

🆚 while vs 图编译 · AgentScope Reactor 对比

传统 while 循环（代价）

· 状态在调用栈：崩溃丢状态
· 无法中断/恢复 → 不支持 HITL
· 无法并行多 Agent
· 不可观测，不知道第几轮推理

图编译（自动获得）

· Checkpoint 每步存盘+恢复
· Interrupt 任意 afterModel 暂停
· Nested 子图可嵌入
· Observable 每节点输入输出被记录

AgentScope 的 Reactive Hook 事件链（不同派别）：
ReActAgent.call() → PreCall → reasoning() → PreReasoning → LLM → PostReasoning → acting() → PreActing → 工具 → PostActing → summarize() → PreSummary → LLM → PostSummary → PostCall（12 个 Hook 拦截点）

对比：图编译把"循环结构"显式建模（可分析、可静态检测环）；Reactor flatMap 事件链把循环隐式在流里（更轻，但循环终止只能靠程序计数兜底）。