n8n-ai-nodes-official

n8n AI 节点

AI Agent 节点（@n8n/n8n-nodes-langchain.agent）是一个多轮大模型驱动器，包含模型、记忆、工具和可选输出解析器的子节点。它位于工作流中，由工作流负责触发器、控制流和生命周期。

使用 AI Agent 节点还是一等 n8n Agent？

默认情况下，“帮我构建一个 Agent”指的是一等 n8n Agent（n8n-agents-official）。当工作流负责控制流且 AI 只是其中一个边界明确的步骤时，或者一等 Agent 遇到限制时，使用该节点：

需求	目前该节点更合适的原因
将触发器或上游数据精确映射到工具参数	Agent 工具表达式只能访问模型自身的参数。节点工具可以使用 $('Webhook').item.json...
在聊天渠道与其他工作流之间共享同一段对话	Agent 渠道会话与工作流会话互不相通
MCP 工具列表中没有 create_agent	此实例未启用 Agents

何时使用 Agent 节点，何时使用原始聊天补全

选择方式：

• 需要工具调用、多轮推理或记忆？ 使用 Agent。如果不想多想，Agent 也是不错的默认选择：在整个工作流中统一使用 Agent 很合理，也能简化后续升级。
• 希望以尽可能轻量的方式进行单次文本输出调用？ 使用 Basic LLM Chain（@n8n/n8n-nodes-langchain.chainLlm）和聊天模型子节点（OpenRouter Chat Model、OpenAI Chat Model、Anthropic Chat Model 等）。没有 Agent 循环、工具／记忆／解析器插槽，也更易于调试。注意：聊天模型节点是子节点，不能独立运行。它们需要连接到链或 Agent。如果你更希望统一使用 Agent，这里也可以使用 Agent。
• 根据自然语言输入将内容路由到 N 个输出分支之一（由 AI 选择分支）？ 使用 Text Classifier 节点（@n8n/n8n-nodes-langchain.textClassifier）。该节点有 N 个输出句柄，每个类别对应一个，下游路径可直接连接到各个输出。每个类别都需要名称和描述（模型会根据描述进行选择，仅有名称还不够）。设置 options.enableAutoFixing: true，以便更稳健地处理边缘输入。不要用 Agent + Switch 来实现。Text Classifier 是一个专为此用途设计的单节点。
• 需要结构化输出，但不需要工具？ 考虑到未来扩展，Agent 是更简便的默认选择。Basic LLM Chain 也接受 outputParserStructured 子节点；如果你希望使用更轻量的节点，它也完全适用。
• 生成图像／音频／视频？ 直接调用相应服务提供商时，使用其原生单次调用节点（OpenAI Image、Gemini Image、ElevenLabs 等）。通过聚合服务（OpenRouter、Together 等）路由时，使用 HTTP Request，因为目前没有原生聚合服务节点，而且原生节点会在媒体操作中将服务提供商的基础 URL 写死。不要用 Agent 封装媒体生成，请参阅下文“二进制数据与 Agent 边界”。

还有其他用于特定任务的 LangChain“chain”／实用工具节点：Information Extractor（从文本中提取结构化字段）、Sentiment Analysis（三路分支）、Summarization Chain、Basic LLM Chain。

对于大多数大模型步骤，Agent 都是不错的默认选择。如果你明确希望使用更精简的节点来进行无需工具、记忆或迭代的单次文本调用，请选择 Basic LLM Chain。如果 Information Extractor／Sentiment Analysis／Summarization Chain／Text Classifier 等专用节点恰好完全适合任务，请选择相应节点。

不可妥协的事项

1. 工具名称和描述属于提示词的一部分。 模型会根据名称和描述选择工具。含糊的工具节点名称（如 doStuff）或不清晰的描述（“用数据做一些事情”）会导致无声故障：模型会跳过你的工具、选错工具，或幻觉出参数。请将二者都视为 API 设计。参见 references/TOOLS.md。
2. 结构化输出：解析并自动修复。 在生产环境中，应使用 outputParserStructured 配合 autoFix: true 和具备编码能力的修复模型（例如 Claude Sonnet 4.6）。

推荐默认做法

• 工具描述是模块化的提示词片段。 任何与如何调用此工具有关的特定内容，都应放在工具描述中，而不是系统提示词中。这样可以让系统提示词保持专注，并使工具能够在不同 Agent 间复用。参见 references/SYSTEM_PROMPT.md。
• 多步骤任务使用子工作流工具（toolWorkflow）。 任何工作流都可以变成带有类型化 fromAi() 输入的工具，并组合分支、错误处理和子工作流。参见 references/SUBWORKFLOW_AS_TOOL.md。
• 对会产生用户可见副作用的工具加入人工审核。 发送消息、付款、退款、账户变更等操作，都应通过 Slack / Chat / Discord / Telegram 审批节点进行把关，确保工具运行前有人审核。参见 references/HUMAN_REVIEW.md。

子节点模式

Agent 节点有一个主输入（提示词或用户消息）和子节点输入：

const aiAgent = node({
    type: '@n8n/n8n-nodes-langchain.agent',
    config: {
        name: 'Customer Support Agent',
        parameters: {
            promptType: 'define',
            text: '={{ $json.userMessage }}',
            options: {
                systemMessage: '...',
                passthroughBinaryImages: true,    // for vision / multimodal
            },
        },
        subnodes: {
            model: openRouterModel,
            memory: simpleMemory,
            tools: [generateImage, editImage, searchKnowledgeBase],
            outputParser: structuredParser,    // optional
        },
    },
})

四个子节点插槽：

• model（必需）：大模型。OpenAI、Anthropic、OpenRouter 等。使用聊天模型变体，而非补全模型变体。
• memory（可选）：对话记忆。没有它，每次调用都是无状态的。参见 references/MEMORY.md。
• tools（可选，但这是使用 Agent 的关键）：Agent 可以调用的工具。参见 references/TOOLS.md。
• outputParser（可选）：强制输出结构化 JSON。参见 references/STRUCTURED_OUTPUT.md。

触发器

不同触发器会以不同方式塑造输入：

• Chat Trigger（@n8n/n8n-nodes-langchain.chatTrigger），设置 availableInChat: true：启用画布聊天测试器，让你在构建 Agent 时试用它。输入为 { chatInput, sessionId, files[] }。记忆会以 sessionId 为键，因此在需要保持对话连续性的地方都要传递它。文件通过 files[] 传入，参见下文的二进制数据部分。这不是生产环境的入口，应改用 Slack / Discord / Teams / Telegram / webhook。
• Webhook：输入形状任意，默认没有会话。通过在请求正文中传递会话 ID / 对话 ID，并将其转发给记忆节点来管理连续性。
• 外部聊天入口（Slack、Discord、Teams、Telegram）：每个会发布回复的聊天触发工作流，都必须过滤掉机器人自身的用户 ID，否则会无限循环，甚至可能导致 n8n 崩溃。若入口支持，优先在触发器层过滤（Slack 的 options.userIds 是排除列表）；否则就在触发器后的第一个节点中过滤。不同入口的语义各不相同，参见 references/CHAT_SURFACE_PATTERNS.md。一流的 n8n Agent 可原生连接 Slack、Telegram、Discord 和 Linear，无需工作流，参见 n8n-agents-official。除了防循环过滤外，简单的机器人（触发器 → Agent → 回复）可放在一个工作流中。一旦需要加载状态体验、子 Agent、跨入口复用或健壮的错误处理，就应拆分为“外壳”工作流和 Agent 核心子工作流。
• 手动 / 计划：用于临时调用。除非明确要继续之前的运行，否则记忆很少有用。
• Execute Workflow Trigger（子工作流）：当 Agent 本身是另一个 Agent 的工具时使用。将触发器声明的输入视为接口契约。

二进制数据与 Agent 边界

模型可以通过 passthroughBinaryImages: true 查看上传的文件（视觉能力）。但工具无法接收二进制数据，而 fromAi() 参数仅支持 JSON。工具也不接受 Base64，即使通过非 AI 绑定也不行。

解决方法：在 Agent 运行前，将上传内容预先存入存储，然后把存储键注入系统提示词；工具将该键作为字符串参数接收，并在内部重新获取。完整模式见 n8n-binary-and-data-official references/AGENT_TOOL_BINARY.md。

在输出端：Agent 的输出格式化器面向文本（如果接入了 outputParser，则为结构化文本）。当模型返回二进制数据（图像字节、音频字节、视频）时，Agent 不会将其输出。下游没有任何内容可供提取，而且尝试在 Agent 后面通过 Code 或 Set 节点恢复也行不通。对于一次性媒体生成，请直接使用提供方原生的单次调用节点，例如 @n8n/n8n-nodes-langchain.googleGemini 或 @n8n/n8n-nodes-langchain.openAi。

例外情况：当媒体步骤确实属于 Agent（多个工具之一，根据对话上下文选择，或编辑先前生成的图像）时，可使用一种变通方法：创建一个工具子工作流，将结果上传到存储，并返回键或 URL。模式见 n8n-binary-and-data-official references/AGENT_TOOL_BINARY.md。不要默认采用这种方式。上传、获取键和重新获取的流程会增加节点，以及原本不需要的存储依赖。只有当编排确实需要 Agent 选择工具时才这样做。

系统提示词与工具描述分别应包含哪些内容

应放入系统提示词的内容	应放入工具描述的内容
人设、角色、语气	此特定工具的功能
输出格式规则（“以 markdown 回复”）	何时使用此工具而非其他工具
拒绝/安全行为	每个参数的含义及其预期格式
显示协议（“通过 ![]() markdown 显示图像”）	良好与不良调用的示例
通用上下文（当前日期、用户角色）	工具特定注意事项（速率限制、边缘情况）
工具间流程（“生成后，始终通过显示协议展示”）	工具特定输入转换

优点：工具可重复使用。描述完善的工具可以用于任何接入它的 Agent。系统提示词则可以专注于角色和共同行为。

如需更深入的指导和完整示例，请参阅 references/SYSTEM_PROMPT.md 和 references/TOOLS.md。

工具选择：四种类型

选择能满足任务需求的最轻量选项：

• 是否存在原生 n8n 工具节点？（例如 slackTool、gmailTool、calculatorTool）使用它。配置开销最低。
  • 原生节点缺少某项操作或需要自定义参数（例如节点未公开的 Notion 端点、非标准请求头、不同的分页格式）？使用 HTTP Request Tool，并选择该服务的“Predefined Credential Type”。这会复用现有的 OAuth / API 密钥凭证，提供完整的 API 访问权限，且无需编写自定义身份验证代码。
• **是否涉及多步骤逻辑，或需要复用项目中已有的子工作流？**将子工作流用作工具（toolWorkflow）。任何可以构建为工作流的内容，都可以通过类型化的 fromAi() 输入成为工具。这是 n8n 中功能最强大的选项，因此不确定时默认选择此项。参阅 references/SUBWORKFLOW_AS_TOOL.md。
• **是否需要让 Agent 直接编排外部 HTTP API 调用？**使用 HTTP Request Tool。它也适用于通过长轮询回调处理耗时的异步任务。
• **工具是否已作为已发布、可通过 MCP 访问的工作流存在？**使用 MCP 工具。适用于跨工作流的 Agent 能力。参阅 n8n-extending-mcp-official。

如需了解每种选项的深入指导，以及如何连接 fromAi() 参数，请参阅 references/TOOLS.md。

人工审核

在决定是否为某个工具添加人工审核或跳过审核之前，请先询问用户。是否需要审批属于产品／策略决策（影响范围、审计要求，以及他们对模型的信任程度），用户比你更适合做出判断。提出这个问题，根据以下标准给出建议，然后让用户决定。

当工具执行前需要人工批准其操作（发送消息、付款、退款、账户变更、面向客户的操作）时，请使用审核工具节点将其包装起来：slackHitlTool、discordHitlTool、telegramHitlTool、gmailHitlTool 等。（n8n 的节点名称使用 Hitl 表示人机协同模式，而 UI 中称其为“人工审核”。）审核节点位于被包装的工具与 Agent 之间，通过 ai_tool 连接：被包装工具的 ai_tool 输出连接到审核节点，审核节点的 ai_tool 输出连接到 Agent。Agent 发出调用后，审核节点会暂停并等待批准；批准后，被包装的工具才会运行。

以下情况默认添加／建议进行人工审核：

• 工具会发送消息、付款、退款，或以其他方式更改用户可见的状态。
• 审批人和发起对话的人不是同一人（例如，经理审批面向客户的操作，或支持团队审批由客户触发的退款）。
• 触发器是非交互式的（订单、表单、计划任务），但工具的操作需要人工签字批准。

审批消息应显示被包装工具将实际接收的参数，而不是模型转述的文本。直接使用 $tool.parameters.<name>，或遍历 $tool.parameters 列出所有参数。不要使用 fromAi() 填写审批文本，否则审批的将是转述内容，而非实际调用内容。请根据实际值自定义按钮标签，例如 Approve {{ $tool.parameters.amount }} refund。

完整配置模式、各平台设置以及多渠道审批人模式，请参阅 references/HUMAN_REVIEW.md。

输出解析：何时以及如何使用

当下游需要结构化数据而非自由文本时，添加 outputParser 子节点。

const parser = outputParser({
    type: '@n8n/n8n-nodes-langchain.outputParserStructured',
    config: {
        parameters: {
            schemaType: 'manual',
            inputSchema: JSON.stringify({
                type: 'object',
                properties: {
                    score: { type: 'integer', minimum: 1, maximum: 5 },
                    category: { type: 'string', enum: ['bug', 'feature', 'question'] },
                    reason: { type: 'string' },
                    tags: { type: 'array', items: { type: 'string' } },
                },
                required: ['score', 'category', 'reason'],
            }),
            autoFix: true,
            customizeRetryPrompt: true,
            prompt: '...retry instructions...', // generally leave as default
        },
        subnodes: {
            languageModel: fixerModel,    // coding-capable model, e.g. Claude Sonnet 4.6
        },
    },
})

1. 使用 schemaType: 'manual' 和真实的 JSON schema，而不是 jsonSchemaExample。 示例无法表达可选字段、枚举、取值范围或数组约束，因此数据结构一旦稍微复杂，你很快就会发现它不够用。Schema 可以标记必填字段和可选字段、定义枚举、限制数字取值和字符串格式，并为模型提供更明确的规则。只有在一次性使用且确定结构永远不会增加约束时，才考虑使用带示例的 schemaType: 'fromJson'。
2. autoFix: true 会在解析失败时重试。 将具备编码能力的模型连接为修复器子节点（例如 Claude Sonnet 4.6 或类似模型）。根据 Schema 修复格式错误的 JSON 属于结构化输出／编码任务；能力较弱或通用型模型往往会再次生成格式错误的重试结果，反而达不到预期效果。

包含自定义重试提示词的完整模式，请参阅 references/STRUCTURED_OUTPUT.md。

记忆：简要概念模型

• 无记忆： 无状态。适用于一次性任务（分类、摘要）。
• memoryBufferWindow： 为每个记忆键保留最近的 N 条消息，并通过 n8n 的内部存储跨执行持久化。键由绑定到 sessionKey 的表达式决定。聊天触发器会自动填入 sessionId，但你也可以使用任何值作为键（Slack 的 thread_ts、webhook 对话 ID，或多租户组合键）。这是聊天记忆的默认选项。“窗口”限制的是保留在上下文中的消息数量，而不是持久化范围。
• memoryPostgres / memoryRedis / 类似方案： 当你需要在 Agent 之外查询或读取记忆时，使用这些方案：在自有 UI 中显示对话历史、分析过往聊天，或与其他系统共享记忆。否则，memoryBufferWindow 就足够了。

请始终将触发器中的稳定键传递给记忆，否则不同对话可能会串在一起。请参阅 references/MEMORY.md。

RAG（检索增强生成）

n8n 提供 LangChain 的 RAG 基础组件：文档加载器、文本分割器、嵌入、向量存储、检索器、重排器。这些组件可以协同工作，但一站式端到端方案（“用哪个向量存储、如何分块、何时重排”）在很大程度上取决于数据形态和规模。

本技能有意保持对 RAG 的建议精简。如需详细了解 RAG，请参阅 references/RAG.md。

参考文件

文件	阅读时机
references/TOOLS.md	为 Agent 添加工具、在四种工具类型中进行选择、编写工具名称和描述时
references/SUBWORKFLOW_AS_TOOL.md	通过 toolWorkflow 将子工作流接入为 Agent 工具、映射 fromAi 覆盖值时
references/SYSTEM_PROMPT.md	编写或重构系统提示词、决定哪些内容放入系统提示词而非工具描述时
references/STRUCTURED_OUTPUT.md	强制输出 JSON、配置 autoFix 重试、验证下游内容时
references/MEMORY.md	选择记忆类型、处理持久化和 sessionId 时
references/RAG.md	构建检索增强型 Agent；本文有意仅作简介
references/HUMAN_REVIEW.md	为工具添加人工审批、配置审批消息、设置多渠道审批者模式时
references/CHAT_SURFACE_PATTERNS.md	在 Slack、Discord、Teams、Telegram 或任何自定义聊天界面上构建聊天机器人工作流：外壳 + 核心 + 子 Agent，包括通过 Message an Agent 将 Agent 作为核心的一等方案

反模式

反模式	问题所在	修复方法
通用工具名称（doStuff、runQuery）	模型无法判断该选择哪个工具，会跳过它们或幻觉出参数	使用动词开头的具体名称：Search customer database、Generate image with Veo
空的或只有一行的工具描述	模型完全不知道何时调用，导致选择不当	编写完整描述：说明工具的功能、使用时机和参数含义
把所有内容都塞进系统提示词	提示词臃肿、无法复用，针对每个工具的指导也被埋没	将针对工具的说明移到工具描述中，系统提示词只保留角色设定和全局规则
本可使用子工作流却用了代码节点工具	无法复用、不能独立测试，也无法与分支组合	使用 toolWorkflow，并创建合适的子工作流
直接向工具传递二进制数据	无法正常工作，二进制数据不能跨越工具边界	预先存入存储，通过 fromAi 传递密钥，让工具在内部获取。参见 n8n-binary-and-data-official
使用 outputParserStructured 却未设置 autoFix	模型一次输出不佳就会导致工作流失败	将 autoFix 设为 true，并使用低成本修复模型
硬编码 sessionId 或不提供 sessionId	对话会串线，或记忆始终无法匹配	将 sessionId 从触发器一致地传递给记忆和工具
用两个近乎相同的工具，而不是一个带分支的工具	模型会困惑，选择结果不确定	使用一个由参数驱动内部逻辑分支的工具
对多个工作流复用或经常迭代的系统提示词进行硬编码	编辑后必须重新发布，无法在工作流间共享，调整内容散落在节点 JSON 中	将提示词存储在 Data Table 中，并在运行时加载
将图像／音频／视频生成封装在 Agent 中	二进制数据无法通过工具或输出格式化器传递，Agent 只会增加节点而无实际收益	直接使用提供商原生的单次调用节点（OpenAI Image、Gemini Image、ElevenLabs）；只有通过聚合器时才使用 HTTP Request
使用 Agent + Switch 来路由自然语言输入	本可由一个具有 N 个内置输出分支的 Text Classifier 完成，却用了两个节点并添加了提示词样板内容	使用 Text Classifier（@n8n/n8n-nodes-langchain.textClassifier），每个类别都有自己的输出端口，直接连接下游路径
会更改用户可见状态（发送、支付、退款）却未经过人工审核的工具	Agent 可能因错误推断触发不可逆操作	使用适合相应渠道的审核工具节点（Slack/Chat/Discord/Telegram）进行封装，并通过 $tool.parameters 展示实际参数
使用 fromAi() 填写审核批准消息	模型会进行转述，导致你批准的是文本而非实际值	直接使用 $tool.parameters.<name>，以便看清实际调用内容
聊天触发的 Agent 工作流发布回复时，未过滤掉机器人自己的用户 ID	机器人的消息会再次触发工作流，形成无限循环，持续消耗运行次数和令牌，直到触及速率限制或被 n8n 并发限制拦截	条件允许时优先在触发器层过滤（Slack Trigger 的 options.userIds 是排除列表，请将机器人 ID 放入其中）。否则，在触发器后的第一个节点中使用 $json.user !== '<BOT_USER_ID>'（或相应平台的等效写法）进行过滤。对于任何会发送回复的聊天触发工作流（Slack、Discord、Teams、Telegram），无论复杂程度如何，都必须进行过滤。各平台的具体语义参见 references/CHAT_SURFACE_PATTERNS.md
Agent 返回 Block Kit 时，直接将原始 blocks 数组传给 Slack 节点的 blocksUi	Slack 节点会静默接受输入，却只发送没有富文本内容的消息；既不会报错，也不会警告	使用 { "blocks": [...] } 封装，并确保其值是真正的数组，而不是字符串化的数组。表达式：={{ { "blocks": $('Agent').item.json.output.blocks } }}。参见 n8n-node-configuration-official 中的 references/COMMS_NODES.md“Block Kit messages”