ReAct 智能体开发指南

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-nodes/src/nodes/builtin/agent/strategy/agent.rs、agent/strategy/task_mode.rs、agent/base

普通工作流在设计阶段就决定了自己的顺序——连线是你画的。而智能体在运行时决定：它推理任务、调用工具、查看结果，然后重复，直到完成或被某个限制终止。agent/react_agent 就是这个节点。

这是一笔用控制力换能力的交易。当后续步骤确实取决于前面步骤发现了什么时，用智能体；当你已经知道顺序时，用普通图，因为图更省钱、更快，而且完全可预测。

循环

agent/react_agent 把三个阶段合并进画布上的单个节点——Plan、Execute、Review——所以你连一个节点就够了，不需要手工搭一个循环：

1. Plan——根据任务和已发生的事情决定下一步动作。
2. Execute——调用选定的工具并捕获观察结果。
3. Review——判断任务是否完成，未完成则继续。

循环持续进行，直到智能体给出最终答案、达到 max_iterations，或被某条策略终止。

配置

use_function_calling 通常应保持开启：原生 function calling 让供应商直接输出结构化的工具调用，而不是让智能体从散文里解析工具意图，可靠性明显更高。只在模型不具备该能力时才关闭它——哪些供应商支持见模型配置。

use_llm_evaluation 的代价是每轮评审多一次模型调用，换来的是更好的完成度判断。对有明确结束状态的任务保持关闭；对「完成」需要主观判断的开放式工作则打开它。

短任务与长任务

task_run_mode 设置在两种循环策略之间选择，选对与选错的区别就是「智能体过早停止」和「智能体永远跑不完」：

long 模式不是「更多迭代」——它是一条不同的终止规则。它有自己的高级安全阀（internal_window、no_progress_windows、partial_window_limit、checkpoint_parse_failure_limit），存在的意义是让停止取得进展的智能体被终止，而不是把预算耗在原地打转上。除非你有具体的停滞问题要解决，否则不要动它们。

给智能体配备工具

把工具节点连到 tools 端口。来自所有已连接来源的工具定义会被合并成模型看到的那一套工具。可扩展的做法是 Tool Hub，它把许多工具放在一个稳定函数背后，而不是让模型的工具列表线性膨胀。

智能体还自带一些内置能力：它可以读取自己的执行轨迹，并为多步骤工作维护一份待办清单。

循环内部还运行着两道护栏，知道它们的存在能解释一些看起来莫名其妙的行为：

• 重复读取抑制。 两次读取同一段文件范围，或重复一次已经执行过的搜索，会被检测并劝阻——否则智能体会把迭代次数消耗在重读已有内容上。
• 变更前置检查。 变更类操作可能要求先检视目标，所以智能体会在覆盖之前先看一眼。

凭证

智能体遵守和其他所有节点相同的规则：工具收到凭证，模型收不到。 智能体可以调用需要认证的 API，而密钥从不出现在它的上下文里。这正是自主工具调用可以放心开放的原因——提示词注入无法窃取一个模型从未拿到过的密钥。

审批与评审

工具可以返回 requires_review: true，这会把执行转入 waiting_for_review 并挂起，直到有人做出决策。决策会持久记录在审批上下文上，而不只是广播出去，因此在无人监听时做出的决策不会丢失。对不可逆的操作使用这个机制——参见 utils/approver。

上下文管理

长时间运行最终会超出模型的上下文窗口。智能体会跟踪上下文用量并发布 CONTEXT_WINDOW_STATUS_UPDATED 事件，在需要时压缩历史，并对上下文溢出做分类，从而能够恢复而不是直接失败。

观察一次运行

智能体运行发出的事件流比普通节点丰富得多：AGENT_ITERATION_COMPLETED、TOOL_EXECUTION_STARTED / COMPLETED / FAILED、AGENT_TURN_STARTED / COMPLETED、AGENT_PAUSED_FOR_REVIEW 和 CONTEXT_WINDOW_STATUS_UPDATED。对智能体来说，读这个流就是调试方法——事后读 trace 输出能告诉你发生了什么，但事件流能告诉你它卡在哪里。

从模板出发

两个内置模板是值得在自己动手前先读一读的可运行智能体：tools-user（在沙箱中带文件操作工具的 ReAct 智能体）和 create-workflow（根据自然语言构建工作流的智能体）。

下一步

• 工具发现与 Tool Hub——扩展工具面。
• 模型配置——挑选适合智能体工作的模型。
• 测试与调试——观察一次运行。