快速上手：你的第一个智能体

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-nodes/src/nodes/builtin/agent、deploy/workflow-templates/tools-user/、crates/cheng-nodes/src/nodes/builtin/tools/tool_hub

第一个工作流搭的是一张由你决定顺序的图。这一篇搭的是智能体：你给它一个目标和一些工具，顺序由它在运行时自己决定。

大约十五分钟。你需要一个运行中的实例和一个配置好的模型供应商。

什么时候该用智能体

智能体比普通图更贵、更慢、也更不可预测。只有当各步骤确实取决于前面步骤发现了什么时，这些代价才值得——「翻一遍这些文件，告诉我哪些提到了 X」没有固定顺序，因为不读完第一个文件，智能体无从知道第二个该开哪个。

如果顺序你已经知道了，那就直接画图。

形态

六个节点。这是 tools-user 模板的结构，也是标准的智能体布局：

chat/input ─────────────────► agent/react_agent ──► chat/output
                                 ▲       ▲
                  ai/llm_config ─┘       └─ tools/tool_hub ──► tools/file_ops_hub

• chat/input 接收用户消息。
• ai/llm_config 保存模型选择，通过连线接入智能体而不是填在它里面——于是一个配置节点可服务多个节点。
• agent/react_agent 就是那个循环。
• tools/tool_hub 把多个工具收敛到一个稳定函数背后。
• tools/file_ops_hub 是真正的能力，本例中是文件操作。
• chat/output 返回答案。

第 1 步 · 从模板开始

与其从零搭，不如安装 tools-user 模板——见工作流模板。你会直接得到上面这套已经连好的布局，可以先读懂再动手改。在编辑器中打开它。

如果你更愿意手搭：把这六个节点拖上来，按图连线——输入连到智能体的任务输入，llm_config 连到智能体的 llm_config，Tool Hub 连到智能体的 tools 端口，智能体的答案连到 chat/output。

第 2 步 · 配置模型

选中 ai/llm_config，挑一个供应商和模型。

在继续之前有一件事必须确认：智能体的 use_function_calling 默认为 true，而并非所有供应商都声明了原生工具调用。 在随附的 providers.toml 里，Anthropic 和 Ollama 没有声明 native_tool_calling，因此 use_function_calling = true 的智能体在这两家上无法工作。请选一个声明了它的供应商——见大语言模型与模型配置。这是第一个智能体毫无反应的最常见原因。

第 3 步 · 给它工具

选中 tools/file_ops_hub，打开你希望它具备的操作。读操作可以放心启用；第一次运行时把写操作留着关掉。

然后看看 tools/tool_hub。它的职责是把多个工具收到模型只调一个函数的背后，而不是让模型的工具列表一直变长、长到列表本身开始吃掉上下文窗口。对第一个智能体来说，默认值就够了。

第 4 步 · 设定迭代预算

选中 agent/react_agent：

short 模式意味着：迭代预算用尽时，暂停并询问你，而不是悄悄停下。学习阶段你要的就是这个——一个默默放弃的智能体，比一个明说「我跑到头了」的智能体难调试得多。

第 5 步 · 运行

用画布旁边的对话面板，问一件确实需要四处看看的事，例如：

列出工作区里的文件，并告诉我哪个最大。

盯着这次运行。每一轮迭代都会渲染成独立的一组：推理、带参数的工具调用、结果，然后是下一轮。这部分值得你仔细看——你看到的是智能体真实的决策，而不是对它们的概括。

第 6 步 · 读轨迹

智能体返回的不只是答案：

最该盯的数字是 iterations_used。如果每次都撞上 max_iterations，说明任务对这个预算来说太大，或者工具不对路——直接调高上限通常只是掩盖症状。

出问题时

接下来做什么

循环跑通之后，有价值的升级是：

1. 更好的工具。 智能体的上限就是它能调用的东西。接入 MCP 服务或技能。
2. 审批门。 在启用写操作之前，先在它们前面放一道审批门，让你逐个确认危险动作。
3. long 模式。 面向多步自主工作时，把 task_run_mode 切到 long，只要智能体还在推进，它的预算就会续上。

下一步

• ReAct 智能体指南——每个设置的深入讲解。
• 工具发现与 Tool Hub——工具超过几个之后怎么扩展。
• 人工审批与评审——启用写操作之前先看这个。