> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体工作流

**智能体工作流（Agent Workflow）节点** 会把后续工作流封装成一个可被上游 Agent 调用的工具。Agent 决定调用它时，节点会执行其后连接的工作流节点，并把执行结果以 `ToolMessage` 写回给调用它的 Agent。

当一个工具结果需要多步骤编排时，可以使用智能体工作流，例如数据检索、条件分支、迭代处理、调用其他工具、HTTP 请求、代码执行，以及最终结果格式化。

:::note
智能体工作流替代旧的 **智能体工具（Agent Tool）** 工作流节点。已有 `agent-tool` 节点会继续兼容运行，但新建工作流应使用 `agent-workflow`。
:::

## 工作机制

1. **注册为工具**
   * 节点会注册为上游 Agent 可调用的工具。
   * `工具名称`、`工具描述` 和 `工具参数` 会作为模型看到的工具名称、描述和入参 schema。

2. **传递调用参数**
   * Agent 调用工具时，调用参数会保存到智能体工作流节点状态中。
   * 每个配置的输入参数都会暴露给后续节点，变量路径为 `args.<参数名>`。

3. **执行子工作流**
   * 智能体工作流后连接的节点就是这个工具的实现逻辑。
   * 子工作流可以包含分支、迭代、工具调用、HTTP 请求、代码执行、模板转换、知识检索和 Agent 节点。

4. **返回给调用 Agent**
   * 子工作流完成后，智能体工作流会创建 `ToolMessage` 并写回调用它的 Agent。
   * 调用 Agent 会基于该工具结果继续推理和回答。

## 配置说明

| 配置项       | 说明                                              |
| --------- | ----------------------------------------------- |
| **节点名称**  | 工作流画布中的展示名称。                                    |
| **工具名称**  | 暴露给 Agent 模型的工具标识。为空时会使用节点 key，并产生 warning 校验项。 |
| **工具描述**  | 帮助 Agent 模型判断何时调用该工具的说明。                        |
| **工具参数**  | 工具调用的输入 schema。参数会在后续节点中以 `args.<name>` 形式使用。   |
| **返回内容**  | 选择返回给调用 Agent 的内容来源。                            |
| **终点**    | 在 Agent 交接流程中将该节点标记为 Agent 终点。                  |
| **后续工作流** | 智能体工作流后连接的节点负责实现具体工具逻辑。                         |

## 返回内容

智能体工作流支持三种返回方式：

| 方式       | 行为                                        | 推荐场景                      |
| -------- | ----------------------------------------- | ------------------------- |
| **最后消息** | 返回工作流状态中的最后一条消息，保留旧智能体工具行为。               | 以回答节点或 Agent 节点结束的简单流程。   |
| **变量**   | 返回某个后续节点产出的变量，例如迭代节点的 `output_str` 或模板结果。 | 需要稳定、可预期返回数据的流程。          |
| **模版**   | 使用 Mustache 模版渲染工作流变量，并返回渲染后的文本。          | 需要把多个变量组织成结构化结果或说明性文本的流程。 |

如果后续路径最后是**迭代**节点，不要依赖**最后消息**。请选择迭代节点的输出变量，通常是 `output_str`，或者在迭代节点后添加**回答**节点并返回该结果。当智能体工作流以迭代路径结束且仍使用最后消息返回时，校验会报告错误。

## 兼容性

* 新节点使用 `WorkflowNodeTypeEnum.AGENT_WORKFLOW`，值为 `agent-workflow`。
* 旧节点 `WorkflowNodeTypeEnum.AGENT_TOOL`，值为 `agent-tool`，仍会为已有工作流继续加载和运行。
* 旧的智能体工具文档页仅作为废弃兼容入口保留。

## 最佳实践

1. 为工具提供清晰的名称和描述，帮助 Agent 模型稳定选择它。
2. 明确定义输入参数，不要让后续工作流依赖隐式上下文猜测。
3. 生产流程优先使用**变量**或**模版**作为返回内容。
4. 只有以回答或 Agent 响应结束的简单兼容流程，才建议使用**最后消息**。
5. 如果存在分支，确保选择的返回变量在所有可能路径上都会产出，或在每条分支上使用模版/回答节点生成返回内容。