n8n-agents-official

n8n Agents

一等公民 n8n Agent 是一种已保存的资源，拥有自己的指令、模型、工具、技能、子 Agent、记忆、渠道、计划任务、版本和支出限额。它通过 Agent MCP 工具以 JSON 配置，绝不使用 Workflow SDK 代码。工作流中的 AI Agent 节点是另一回事，相关内容见 n8n-ai-nodes-official。

Agents 已全面推出。界面显示 Preview 标签，是因为它们经常变化，而且一些你可能期待的功能尚未提供。它们目前尚未准备好用于 Enterprise：Enterprise 实例可能已启用 Agents，但不要想当然地认为已启用。如果你的工具列表中没有 create_agent，说明此实例未启用 Agents。请说明这一点，并提供工作流方案，而不是猜测。

必须遵守的要求

1. 通过 MCP 创建时，始终发送记忆块： "memory": { "enabled": true, "storage": "n8n" }。界面每次保存时都会添加此项。create_agent 会原样保存你发送的内容；如果不包含此项，即使在同一会话中，Agent 也会忘记上一轮的内容（已实时验证）。
2. 未经用户明确同意，绝不发布。 构建完成的 Agent 是草稿。为已发布的 Agent 配置渠道会立即连接，因此也要对此进行确认。
3. 发布 Agent 调用的对象。 工作流工具必须包含 When Executed by Another Workflow 触发器、位于同一项目中，并且工作流必须已发布（validate_agent 会报告此项）。已保存的子 Agent 也必须发布，但系统不会检查这一点：验证和发布都会通过，随后生产环境中的委派会失败，父 Agent 则会悄然自行作答。
4. 对任何发送、修改、删除或花费资源的操作都要求审批，并了解审批人会看到什么。参见 references/APPROVALS.md。
5. 每次更改都只调用一次 mutate_agent，且始终使用最新的 configHash。 如果哈希过期，会返回 stale_config：请调用 get_agent 并重试。

Agent、工作流，还是 AI Agent 节点？

调用任何构建工具之前先做出判断。第一个问题是“能否大声说出步骤”测试。

你可以……	构建
在请求到来之前说出每一步，且不需要任何判断	工作流
说出每一步，但其中一步需要判断（分类标签、提取、总结、撰写）	带 AI 步骤的工作流：Text Classifier、Information Extractor、chain 或 AI Agent 节点（n8n-ai-nodes-official）
只有看到请求后才能说出步骤，并且有人会与它交谈，或它会自主行动	一等公民 n8n Agent
无法说出步骤，但适用下方某项限制	工作流中的 AI Agent 节点
无法说出步骤，且固定流程也需要同一个“大脑”	一等公民 Agent，由工作流通过 Message an Agent 调用。Agent 负责决策，工作流负责执行

除非适用某项限制，否则“帮我构建一个 Agent”或“助手”都指一等公民 Agent。Chat Trigger 加 AI Agent 节点不能替代用户要求的 Agent。如果请求实际上是固定触发器加固定步骤，请说明两者不匹配，并在改为构建工作流前征求同意。

当前适用 AI Agent 节点的限制

需求	Agent 目前无法实现的原因	替代方案
自定义审批消息，或审批人必须在 Slack 中看到参数	审批只有开或关，且消息固定。渠道卡片只显示工具名称	使用能自行执行发送并等待审批、且包含具体值的工作流工具（可以在同一个 Slack 线程中发布）
将触发器或节点数据精确映射到工具参数	工具表达式只能访问模型自身的参数（节点工具和工作流工具均已实时验证）	AI Agent 节点，或使用结构化输出的 Message an Agent，并由下游节点完成映射
由原生渠道和工作流共享同一段对话	渠道线程与 Message an Agent 会话键位于不同命名空间	在平台触发器上创建一个 shell 工作流，并通过 Message an Agent 调用 Agent
在 Message an Agent 调用中审批	会失败并显示“Suspend/resume is not supported in workflow execution context”	在调用它的工作流中把关该操作

MCP 构建顺序

1. 调用一次 get_agent_builder_reference。其 configSchema 是字段名称的权威来源；如果与本指南不同，以它为准。
2. 调用 search_projects，然后调用 discover_agent_assets（models、integrations、workflows、subagents、mcpServers）、list_credentials，以及使用 usage: "agentTool" 的 search_nodes，再调用 get_node_types 获取节点工具。
3. 调用 create_agent，并提供模型、凭据、指令、记忆块和普通工具。技能、任务和自定义工具要等到之后通过 mutate_agent 添加，因为它们需要服务器生成的 ID。
4. 调用 mutate_agent，每次调用只执行一个操作。skill.upsert 不会更改 configHash；配置补丁会更改。
5. 持续调用 validate_agent，直到 valid: true 且 missing 为空。
6. 调用一次有代表性的 call_agent。它会通过 Preview 使用真实工具运行草稿，因此会产生副作用：如果任何未经批准的工具会发送消息、写入数据或付款，请在测试前询问用户。所有返回的审批请求都交由人工处理；使用各自的 continuation 恢复执行。
7. 使用 validate_agent 返回的 url 报告草稿，并附上会话链接（参见 references/SESSIONS_AND_DEBUGGING.md），然后询问是否发布。
8. 只有在用户明确同意后才调用 publish_agent。渠道：update_agent_integration（references/CHANNELS.md）。

每项操作、错误代码和版本工具的详细信息见 references/MCP_BUILD.md。

深入了解各主题

文件	何时阅读
references/MCP_BUILD.md	任何 mutate_agent 操作、错误代码、版本、还原、删除、availableInMCP
references/CONFIG.md	编写或审查 Agent JSON：所有字段、限制、默认值、版本化内容
references/TOOLS.md	节点、工作流、自定义、MCP 服务和内置工具、输入模式、表达式可读取的内容
references/APPROVALS.md	添加审批、各个界面会显示的内容、无法进行审批的场景、通过工作流工具进行自定义审批
references/SKILLS.md	添加 Agent 技能：加载方式、描述撰写、引用
references/SUB_AGENTS.md	委派、已保存与内联子 Agent、按难度路由模型
references/KNOWLEDGE.md	上传的知识文件与外部向量存储
references/MEMORY.md	记忆类型、会话范围、会话键
references/CHANNELS.md	Slack、Telegram、Discord、Linear、n8n Chat，或“原生渠道还是 shell 工作流？”
references/TASKS.md	定时任务
references/MESSAGE_AN_AGENT.md	在工作流中调用 Agent
references/SESSIONS_AND_DEBUGGING.md	出现问题，或用户询问在哪里查看 Agent 执行的操作

对于通过工作流 shell 构建的聊天机器人（使用没有原生渠道的平台、斜杠命令或自定义路由），shell 模式见 n8n-ai-nodes-official 的 references/CHAT_SURFACE_PATTERNS.md 中的 “Core as Message an Agent” 一节。有一条规则必须立即遵守：在会投递机器人自身消息的界面（Slack、Discord）上，发布回复的 shell 必须在触发器之后立即过滤机器人的用户 ID，否则会不断触发自身。

撰写指令

指令就是系统提示词。与节点采用相同的职责划分：角色设定、规则、输出格式和工具间流程写在指令中；特定工具的调用方式写在该工具的描述中。只有在某些时候才需要的冗长流程，应放入技能中，这样只有在加载时才会消耗令牌。请说明结果应发送到哪里（“将摘要发布到 #ops”），因为定时运行时没有人可以回复。

反模式

反模式	问题所在	修复方法
create_agent 未设置 memory	即使在同一会话中，Agent 也会忘记上一轮内容	发送 { "enabled": true, "storage": "n8n" }
用户要求创建 Agent，却使用 Chat Trigger + AI Agent 节点	缺少渠道、会话、审批、版本、任务和预算	使用一等 Agent，除非受到某项限制
因为验证通过就发布	用户并未批准启用 Agent，而各渠道会随之上线	报告草稿状态并征求同意
已保存的子 Agent 未发布	生产环境中的委派会静默失败；父 Agent 会在没有子 Agent 的情况下作答	父 Agent 上线前先发布子 Agent
工具输入中的表达式读取 $('Webhook') 或 $json.<trigger field>	只能看到模型的参数，因此该值为空或错误	通过消息传递该值，或将映射保留在工作流中
Agent 通过 Message an Agent 或任务调用的工具需要审批	运行失败，或停滞等待处理，无人应答	在调用工作流中设置审批门槛；任务只使用安全的工具
同一项目中的两个 Agent 使用相同的 Message an Agent 会话键（例如都使用未经处理的 Telegram id 作为键）	键的作用域是整个项目，而非单个 Agent：第二个 Agent 会报错，显示 "Failed to create the agent execution record"	为每个 Agent 添加前缀：support-<telegramId>
Skill 正文含糊地写着“read references/x.md”	模型经常会跳过	“回答前，使用 load_skill（filePath）加载 references/x.md”
通过 config.patch 设置集成	会被拒绝	使用 update_agent_integration
使用为 Slack Trigger 创建的凭据连接 Slack	所有检查都能通过，但收不到任何内容	使用托管设置，或使用请求 URL 指向此 Agent 的应用