Message an Agent 节点
使用 Message an Agent 节点从工作流向 agent 发送消息,然后在后续节点中使用 agent 的回复。agent 会运行自己的推理循环、调用自己的工具和技能,并将响应返回给工作流。
您可以向已经构建的 agent 发送消息,也可以直接在节点中定义内联 agent。
提示
Agents 目前处于预览阶段。若要了解如何构建、发布和管理 agent,请参阅构建和管理 agents。
与其他工作流执行一样,您发送的每条消息都会计为一次执行。
提示
节点版本
本页介绍版本 3.1。早期版本不提供部分控件:
- 版本 1 使用支持列表和 ID 两种方式的智能体选择器;版本 2 引入了新的智能体选择器。
- 版本 3 新增 Require Specific Output Format 要求特定输出格式。
- 版本 3.1 新增 Session 会话设置。
您可以在节点设置面板底部查看节点版本。
Node parameters 节点参数
Agent
选择要向其发送消息的 agent。
列表会显示与工作流属于同一项目的 agents。如果列表为空,则该项目还没有 agent。请在该项目中创建一个 agent,或将工作流移到目标 agent 所在的项目。
运行工作流的方式决定使用哪个 agent 版本:
- 手动执行和聊天执行使用 agent 的当前草稿,因此测试时始终会采用最新更改。
- 生产执行使用 agent 的已发布版本。
更改 agent 后请发布它,否则生产运行仍会使用之前的版本。
Message 消息
输入要发送给 agent 的消息。请像向人提出请求一样编写,并使用表达式加入前面节点的数据。
例如:
Process the refund for order {{ $json.order_id }}, then confirm with the customer that it was approved.
Require Specific Output Format 要求特定输出格式
如果后续节点需要可预测的数据结构而不是自由文本,请开启此选项。agent 随后会在 structuredOutput 字段中返回与您所定义 schema 匹配的对象。
使用 Schema Type Schema 类型选择定义 schema 的方式:
- Generate From JSON Example 从 JSON 示例生成:在 JSON Example JSON 示例中粘贴示例对象,n8n 会据此构建 schema。示例中的每个属性都会成为必填项。
- Define Using JSON Schema 使用 JSON Schema 定义:在 Output Schema 输出 Schema中使用 JSON Schema 格式自行编写 schema。
警告
结构化输出由模型提供商强制实施,因此支持情况因提供商而异。为获得最可靠的结果,请将每个属性标记为必填。部分提供商会拒绝可选字段或高级关键字,另一些则完全不支持结构化输出。
Node options 节点选项
在 Advanced 高级下选择 Add Option 添加选项,即可添加以下选项。
Enable Streaming 启用流式传输
决定是否在 agent 生成文本时流式传输响应,而不是等待完整回复。默认启用。
只有触发器支持流式传输时,调用方才能收到流。请将已连接的 Chat Trigger 或 Webhook 节点上的 Response Mode 响应模式设为 Streaming 流式传输。使用其他响应模式时,工作流会等待完整回复,开启此选项不会产生可见差异。
Invoke Agent 调用 Agent
决定是针对所有输入数据项调用一次 agent,还是针对每个输入数据项分别调用:
- Once for All Items 对所有数据项调用一次:只调用一次 agent。agent 可以读取每个输入数据项。这是默认选项。
- Once Per Item 按数据项调用:为每个输入数据项调用一次 agent。
此选项不适用于内联 agents。
Session 会话
会话允许 agent 记住之前的消息。如果不使用会话,每次执行都会开始一次全新的对话。
设置 Session ID 会话 ID,选择会话键的来源:
- Connected Chat Trigger Node 已连接的 Chat Trigger 节点:复用直接连接的 Chat Trigger 中的会话。这是默认选项,因此 Chat Trigger 无需额外设置即可工作。
- Define below 在下方定义:在 Key 键中输入自己的键,可以是静态文本或表达式。可用它将多次运行归入同一次对话,例如使用客户 ID 进行分组。
会话键最长为 74 个字符。
Allow Agent to Access Other Nodes' Data 允许 Agent 访问其他节点的数据
决定是否向 agent 提供可读取工作流中其他节点执行数据的工具。默认关闭,此时 agent 只能访问自己的输入。
此选项不适用于内联 agents。
Node output 节点输出
节点为每次 agent 调用返回一个数据项,其中包含以下字段:
| 字段 | 说明 |
|---|---|
text |
agent 的响应。 |
structuredOutput |
开启 Require Specific Output Format 要求特定输出格式时,与 schema 匹配的对象;否则为 null。 |
usage |
本次调用的 token 使用情况。 |
toolCalls |
agent 生成响应时调用的工具。 |
finishReason |
agent 停止的原因。 |
session |
运行本次调用的会话。 |
提示
节点版本 1 在名为 response 的字段中返回响应。版本 2 将其重命名为 text。仍使用版本 1 的现有工作流会继续使用旧字段名。
将节点用作工具
此节点也可以作为 Message an Agent Tool 使用,让 AI Agent 把工作交给您的某个 agent。将它连接到 AI Agent 节点的 Tool 工具输入,并使用相同的方式进行配置。
相关资源
常见问题
以下是 Message an Agent 节点的一些常见错误和问题,以及相应的解决或排查步骤。
Agent 列表为空
Agent 列表只显示工作流所属项目中的 agents。其他项目中的 agents 不会显示。
请在工作流所在项目中构建 agent,或将工作流移到目标 agent 所在的项目。
找不到 Agent 或无权访问
节点只能访问工作流所属项目中的 agents。如果有人删除了 agent,或工作流与 agent 位于不同项目,您会看到此错误。
请检查 agent 是否仍然存在,并确认它与工作流位于同一项目。
Session ID 最长为 74 个字符
n8n 使用由项目 ID 和您的 session ID 组合而成的键存储会话,而存储值有固定长度限制。
请缩短 Key 键中的值。如果从上游数据映射了较长的 ID,请先对其进行哈希或截断。
Prompt 为空
当 Message 消息解析为空值或非文本值时,节点会返回 Prompt cannot be empty。
请检查 Message 消息中的表达式。返回对象或数字的表达式会解析为空 prompt,因此请先将其转换为文本。