NodeTool Agent 系统全揭秘:CodeAct 执行循环与任务规划,AI 如何自动搭建工作流
NodeTool Agent 系统全揭秘:CodeAct 执行循环与任务规划,AI 如何自动搭建工作流
NodeTool 是一个开源的 Agent-first 创意工作区,它的核心 Agent 系统基于 CodeAct 执行循环(代码即动作空间)与任务规划(TaskPlanner)驱动:你只需描述想要的效果,AI Agent 就会自动拆解步骤、调用工具、执行代码,甚至自动搭建并运行工作流。本文将用通俗易懂的方式,拆解这套 Agent 系统的设计原理与运作机制。
为什么传统"工具调用"模式不够用
在早期的 Agent 设计中,模型每执行一个动作就要发起一次 JSON 工具调用,宿主执行后把结果作为消息返回——一个工具一次往返。步骤越多,往返越多,既慢又贵。
NodeTool 采用了学术界验证的方案:CodeAct(Wang et al., ICML 2024)。核心思想是让模型直接编写 JavaScript 程序作为动作,程序在沙箱里一口气完成链式调用、循环、分支和结果后处理,研究数据显示该方式相比 JSON 工具调用:
- 任务成功率提升最多 +20%
- 完成轮次减少约 30%
- 大型数据结果先在沙箱内"瘦身",只把摘要送回上下文,进一步节省 token
相关设计文档:codeact-design.md
CodeAct 执行循环:写代码、看结果、再修复
模型只看到一个"工具":execute_code
在 CodeAct 模式下,模型看到的 provider 工具只有一个:
execute_code({ code, title, risk })—— 提交一段 JavaScript 程序
程序会在 QuickJS WASM 沙箱中执行(30 秒超时、64MB 内存上限、网络出口防护等限制自动生效),执行完的返回值、日志、错误一起打包成观察结果(observation)送回给模型,进入下一轮。这个"写代码 → 执行观察 → 修复重试"的闭环,就是 CodeAct 执行循环的精髓。
核心执行器实现位于 codeact-executor.ts,沙箱引擎在 js-sandbox.ts。
沙箱里的"工具带":import 即调用
模型不需要逐个记住工具函数。工具通过 import 语句按需引入:
import { web_search } from "@nodetool-ai/sandbox-nodetool/web";
const results = await web_search("ComfyUI 教程");
// 一个动作里可以循环、过滤、汇总任意多次调用
return results.slice(0, 3).map(r => r.title);
配合 nodetool.* 对象模型(nodetool-api.ts),Agent 还能直接操作工作流、节点、媒体、记忆、时间线等 18 个命名空间,实现"平台即对象"的编程式控制。
记忆:跨动作、跨轮次的持久承载
局部变量随动作结束而消失,NodeTool 用运行期记忆(context.memory)承接关键产物:
- 每步结果写入
step:<id>,每任务结果写入task:<id> - 生成类调用把产物存为资产,仅返回轻量的
asset://引用 - 后续动作通过
nodetool.memory.*按需读取,避免重复抓取或重复生成
详见 agent-memory.md。
任务规划:从一句话到一张可执行 DAG
当任务复杂到值得拆分时,Agent 不会即兴乱跑,而是走规划流程(TaskPlanner):
- create_plan —— 将目标拆解为任务与步骤组成的 DAG(有向无环图),独立任务被标记为可并行
- execute_plan —— 由 ParallelTaskExecutor 调度,独立任务并发执行
- 结果汇聚 —— 每步结果写入记忆,最终由父循环读取
task:<id>汇总成最终答复
在 Plan 模式下,计划只会生成、不会执行,你可以逐条审查;切到 Auto 模式后,Agent 会为每段代码动作声明 low / high 风险标签——低风险动作静默执行,高风险动作(删除、发布、花钱)才弹窗询问一次。这样既保持自动化的流畅,又不丢失用户掌控权。
AI 如何自动搭建工作流
这是 CodeAct 最直观的应用场景:当你说"帮我做一个把脚本变成时间线的流程",Agent 会:
- 用
openWorkflow打开工作流对象模型(graph-model.ts) - 添加节点、连线、设置参数——全部是同步方法调用,一次
commit()提交 - 调用
validate_workflow对照节点库校验,失败则自动修复重试 - 保存为正式工作流并试运行,把出错节点调试通过
生成的就是你工作流库中的一个普通工作流,之后可反复编辑、复用、分享。整个"规划 → 生成 → 校验 → 运行 → 调试"闭环无需人工干预。
架构决策:统一为唯一的 Agent 循环
值得注意的是,ADR-0002 做出了一个关键决策:CodeAct 是唯一的 Agent 执行循环,没有开关。旧的 JSON 工具循环仅保留给两个"一次性结构化判定"场景。理由很实际——两套循环意味着预算、权限、调度等每个能力都要维护两遍,而没人用的那套会逐渐腐烂。
这一决策保证了:聊天、Plan 模式、CLI、子 Agent 全部跑在同一条 CodeAct 会话上,行为一致、修复一次生效。
安全边界:自动化不等于失控
CodeAct 让模型能写任意代码,NodeTool 用多层机制兜底:
- 沙箱限制:30 秒超时、CPU 中断、64MB 堆、fetch 数量/体积上限、SSRF 防护,禁止
eval/动态模块加载 - 权限阶梯:每步的工具允许列表就是权限边界,代码动作只能看到被授予的工具子集
- 风险声明 + 静态抬底:模型声明
risk,宿主在运行前校验;静态检测到导入execute/external能力类导入时,风险自动抬到 high,无法通过声明绕过 - 宿主侧 finish 校验:步骤完成必须通过宿主验证,沙箱内无法伪造"已完成"
小结:一套循环打通"说到做到"
| 能力层 | 关键组件 | 作用 |
|---|---|---|
| 动作空间 | execute_code + QuickJS 沙箱 |
一次动作完成多工具链式编排 |
| 任务规划 | create_plan / execute_plan |
目标拆解为可并行的 DAG |
| 状态承载 | context.memory + asset:// |
跨动作/轮次共享中间结果 |
| 工作流搭建 | graph-model + 沙箱 DSL 包 | 编程式生成、校验、运行工作流 |
| 权限安全 | 风险声明 + 沙箱限制 | 自动化与用户掌控并存 |
NodeTool 的 Agent 系统证明了:让模型"写代码干活"而不是"发 JSON 报菜名",配合统一规划层与严格安全边界,AI 自动搭建工作流就能既快又稳。相关设计文档可深入阅读:codeact-design.md、global-chat.md 中的 Agent Loop 章节,以及源码目录 packages/agents/src/codeact/。



