从 0 到 1 打造 AI 提示流编排器：给大模型装上手和脚！Agent 节点与 Tools 工具调用体系设计与实战（开源系列 09）

深度复盘 AI 提示流编排器 PatchCat 从“静态流水线”跃升至“自主智能体”的内核演进：拒绝意面式环路画布，将 ReAct 自主思考循环内聚于单个 Agent 节点中；设计沙箱代码（builtin_code）、外部 API（builtin_http）与画布节点复用（canvas_node）三大工具形态，详述属性面板配置、数据流转协议与端到端调试实战，攻克流式 SSE 碎片拼接与步数熔断防线。

项目开源地址：https://github.com/GuoBug/PatchCat
在线体验：https://guobug.github.io/PatchCat/
往期回顾：
📖 《从 0 到 1 打造 AI 提示流编排器：即时对话调试抽屉、节点级耗时追踪与一键发布生产 API 实战（开源系列 07）》
📖 《从 0 到 1 打造 AI 提示流编排器：IndexedDB 工业级会话存储、动态 Token 修剪与变量注入实战（开源系列 08）》

一、引言：当提示词流水线遇上“自主思考”

在 PatchCat 之前的版本演进中，我们打造了一套基于 Kahn 算法的高性能有向无环图（DAG）拓扑调度引擎：用户在画布上将输入、Prompt 模板、LLM 推理、条件分支与数据聚合节点自由连线，点击运行后，引擎按照波次层级推进执行。

这套模式在固定 SOP（例如客服意图分流、文档结构化清洗、多模型盲测评测）中表现极为稳定。然而，当业务场景迈向深水区时，我们遇到了一个显而易见的天花板：

如果任务的解题步骤不是预先固定的呢？
例如用户输入：“请帮我按最新汇率折算 450 美元为人民币，并扣除 3% 的跨境手续费，计算出最终到手金额。”

在纯单向流水线模式下，大模型要么被迫“心算”给出不可靠的幻觉数字，要么需要开发者在画布上手工配置繁琐庞大的嵌套路由。大模型必须具备“自主判断使用何种工具、根据工具返回结果再推导演进下一步”的闭环能力。

在最新的 v0.4.2 版本中，PatchCat 正式迎来了 原生 Agent 节点与 Tools 工具调用体系，让编排器从“静态流水线”跃升为“自主智能体”。

本文全程秉承我与 AI 搭档结对辅助编程（AI Pair Programming）与“干中学（Learning by Doing）”的原则，深入拆解我们在攻坚 Agent 节点与工具体系中的关键节点双向启发、方案权衡、底层机制、实操用法与极端边界实录。

二、关键决策与双向共创：人机启发推演矩阵 (Milestone Co-Discovery)

回顾这一里程碑的演进，系统架构走向由一系列决定产品体验与工程底座的关键节点（Critical Milestones）构成：

关键点 1：拒绝“意面画布”，追求极致纯粹的调度心智

我提出的产品定位与交互痛点：
传统工作流工具为了支持 Loop 循环与 Agent，往往允许用户在画布上直接连出“回流连线（Back-edges）”。但在原型实测中，一旦允许画环，连线在画布上频繁交叉穿梭，画布迅速退化为不可读、不可维护的“意面式图谱（Spaghetti Graph）”，用户根本无法直观掌控当前跑在第几轮循环。
底线要求：必须把 ReAct 的自主迭代循环收敛在单个独立的 Agent 节点内部！全局画布依然坚守清爽高效的 Kahn DAG 拓扑调度；循环过程通过节点徽章、打字机事件流透明展开。同时，Tools 决不能局限于静态脚本，必须能够直接将画布上已配好的其他节点（如知识库 RAG 检索）作为现成工具调用！
AI 搭档指出的底层工程隐患：
如果要在单节点内聚 ReAct 闭环，必须建立严格的协议防线与步数熔断守卫：
1. SSE 分片截断风险：在流式输出中，主流大模型的 tool_calls 是作为离散的 delta.tool_calls 碎片化推送的，入参 JSON 字符串可能被切碎在不同数据帧。客户端必须设计字符级累加器，否则频繁抛出 Unexpected end of JSON 崩溃；
2. 模型幻觉死循环：模型遇到矛盾指令或工具执行报错时，极易陷入“反复调用同一无效工具”的死循环，单靠前端无响应等待会烧光用户的 Token 并卡死界面。必须在引擎内核设立带强制熔断的 maxIterations 步数看门狗，并全程贯穿 AbortSignal 强取消支持；
3. 采样参数干扰：大模型进行 Function Calling 时对采样温度极为敏感，必须建议将 temperature 收敛在 0.1~0.3 区间，抑制随机发散。
关键决策沉淀：版本演进与工程克制（作者心得）：
在完成了 Agent 原型开发后，AI 搭档曾建议直接跨跃到 v0.5.0。我当即决定纠偏：“版本步子不应该迈得这么快，这个版本应该是变小一位，定在 v0.4.2。并且我们必须在这个版本停下来，把 Agent 节点和工具体系在真实场景中的用法、配置与边界全部吃透磨平，做扎实了再往前走。” 这种人机协同中的清醒与克制，确保了工程底座的每一步都经得起检验。

ReAct 自主循环与单节点内聚架构

通过上述权衡，我们彻底放弃了破坏拓扑调度的画布级全局回边，全面落地“单节点内聚 ReAct 闭环 + 步数看门狗 + SSE 碎片累加器”的工业级架构。

三、技术剖析：三大工具形态与执行协议 (Tools Taxonomy)

在 v0.4.2 中，我们在 Agent 节点的属性抽屉中提供了开箱即用的可视化配置体系，原生支持 3 种核心工具形态：

PatchCat 三大核心工具形态与执行协议

1. 沙箱代码工具 (`builtin_code`) —— 专治大模型的“算术硬伤”

核心价值：针对高精度代数运算、日期时间差计算、复杂正则提取、数组过滤重排等确定性逻辑。大模型本质是概率模型，算浮点数乘除、百分比折算经常产生幻觉。
执行安全防线：在客户端独立的 Web Worker 沙箱环境中执行，彻底剥离敏感的 DOM、LocalStorage 与外网网络权限。参数通过 inputs 结构化注入，纯 JS 毫秒级计算并 return 结果。

// Web Worker 安全沙箱代码工具执行切片
const workerScript = `
  self.onmessage = function(e) {
    try {
      const inputs = e.data.inputs || {};
      const run = new Function('inputs', e.data.code);
      self.postMessage({ success: true, result: run(inputs) });
    } catch (err) {
      self.postMessage({ success: false, error: err.message });
    }
  };
`;

2. 外部 REST API 工具 (`builtin_http`) —— 连接实时真实世界

核心价值：查询实时外汇牌价、天气预报、快递物流、连接内部企业业务微服务。
执行原理：根据开发者预设的 JSON Schema 生成强类型参数，前端运行时动态向指定 API URL 发起请求，并将 HTTP Response 自动封装为标准 Tool Message 回传给大模型。

3. 画布已有节点复用 (`canvas_node`) —— PatchCat 的杀手锏

核心价值：避免在 Agent 内部重复配置知识库或编写抓取逻辑，直接复用当前画布中已配置的「知识库 RAG 检索节点」或「Prompt 处理节点」。
执行原理：当 Agent 判定需要知识库支持时，引擎将临时挂起当前 Agent 的执行栈，以目标 nodeId 递归调度执行目标节点，取得检索切片结果后，无缝注回 Agent 的上下文。真正做到原子能力即工具、零蜘蛛网连线组合复用！

四、实战指南：AI Agent 节点从配置到画布调度 (How to Use Agent Node)

在 PatchCat 中，AI Agent（自主智能体）节点是整个工作流从“确定性线性编排”迈向“动态自主决策”的核心枢纽。究竟该怎么配置、怎么串接？这里梳理出完整的实操全景：

1. 普通 LLM 节点 vs AI Agent 节点核心差异

为更直观理解两者的分工与能力阶梯，我们通过两张核心维度卡片与对照矩阵进行横向对比：

普通 LLM 节点单向执行器

运行机制：单次直出模式。输入 Prompt ➔ 模型单次推理 ➔ 立即输出文本并结束当前节点生命周期。

能力边界：纯靠模型静态权重与参数记忆，无法调用外部算力或实时 API；遇到高精度代数计算、日期差值或实时外部事实时极易产生“一本正经的胡说八道”。

适用场景：意图分类分流、文本润色、固定模板转换、摘要提取等规则明确的 SOP 环节。

AI Agent 节点闭环决策者

运行机制：ReAct 自主思考循环。Think（思考）➔ Act（选调工具）➔ Observe（观察回传结果）➔ 再 Think...，直到大模型认为任务已彻底解决。

能力边界：自带动态工具箱（Tools），遇数学可调沙箱 JS 计算、遇事实可调 REST API、遇企业数据可调度画布既有 RAG 节点，彻底根治算术幻觉。

适用场景：动态多步推理、需要工具求证的复杂业务、外汇牌价折算与费率计算等未知解题步骤的任务。

核心维度	普通 LLM 节点	AI Agent 节点
执行机制	单次直出：一次输入 ➔ 一次推理 ➔ 输出结束	ReAct 自主循环：思考 ➔ 调工具 ➔ 观察结果 ➔ 再思考 … ➔ 终答
外部能力	纯凭模型记忆，无工具调用能力，易产生幻觉	自带动态工具箱（沙箱 JS、外部 HTTP、画布节点复用）
画布形态	DAG 流程中的单一静态步骤	将完整状态机与步数看门狗内聚在单节点内，对下游暴露标准化结果

2. AI Agent 节点的核心配置（属性面板 4 大配置区）

选中画布上的 Agent 节点后，右侧抽屉面板提供 4 个决定智能体行为的核心配置区：

① 系统提示词 (System Prompt) —— 立规矩与压制幻觉

与普通 LLM 节点单纯关注“输出格式”不同，Agent 的系统提示词必须承担“行为准则与授权边界”的重任。特别是必须明确申明“工具实证法则”，杜绝大模型的自负盲猜。

💬 生产级系统提示词 (System Prompt) 规范示范最佳实践

你是一名资深智能财务分析助手。请充分利用已配置的工具查询实时汇率及精确执行数学运算，给出详尽、可靠且条理清晰的最终分析结果。在面对数学代数与外部牌价时，严禁凭借记忆盲猜，必须优先调用所提供的工具进行实证。

② 工具集绑定 (Tools Management) —— 赋予手脚

点击面板中的 + 添加工具 (+ Add Tool)，可灵活绑定前文所述的三大形态工具：

工具名称（Name）：英文唯一标识（如 calculate、get_exchange_rate）；
功能描述（Description）：至关重要！ 大模型纯粹依靠描述决定何时发起调用（例如：“高精度执行代数运算与百分比折算，接收标准数学算式字符串”）。描述越严谨、示例越清晰，调用命中率越高。

③ 最大迭代轮次 (Max Iterations) —— 步数熔断防线

运行机制：内核级看门狗熔断阈值（建议默认设为 5 ~ 10 轮）。
工程价值：防止大模型在复杂边界下陷入 调工具 A -> 报错 -> 再调工具 A 的无休止死循环。达到轮次阈值后引擎将强制安全截断，保护用户的 Token 账单与响应时间。

④ 模型与采样参数 (Model & Temperature) —— 抑制随机发散

模型推荐：建议选用对 Function Calling / Tool Calling 具有良好原厂支持的模型（如 gpt-4o、deepseek-chat、gemini-1.5-pro 等）；
Temperature 采样温度：强烈建议收敛在 0.1 ~ 0.3。工具调用需要严谨的 JSON 结构与逻辑确定性，过高的 Temperature 会引发字段解析偏差甚至幻觉报错。

3. 画布中的数据流转协议（输入与输出）

Agent 节点如何与画布上的其他节点建立数据连接？PatchCat 提供了简洁且强契约的变量流转机制：

DATA CONTRACT // AGENT NODE I/O SPECIFICATION

1. 输入接收 (Inputs Injection)

在 Agent 节点的输入参数中，使用双大括号插值语法 {{node_id.field_name}} 动态引用上游节点的数据。例如将上游 input_user 输入节点的提问注入给 Agent：

```json { "prompt": "{{input_user.user_query}}" } ```

2. 内部自治 (Black-Box Execution)

无论 Agent 内部经历了多少次 ReAct 循环往返（例如先查牌价、再算手续费），外部 DAG 拓扑调度器始终将其视作单一异步任务挂起等待，画布无需任何回边，彻底杜绝死锁与连线污染。

3. 输出暴露 (Outputs Exposure)

任务完成后，Agent 节点对外暴露规范对象，下游节点（如 Output 渲染卡片、条件判断分支）可通过变量选择器自由消费：

{{agent_node.response}}：最终自然语言回答（多轮推演合成的 Markdown 格式结论）；
{{agent_node.iterations}}：实际迭代步数（整数，如 3，可用于审计或判断是否触及多轮重试）；
{{agent_node.usage}}：累计 Token 消耗对象（包含 prompt_tokens、completion_tokens 与 total_tokens，精确统计单次智能体执行成本）。

五、端到端实战：体验官方内置的双语 Agent 预设

为降低学习门槛，我们在 v0.4.2 中随包内置了官方预设 「自主智能体工具调用与运算流」（Autonomous Agent with Tool Calling）：

打开 PatchCat，在左侧工作流抽屉的 预设模版 目录中载入该预设；
画布清晰呈现 3 个核心节点：用户提问输入 ➔ 智能财务助手 Agent ➔ 最终回答输出；
点击 Agent 节点属性抽屉，可见已自动绑定 get_exchange_rate（汇率查询）与 calculate（代数计算）两个工具；
点击顶部 Run Workflow 执行默认测试问句：

“我有 450 美元，请帮我按最新汇率折算为人民币，并扣除 3% 的跨境手续费，计算出最终到手人民币金额。”

执行时序剖析

第一轮思考（Think 1）：Agent 节点激活紫色脉冲，模型分析后判定需要最新汇率，发起调用 get_exchange_rate(from='USD', to='CNY')，工具返回牌价数据 { rate: 7.25 }；
第二轮思考（Think 2）：模型拿到汇率后，判定需要精准算术，将算式 450 * 7.25 * (1 - 0.03) 注入 calculate 工具，沙箱秒级给出高精度计算值 { result: 3164.025 }；
第三轮思考（Think 3）：模型综合汇率依据、扣除比例与最终到手金额，判定数据全部齐备，组织语言输出规范结论并终止循环；
下游输出：Output 节点直接渲染展示规范解析，节点徽章显示 Step 3/6。

💡 调试利器联动：在运行过程中，配合我们在系列 07 中实现的 即时对话调试抽屉（Chat Debug Drawer），控制台能够实时流式呈现 [Agent Iteration 1] Thinking... 与 [Agent Tool Call] ... 的完整链路，让 Agent 的每一步心智轨迹都纤毫毕现！

六、独立查证与极端测试实录

任何架构的成立都必须建立在严谨的工程实证之上。我们在 tests/agent-node.node.test.ts 中针对性构造了多项极限边界单测：

死循环与看门狗熔断断言：故意输入“求解不可达逻辑”的矛盾 Prompt，模拟模型在工具报错后反复重试的死循环场景。实测验证引擎在达到预设 maxIterations: 5 阈值时能否安全截断，彻底避免 Token 账单被无休止刷爆；
低带宽 SSE 碎片拼接压测：模拟极端网络波动下大模型将入参 JSON 切碎为每帧 1~2 个字符的分块流，验证累加器在各种乱序断帧下均能 100% 完整复原，无任何解析中断；
Loop 迭代与子图空输入容错：为迭代节点输入空数组、非 JSON 字符串甚至是负数，验证系统优雅降级，杜绝页面崩溃白屏。

全部用例在 Node.js CI 环境下保持 195 项自动化测试 100% 绿灯全通，TypeScript 严格模式 0 警告。

七、进阶实战建议与避坑心得 (Pro Tips)

在为 Agent 编排生产级工具链时，有四条非常关键的实战心得：

Tool Description 是模型的唯一指南针：
大模型“看不到”你的代码实现，它纯粹依靠你撰写的 description 和参数解释决定何时调用。
- ❌ 简陋描述："calc"
- ✅ 详尽描述："高精度执行数学代数运算，支持加减乘除与百分比折算，接收标准数学算式字符串"。描述越严谨，调用精准度越高。
在 System Prompt 中申明“工具实证法则”：
在 Agent 系统提示词中明确加入：

“涉及数学算术、实时汇率或客观事实，严禁凭记忆估算盲猜，必须优先调用相应工具进行实证。”
能够立竿见影地压制大模型的自负幻觉。
根据业务复杂度配置 maxIterations：
对于简单确定性问答，建议配置 3 ~ 5 轮步数；对于复杂递归分析，可适当放宽至 8 ~ 10 轮，既给足重试容错空间，又牢固守住成本红线。
结合知识库 (RAG) 节点与调试抽屉：
Agent 节点不仅可以单独使用，还可以在其上游放置知识库检索，先检索出背景文档作为上下文塞入 Agent 的 prompt，由 Agent 负责基于私有知识做深入分析与工具运算。

结语：欢迎体验与 Code Review

从“静态有向图连线”跨越到“智能体自主决策”，是 PatchCat 在开源道路上迈出的关键一步。正是人机协同中对架构边界与底层隐患的双向推演，以及对版本节奏的清醒克制，让我们在纯前端零配置的严苛约束下，打造出了这套兼具极简心智与工业级健壮度的 Agent 系统。

欢迎大家上手体验、审阅源码：

🐱 GitHub 仓库: https://github.com/GuoBug/PatchCat
🚀 在线免安装体验: https://guobug.github.io/PatchCat/

个人能力有限，在复杂图调度的边缘场景与工具协议抽象上必定还有提升空间。非常欢迎社区开发者与资深架构师前去提 Issue、发起 PR，交流探讨，共同进步！

从 0 到 1 打造 AI 提示流编排器：给大模型装上手和脚！Agent 节点与 Tools 工具调用体系设计与实战（开源系列 09）

一、 引言：当提示词流水线遇上“自主思考”

二、 关键决策与双向共创：人机启发推演矩阵 (Milestone Co-Discovery)

关键点 1：拒绝“意面画布”，追求极致纯粹的调度心智

三、 技术剖析：三大工具形态与执行协议 (Tools Taxonomy)

1. 沙箱代码工具 (builtin_code) —— 专治大模型的“算术硬伤”

2. 外部 REST API 工具 (builtin_http) —— 连接实时真实世界

3. 画布已有节点复用 (canvas_node) —— PatchCat 的杀手锏

四、 实战指南：AI Agent 节点从配置到画布调度 (How to Use Agent Node)