构建和管理 agents
agent 是你在 n8n 中构建的 autonomous assistant。每个 agent 都有一个 language model、instructions,以及你配置的 capabilities,例如 tools、skills 和对 knowledge base 的访问。agents 会作为项目中的 first-class artifacts,与工作流并列存在。当任务对固定工作流来说过于开放,并且你需要一个能推理请求、选择合适 tools、并根据响应调整行为的 assistant 时,请使用 agent。
提示
Feature availability 功能可用性
Agents 可用于:
- n8n Cloud: 所有计划
- Self-hosted: n8n 2.32.3 起的所有计划。设置详情请参阅自托管。
提示
Preview status 预览状态
Agents 目前处于 Preview 阶段。它们可能会出错,并且在功能开发期间行为可能发生变化。在自托管环境中,knowledge bases 也处于 Preview 阶段。
启用或禁用 agents
Agents 在包括 Enterprise 在内的所有计划上默认启用。实例所有者和管理员可以为整个实例更改此设置:
- 打开 Settings 设置 > Agents 代理。
- 开启或关闭 Enable Agents 启用 Agents。
n8n 会在重启和 license 变更后保留你的选择。此设置独立于 n8n Assistant 设置。
关闭 agents 后:
- 用户无法创建 agents,也无法从 Preview、聊天、schedules、channels、MCP、evaluations 或 Message an Agent 节点启动新的运行。
- 正在运行的任务可以完成,包括等待 approval 的运行。
- n8n 会取消为未来运行排队的消息;重新启用 agents 后,这些消息也不会执行。
- n8n 会保留已保存的 agents 和 session 历史。重新启用 agents 后,你可以再次访问它们。
Schedules 仍会保留。重新启用 agents 后,它们可以再次触发新的运行。n8n 不会补跑 agents 关闭期间发生的 schedule triggers。
此设置不会影响工作流中的 AI Agent 节点。
配置共享 sandbox
Agents 和 n8n Assistant 使用同一个 sandbox 连接。更改会同时应用于这两个功能。即使任一功能已关闭,你仍可以配置该连接。
在自托管实例上,实例所有者或管理员可以配置连接:
- 打开 Settings 设置 > Agents 代理。
- 在 Shared sandbox 共享 sandbox 下选择 Add sandbox 添加 sandbox。要编辑现有连接,请选择 Code sandbox 行。
- 选择 sandbox provider 并输入连接详情。
- 选择 Save 保存。n8n 会在保存前检查连接。
n8n Cloud 会管理 sandbox 连接。如果通过环境变量配置了自托管连接,页面会显示 Found in server configuration 在服务器配置中找到,且不提供编辑控件。如果连接已经配置但 sandbox 尚未启用,请选择 Enable sandbox 启用 sandbox。
有关环境变量和 module 要求,请参阅在自托管 n8n 上启用 agents。
视频:agents 如何与工作流和 AI 协作
Agents、固定工作流以及仅在特定步骤使用 AI 的工作流分别适用于不同类型的工作。观看视频,了解三者之间的差异,以及它们如何协同构建可用于生产环境的系统。
https://www.youtube.com/embed/P5x0nsY8hCg
可以用 agents 构建什么
使用 agents 基于你上传的文件和已连接服务回答问题,在 Slack、Google Sheets 或 Linear 等 tools 中执行操作,并触发或协调工作流来完成更大的任务。Agents 还可以委派给其他 agents,并按计划运行。请参阅下方的 Sub-agents 子 agents和 Schedules 计划。
Agents 如何工作
agent 会运行一个 reasoning loop。当你向它发送消息,或由 schedule 触发时,agent 会读取你的 instructions,查看请求,并决定下一步做什么:调用 tool、搜索 knowledge base、交接给另一个 agent,或提出后续问题。它会重复这个循环,直到生成最终响应。
与 agent 的每次对话都是一个 session。n8n 会存储 session,因此你可以稍后继续,并让 agent 通过 memory 记住上下文。
Agent 的组成部分
在 Agent Builder 中配置 agent 的这些部分:
| 部分 | 作用 |
|---|---|
| Model 模型 | 用于推理并生成响应的 language model。设置 agent 时选择 provider 和 model。 |
| Instructions 指令 | 描述 agent 角色、语气和约束的 system prompt。 |
| Tools 工具 | agent 可以执行的操作:工作流、自定义代码、内置 n8n integrations,以及 MCP 服务器。 |
| Web search 网络搜索 | 让 agent 使用 model 的原生搜索 tool 或备用服务在网络上搜索最新信息。 |
| Skills 技能 | 可复用的 behavior bundles,将 instructions 与特定任务所需的 tools 打包在一起。 |
| Channels 渠道 | 用户可以访问 agent 的位置,例如 Slack、Telegram 或 Linear。 |
| Schedules 计划 | agent 发布后按周期运行的任务。 |
| Sub-agents 子 agents | 此 agent 可以委派工作的其他已发布 agents。 |
| Knowledge base 知识库 | agent 可以搜索和读取以获取上下文的文件(n8n Cloud,或在已配置 sandbox 的自托管环境中作为 Preview 功能使用)。 |
| Memory 记忆 | Session memory 保存当前对话。Episodic memory 会回忆早期 sessions 中的上下文。 |
Model、Instructions、Tools、Skills、Knowledge、Memory 和 Sub-agents 会在构建 agent 时配置。Channels 和 Schedules 在发布后生效。
草稿版本和已发布版本
每个 agent 都有一个 draft 草稿版本,并且在准备好后会有一个 published 版本。draft 是你进行更改的位置;n8n 会自动保存。published 版本会在有人与 agent 聊天、channel 触发它或 schedule 运行时执行。
发布会对 draft 创建 snapshot,因此正在运行的 agent 不会在你编辑时改变。每次发布都会向发布历史添加一个版本,你可以随时恢复或回滚到早期版本。
构建 agent
在 Agent Builder 中构建 agents。先设置名称和 model,添加 instructions,然后附加 agent 需要的 tools、skills、knowledge、memory 和 sub-agents。n8n 会自动将你的更改保存到 draft。
创建 agent
- 从左侧菜单选择你的项目。然后前往 Agents 智能体 tab。
- 选择 Create Agent 创建 Agent。n8n 会打开带有空白 draft 的 Agent Builder。
- 在 Agent 智能体 tab 中,输入 agent 名称。使用 icon picker 更改图标。
提示
使用 n8n Assistant
向 n8n Assistant 描述你希望 agent 做什么。它会建议要添加的 instructions、tools 和 skills。你可以在 Agent Builder 中继续细化这些建议。
选择 model
在 Agent 智能体 tab 中,打开 Model 模型字段并选择 provider 和 model。如果 provider 需要 credentials,请按照提示添加。
编写 instructions
在 Instructions 指令字段中,描述 agent 的角色、语气和响应格式、应该做什么和不应该做什么,以及常见任务应优先使用哪些 tools 或 skills。
保持 instructions 具体。如果 agent 行为不符合预期,请先优化 instructions,再添加更多 tools。
添加 tools
在 Tools 工具 部分,选择 Add tool 添加工具,并从内置 tools(Slack 或 Google Sheets 等 n8n integrations)、同一项目中的工作流、由 JSON schema 定义的自定义 tools,或使用 MCP 服务器 提供的外部 tools 中选择。
agent 会根据你的 instructions 和任务决定使用哪个 tool,并使用你添加 tool 时附加的 credentials。对于敏感 tools,你可以要求 agent 运行前获得 approval。请参阅批准 tool calls。
启用 Web 搜索
在 Capabilities 功能部分启用 Web search 网络搜索,agent 即可查询价格、文档和新闻等最新信息,而无需您自行添加 tool。
- 如果所选 model 提供原生网络搜索 tool,agent 会直接使用它。
- 如果没有,请选择 Brave Search 或自托管的 SearXNG 实例作为备用服务,并为所选服务添加 credentials。
使用 skills 打包 capabilities
skill 会将 instructions 与特定任务所需的 tools 打包在一起。当 agent 要处理多个彼此独立、且各自有步骤的任务时,请使用 skills。
要添加 skill:
- 打开 Skills 技能 section 并选择 Add skill 添加技能。
- 为 skill 指定名称和简短描述。
- 选择该 skill 可以使用的 tools。
- 编写 agent 运行该 skill 时应遵循的 instructions。
agent 会根据描述和当前请求选择合适的 skill。
上传 knowledge
从 Knowledge 知识 tab 添加 agent 可以搜索和读取的文件。支持的文件类型:csv、pdf、markdown、txt。
提示
Feature availability 功能可用性
Knowledge bases 可用于 n8n Cloud。在自托管环境中,它们需要配置好的 sandbox。请参阅自托管。
提示
Preview status 预览状态
在自托管环境中,knowledge bases 处于 Preview 阶段,未来版本中可能会变化。
上传文件后,agent 可以搜索你的 knowledge base 来回答问题并引入上下文。
配置 memory
Session memory 会保存当前对话上下文。它默认开启,无需设置。
要让 agent 回忆早期 sessions 的上下文:
- 打开 Memory 记忆 tab。
- 启用 Episodic memory 情节记忆。
Episodic memory 需要 OpenAI credential 来存储和检索 memories。
添加 sub-agents
Sub-agents 让此 agent 可以将工作交接给其他已发布 agents。当任务有清晰分离的部分,并且 specialized agent 能更好地处理每个部分时,请使用 sub-agents。
- 打开 capabilities list 中的 Agents 智能体 section。
- 选择 Add agent 添加 agent,并从项目中选择一个已发布 agent。
- 在 When should this agent be used? 何时应使用此 agent? 下,描述应调用此 sub-agent 的场景。
你可以在 agent settings 中设置并行运行的 sub-agents 最大数量。
预览 agent
在 header 中选择 Preview 预览来测试 agent,而不发布它。n8n 会使用当前 draft 启动一个 chat session。发布前请使用 preview 检查 agent 的行为、tool 选择和响应。
如果 Preview 预览被禁用,draft 存在配置错误。n8n 会列出你需要解决的项目。
发布 agent
发布 agent 会让它可供 users、channels 和 schedules 使用。生产环境只运行 published 版本,因此你可以继续编辑 draft,而不改变用户看到的内容或 schedules 使用的内容。
- 在 Agent Builder 中打开 agent。
- 检查错误。如果 Publish 发布被禁用,n8n 会列出你需要解决的配置项目。
- 选择 Publish 发布。
发布会对当前 draft 创建 snapshot,并将其标记为 active version。
更新已发布 agent
agent 发布后,编辑会进入 draft。published 版本会继续运行,直到你再次发布。
要发布你的更改:
- 在 Agent Builder 中编辑 draft。n8n 会自动保存你的更改。
- 使用 Preview 预览测试更改。
- 再次选择 Publish 发布以发布新版本。
要丢弃未保存的更改并匹配已发布版本,请从 publish menu 选择 Revert changes 还原更改。
取消发布 agent
要让 agent 离线但保留项目中的 draft,请从 publish menu 选择 Unpublish 取消发布。用户、channels 和 schedules 将无法运行该 agent,直到你再次发布它。draft 仍可编辑。
与已发布 agent 聊天
Agent Builder 中的 chat panel 可让你直接与 agent 对话。
- 打开 chat panel。
- 输入消息并发送。agent 会启动 session 并响应。
- 要查看或继续过去的对话,请打开 session history 并选择一个 session。
n8n 会将每次对话存储为 session。在 Sessions 会话 tab 中查看 sessions,包括交换过的消息、agent 使用的 tools,以及任何待处理 approvals。
批准 tool calls
对于敏感 tools,agent 会暂停并在运行 tool 前请求 approval。在聊天中选择 Approve 批准允许 tool 运行,或选择 Reject 拒绝取消。agent 会根据你的决定从中断处继续。
从其他位置访问 agents
连接 channel 后,用户可以在 Agent Builder chat 之外访问 agent。
可用 channels:
- Slack
- Telegram
- Linear
- Microsoft Teams:请参阅将 agent 连接到 Microsoft Teams
打开 agent 上的 Channels 渠道 section,并按照你想使用的 channel 进行设置。每个 channel 都有自己的连接和权限模型。
通过 MCP 管理代理
你还可以使用 Claude Desktop 或 Claude Code 等 MCP 客户端,通过 n8n 的实例级 MCP 服务器构建和管理代理。此方式会在 MCP 服务器已有的工作流工具基础上,额外提供用于搜索、创建和配置代理的工具。
提示
Reconnect existing MCP clients 重新连接现有 MCP 客户端
如果你在代理功能可用之前已将 MCP 客户端连接到 n8n 实例,则需要重新连接该客户端才能访问代理管理工具。前往 Settings 设置 > Instance-level MCP 实例级 MCP 并重新连接客户端,以获得通过 MCP 管理代理的新权限。
按计划运行 agents
Schedules 可让 agents 按周期自行运行。从 Schedules 计划 section 添加 schedule,描述 agent 应完成的任务,并选择频率:
- Hourly 每小时
- Daily 每天
- Weekly 每周
- Monthly 每月
- Custom cron 自定义 cron
Schedules 只针对 agent 的 published 版本运行。n8n 会显示每个 schedule 的下次运行时间、上次运行时间和上次运行结果。
在工作流中使用 agents
你可以通过两种方式在工作流中使用 agents:
- 内联创建 agents:直接在工作流中添加 agent 作为节点。这让你无需离开 workflow editor 即可构建和配置 agent。
- 向现有 agents 发送消息:从工作流向已创建的 agents 发送消息。这让你可以访问已发布 agents,并将它们的能力集成到自动化中。
Message an Agent 节点
这两种方式都使用 Message an Agent 节点。选择要向其发送消息的 agent,然后编写要发送的消息。该 agent 会运行自己的 reasoning loop、调用自己的 tools 和 skills,并返回回复供后续节点使用。
此节点还可以:
- 通过连接的 Chat 和 Webhook 触发器,在 agent 生成回复时以流式方式传输回复。
- 复用 session,让 agent 记住之前的消息。如果不复用,每次执行都会开始新对话。
- 使用 JSON schema 约束回复,让后续节点接收可预测的字段。
每条消息都计为一次执行,与其他工作流执行相同。
要让一个 agent 将工作交给另一个 agent,请将 Message an Agent Tool 连接到 AI Agent 节点的 Tool 工具输入。
自托管
在自托管 n8n 上设置 agents 有两种方式:
- 手动构建:Agents 默认启用。你自行选择 model、编写 instructions,并附加 tools 和 skills。实例所有者或管理员可以在 Settings 设置 > Agents 代理 中启用或关闭 agents。
- 完整体验:同时设置 n8n Assistant(
instance-ai),用于 AI-assisted building;你描述 agent,n8n 会为它生成脚手架。knowledge base 需要已配置的 sandbox,连接 channels 需要公开的WEBHOOK_URL。
提示
Feature availability 功能可用性
Agents 自 n8n 2.32.3 起可用于所有自托管计划。
警告
Agents 尚不支持队列模式,并且连接渠道(例如 Telegram)可能会失败。目前请在常规模式下运行 agents。
有关环境变量和设置步骤,请参阅启用 agents。
Agent executions 和定价
与 agent 的一次 turn 会计为一次 execution。turn 是一次单独交换,即你向 agent 发送消息并由它生成响应。
Agents 与工作流共享相同的 execution quota。你的 agents 和工作流产生的 executions 都会计入同一 plan 总额度。