Graph 配置¶
Graph 配置控制工作流执行。理解关键设置有助于构建高效的多智能体工作流。
配置概览¶
Graph 配置分为两个层级：
| 层级 | 控制内容 | 关键设置 |
|---|---|---|
| Graph 层级 | 整体工作流 | 名称、描述、输出格式 |
| Node 层级 | 单个执行单元 | Agent/模型、提示词、工具、连接 |
Graph 层级设置¶
| 设置项 | 作用 | 说明 |
|---|---|---|
| 名称 | 工作流标识符 | 不能包含 / \ . |
| 描述 | 工作流功能说明 | 帮助组织和搜索 |
| 输出模板 | 格式化最终输出 | 组合多个节点的结果 |
输出模板 使用 {{node_name}} 语法组合节点输出：
节点设置¶
每个节点有 6 个配置类别：
1. 标识¶
| 设置项 | 必填 | 作用 |
|---|---|---|
| 名称 | 是 | 节点标识符（不含 / \ .） |
| 描述 | 否 | 节点功能说明 |
2. 执行来源¶
选择一种方式：
| 方式 | 使用场景 | 获得什么 |
|---|---|---|
使用 Agent (agent_name) |
复用已配置的 Agent | 继承 Agent 的模型、提示词、工具 |
使用模型 (model_name) |
自定义临时节点 | 完全手动控制提示词和工具 |
使用子图 (is_subgraph + subgraph_name) |
调用另一个工作流 | 模块化、可复用的逻辑 |
Agent 覆盖：使用 Agent 时，节点设置会覆盖 Agent 默认值。例如，在节点中设置 model_name 会使用不同模型，同时保留 Agent 的提示词和工具。
3. 提示词¶
| 设置项 | 作用 | 支持变量 |
|---|---|---|
| 系统提示词 | 定义节点行为和角色 | 是 |
| 用户提示词 | 本次执行的具体任务 | 是 |
提示词中的变量替换：
| 语法 | 含义 | 示例 |
|---|---|---|
{{start}} |
用户的原始输入 | 分析：{{start}} |
{{node_name}} |
引用节点的输出 | 总结：{{researcher}} |
{{node_name:3}} |
引用节点最近 3 次输出 | 审查：{{checker:3}} |
{{node_name:all}} |
引用节点所有输出 | 合并：{{processor:all}} |
{{@prompt_name}} |
引用已注册的提示词 | {{@data_analyst}} |
4. 工具¶
| 设置项 | 作用 |
|---|---|
| 系统工具 | 内置功能（file_creator、memory_tools 等） |
| MCP 服务器 | 外部服务（网页搜索、数据库、API） |
5. 执行控制¶
| 设置项 | 默认值 | 范围 | 作用 |
|---|---|---|---|
| 最大迭代次数 | 50 | 1-200 | 限制单次执行的工具调用次数 |
| Handoffs | - | - | 节点可被重新选择的次数（用于循环） |
| 输出启用 | true | - | 向用户显示结果 vs 静默处理 |
最大迭代次数指南：
| 范围 | 使用场景 |
|---|---|
| 1-10 | 快速任务、简单查询 |
| 10-30 | 多步骤工作流 |
| 30-50 | 复杂分析（默认） |
| 50-100 | 深度研究、代码生成 |
| 100-200 | 长时间运行的自动化 |
Handoffs 启用循环。设置为 3 时，节点在被禁用前可被选择最多 3 次。详见 Handoffs 了解路由逻辑。
输出启用 控制可见性：
| 设置 | 显示内容 | 用于 |
|---|---|---|
true |
助手回复 | 面向用户的结果 |
false |
仅工具结果 | 后台处理 |
6. 连接¶
| 设置项 | 作用 |
|---|---|
| 输入节点 | 此节点从哪里接收数据 |
| 输出节点 | 此节点向哪里发送数据 |
特殊值：
| 值 | 含义 |
|---|---|
["start"] |
接收用户输入 |
["end"] |
结束工作流 |
连接示例：
| 输入 | 输出 | 流向 |
|---|---|---|
["start"] |
["processor"] |
用户 → processor |
["collector"] |
["analyzer"] |
collector → analyzer |
["validator"] |
["end"] |
validator → 结束 |
["router"] |
["option_a", "option_b"] |
router → 多路径 |
配置模式¶
快速响应¶
- 最大迭代次数：10-20
- 最少工具
- 单一路径（无分支）
深度分析¶
- 最大迭代次数：50-100
- 多个 MCP 服务器
- 文件/记忆操作的系统工具
后台处理¶
- 处理节点的输出启用：
false - 最终通知节点的输出启用：
true
模块化工作流¶
- 使用子图实现可复用逻辑
- 每个子图处理一个职责
- 顺序连接子图
常见问题¶
Q: agent_name 和 model_name 有什么区别？
| 设置项 | 使用对象 | 适用场景 |
|---|---|---|
agent_name |
预配置的 Agent | 可复用、行为一致 |
model_name |
直接访问模型 | 自定义、一次性任务 |
Q: 可以覆盖 Agent 的设置吗？
可以。使用 agent_name 时，任何节点设置都会覆盖 Agent 默认值：
- model_name → 使用不同模型
- system_prompt → 不同行为
- mcp_servers → 不同工具
- max_iterations → 不同限制
Q: 如何引用前面节点的输出？
在提示词中使用 {{node_name}}。连接到 ["start"] 的第一个节点可以使用 {{start}} 获取用户输入。
Q: 达到最大迭代次数会怎样？
执行优雅停止。节点返回已生成的内容。不会报错。
Q: 子图可以相互调用吗？
不能循环调用。如果 A 调用 B，那么 B 不能调用 A。
Q: 同一层级的节点如何执行？
按节点列表中出现的顺序依次执行。