NodeTool Agent 系统全揭秘:CodeAct 执行循环与任务规划,AI 如何自动搭建工作流

原创2026-11-14 23:44:281,945 阅读

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 执行循环:写代码、看结果、再修复

NodeTool 的 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):

  1. create_plan —— 将目标拆解为任务与步骤组成的 DAG(有向无环图),独立任务被标记为可并行
  2. execute_plan —— 由 ParallelTaskExecutor 调度,独立任务并发执行
  3. 结果汇聚 —— 每步结果写入记忆,最终由父循环读取 task:<id> 汇总成最终答复

NodeTool 聊天界面中的任务规划与权限模式:Plan / Default / Auto 三种 Agent 执行档位

在 Plan 模式下,计划只会生成、不会执行,你可以逐条审查;切到 Auto 模式后,Agent 会为每段代码动作声明 low / high 风险标签——低风险动作静默执行,高风险动作(删除、发布、花钱)才弹窗询问一次。这样既保持自动化的流畅,又不丢失用户掌控权。

AI 如何自动搭建工作流

这是 CodeAct 最直观的应用场景:当你说"帮我做一个把脚本变成时间线的流程",Agent 会:

  1. 用 openWorkflow 打开工作流对象模型(graph-model.ts)
  2. 添加节点、连线、设置参数——全部是同步方法调用,一次 commit() 提交
  3. 调用 validate_workflow 对照节点库校验,失败则自动修复重试
  4. 保存为正式工作流并试运行,把出错节点调试通过

NodeTool 编辑器内 AI 助手搭建的 Creative Story Generator 工作流:String Input、Agent、Preview 节点自动连线

生成的就是你工作流库中的一个普通工作流,之后可反复编辑、复用、分享。整个"规划 → 生成 → 校验 → 运行 → 调试"闭环无需人工干预。

架构决策:统一为唯一的 Agent 循环

NodeTool 的 Script-to-Screen 自动工作流:提示词、Director 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/。

登录后查看全文
nodetool