n8n 中文教程：AI 代理（AI Agent）

大家好，我是翔宇，一个在自动化领域摸爬滚打多年的实践者，也是 “翔宇工作流” 的作者。在日常的工作中，我们经常会遇到一些简单的、重复性的任务，通过 n8n 的常规节点连接，可以轻松实现自动化，解放双手。但随着业务需求的深入，我们常常会面临更复杂的挑战：比如，需要系统能够理解模糊的用户请求，根据不同的情况调用不同的工具或服务，甚至需要与外部知识库进行交互来获取最新信息。这些任务往往超出了传统预设逻辑节点的处理能力，需要更智能、更灵活的解决方案。

想象一下，一个普通的 n8n 工作流就像一条预先设定好程序的工厂流水线，每个节点按部就班地执行固定任务。但是，如果我们希望这条流水线能够根据产品的不同、物料的变化或者突发状况，智能地调整工序、调用不同的机器（工具）来处理，那该怎么办呢？这时候，我们就需要一位“聪明的工厂管理者”——这就是 n8n 中 AI Agent 节点扮演的角色。

AI Agent 节点是 n8n 迈向智能化自动化的一大步。它赋予了工作流“思考”的能力，让它不再仅仅是指令的执行者，更能成为一个能够理解意图、制定计划、调用工具并最终达成目标的智能代理。无论是构建能与用户进行深度对话的智能客服，还是打造能自动研究分析、处理数据的智能助手，AI Agent 节点都为我们打开了全新的可能性。

本教程旨在为零代码基础的 n8n 用户提供一份全面而深入的 AI Agent 节点指南。我们将从基础概念出发，详细拆解节点的各项配置、参数，深入探讨其核心组件——工具（Tool）、聊天模型（Chat Model）和记忆（Memory）的使用方法，并结合翔宇在实战中的理解和经验，分享常见的应用场景、错误排查技巧以及使用注意事项。

通过本教程，你将学习到：

AI Agent 节点的核心功能与价值定位。
节点的各项参数配置及其在不同场景下的推荐设置。
如何利用表达式，特别是 $fromAI() 函数，实现动态数据映射。
AI Agent 支持的各种工具（Tools）的详细介绍与配置方法。
如何选择和配置合适的聊天模型（Chat Models）。
如何为你的 AI Agent 配置记忆（Memory）以实现上下文感知。
AI Agent 的常见应用场景实例。
常见的错误类型、排查思路和调试技巧。
使用 AI Agent 节点时的重要注意事项和版本兼容性。

无论你是想构建一个简单的智能问答机器人，还是希望实现更复杂的业务流程自动化，本教程都将为你提供坚实的基础和实用的指导。让我们一起探索 n8n AI Agent 的强大功能，开启智能自动化的新篇章！

目录隐藏

1 节点概览

2 参数与配置

3 数据映射与表达式

4 工具 Tool

5 Chat Model

6 Memory

7 应用场景

8 常见报错及解决方案

9 注意事项

节点概览

节点功能定位与核心价值

n8n 中的 AI Agent 节点，可以理解为工作流中的“智能大脑”或“指挥中心” 。它的核心功能定位是接收输入信息（通常是用户的请求或指令），理解其意图，然后自主地决定采取哪些步骤、调用哪些连接的“工具”（Tools）来完成指定的任务，并最终生成一个结果或响应。

与 n8n 中其他按固定顺序执行任务的节点不同，AI Agent 节点的核心价值在于其动态决策和适应性。它不是简单地遵循预设的线性流程，而是能够：

理解自然语言： 能够解析用户的自然语言输入，理解其背后的意图。
规划与推理： 根据用户的请求和自身的配置（尤其是系统消息中的指令），规划出完成任务所需的步骤。
工具使用： 智能地选择并调用连接到其“Tool”接口的各种工具（如 API 请求、数据库查询、文件操作、其他 n8n 节点等）来获取信息或执行动作。
整合信息： 将从工具获取的信息或执行结果进行整合，并生成最终的响应。

重要更新：统一为 Tools Agent

需要特别指出的是，为了简化使用和聚焦核心能力，从 n8n 版本 1.82.0 开始，所有新添加的 AI Agent 节点都默认并且仅作为“Tools Agent”（工具代理）运行 。在此之前的版本中，AI Agent 节点允许用户选择不同的 Agent 类型（如 Conversational Agent, ReAct Agent, SQL Agent 等）。虽然这些旧的类型在现有工作流中可能仍然可见或可以运行，但官方已经将它们标记为“已弃用”（Deprecated），并且不再推荐在新工作流中使用。

这一变化对于初学者来说是一个好消息，因为它极大地降低了入门的复杂度。用户不再需要在多种看似相似的 Agent 类型之间选择，只需专注于理解 Tools Agent 的核心机制——即如何通过连接和配置不同的“工具”来赋予 Agent 完成特定任务的能力。这种统一也反映了 n8n 团队认为 Tools Agent 模式是最通用和最强大的范式，足以涵盖之前各种 Agent 类型的主要应用场景。因此，本教程将完全聚焦于当前标准的 Tools Agent 进行讲解。

与 Chain（链）节点的区别

为了更好地理解 AI Agent 的定位，可以简单对比一下 n8n 中的另一类 AI 节点——Chain（链）节点（例如 Question and Answer Chain）。Chain 节点通常遵循一个预先定义的、固定的步骤序列来处理信息，比如“接收问题 -> 从向量数据库检索信息 -> 将问题和信息发送给 LLM -> 返回答案”。而 Agent 节点则不同，它会根据输入和上下文动态地决定下一步是直接回答，还是调用某个工具，或者调用哪个工具。这种决策能力是 Agent 的核心价值所在。

核心价值总结

AI Agent 节点的核心价值在于，它让 n8n 工作流能够超越简单的、预设的自动化逻辑，实现更高级别的智能：

构建交互式应用： 如智能聊天机器人、虚拟客服、问答系统等。
执行复杂任务： 如根据用户指令自动完成研究、分析数据、生成报告、操作外部系统等。
增强适应性： 工作流能够根据不同的输入和情况，动态调整其行为。

输入（Input）与输出（Output）数据结构

理解 AI Agent 节点的输入和输出对于将其有效地集成到工作流中至关重要。

输入（Input）

AI Agent 节点通常需要一个主要的输入，即用户的请求或提示（Prompt） 。这个输入决定了 Agent 需要完成什么任务。

来源： 这个输入通常来自工作流中的上一个节点，最常见的是触发器节点，例如：
- Chat Trigger: 当用户通过 n8n 内建的聊天界面或嵌入式聊天窗口发送消息时，Chat Trigger 会将消息内容传递给 Agent。
- Webhook Trigger: 可以接收来自外部应用（如自定义前端、其他服务）的 HTTP 请求，请求体中通常包含用户的输入信息。
- 消息类触发器: 如 Telegram Trigger, Slack Trigger, Discord Trigger 等，接收来自这些平台的消息。
- 其他节点: 任何能够输出文本或包含用户请求的 JSON 数据的节点都可以作为 Agent 的输入源。
数据格式：
- 自动获取 (Take from previous node automatically): 如果在 Agent 的 Prompt 参数中选择此项，节点会期望上一个节点的输出中包含一个名为 chatInput 的字段，该字段的值将被用作用户提示。
- 手动定义 (Define below): 如果选择此项，用户可以在 Prompt (User Message) 字段中直接输入静态文本，或者使用 n8n 表达式从上一个节点的输出中提取数据。输入可以是简单的字符串，也可以是包含用户消息和其他上下文信息的 JSON 对象。例如，可以传入一个包含 {"user_message": "你好", "user_id": "123"} 的 JSON 对象。
二进制数据（图像）： Tools Agent 还提供了一个选项 Automatically Passthrough Binary Images，开启后，如果输入数据包含二进制图像文件，Agent 可以将其作为图像类型的消息进行处理。

输出（Output）

AI Agent 节点的输出是其完成任务后的最终结果。由于 Agent 可能需要经过多轮思考和工具调用，其输出结构可能比普通节点更复杂。

基本输出： 最常见的是 Agent 生成的最终文本响应。这通常是回答用户的问题、任务完成的确认信息或生成的内容。
中间步骤 (Return Intermediate Steps): 如果开启了 Return Intermediate Steps 选项，输出结果会包含 Agent 内部执行的详细步骤。这对于调试非常有用，因为它展示了 Agent 的“思考过程”，包括：
- 它调用了哪些工具（Action）。
- 传递给工具的输入是什么（Action Input）。
- 工具返回了什么结果（Observation）。
- Agent 对此的思考（Thought）。
- 翔宇的提醒： 对于初学者来说，理解这个包含中间步骤的输出结构可能有些困难。建议在开发和调试阶段开启此选项，以便了解 Agent 的行为；但在生产环境中，如果不需要这些调试信息，可以关闭它，以简化输出数据，减少后续节点处理的复杂度。
结构化输出 (Require Specific Output Format): 如果开启了 Require Specific Output Format 并连接了相应的 Output Parser（输出解析器），Agent 的最终输出会被强制要求符合预定义的 JSON 结构。这对于需要将 Agent 输出传递给后续节点进行自动化处理（例如，将提取的信息存入数据库）的场景至关重要。输出通常会包含一个名为 output 或类似名称的字段，其值为符合指定结构的 JSON 对象。
错误输出 (On Error): 与 n8n 的其他节点类似，AI Agent 节点也有错误处理设置。如果选择 Continue (using error output)，当节点执行出错时，错误信息会作为输出传递给下一个节点。

总的来说，AI Agent 的输入主要是用户的请求，而输出则是 Agent 处理后的结果，其结构可能包含最终响应、详细的中间步骤（用于调试）或强制的结构化数据（用于后续处理）。

参数与配置

配置 AI Agent 节点是定义其行为和能力的关键步骤。理解每个参数的含义和作用，对于构建出稳定、高效且符合预期的智能工作流至关重要。

核心参数详解

这两个参数是 AI Agent 节点最基础也是最重要的配置：

Prompt (提示): 这个参数定义了 Agent 接收到的主要用户输入或任务指令。它有两种设置方式：
- Take from previous node automatically (自动从上一个节点获取): 这是最常用的方式，尤其是在对接 Chat Trigger 或其他标准输入源时。选择此项后，Agent 会自动查找并使用上一个节点输出数据中名为 chatInput 的字段作为用户的提示信息。
  - 翔宇的实战理解: 这是构建聊天机器人的标准做法。确保你的触发器节点（如 Chat Trigger）或其他输入节点正确地输出了包含用户消息的 chatInput 字段。
- Define below (在下方定义): 选择此项后，会出现一个 Prompt (User Message) 文本框。你可以在这里输入：
  - 静态文本: 直接输入固定的指令或问题。
  - n8n 表达式: 使用 {{ }} 语法动态地从上一个节点或其他地方获取数据，并将其组合成提示。例如，你可以写 请总结这封邮件的主要内容：{{ $('Get Email Node').item.json.body }}，这样 Agent 就会收到包含邮件正文的总结请求。
  - 翔宇的实战理解: 当你需要更精细地控制 Agent 收到的初始指令，或者需要将多个来源的数据组合成一个提示时，Define below 非常有用。例如，你可以结合用户的请求和一些背景信息一起发送给 Agent。
Require Specific Output Format (要求特定输出格式): 这是一个开关选项。默认关闭。当你开启此选项时，n8n 会强制要求你连接一个Output Parser (输出解析器) 子节点到 AI Agent 节点。支持的解析器包括：
- Structured Output Parser (结构化输出解析器): 最常用的一种，允许你定义一个期望的 JSON 结构（通过提供一个 JSON 示例），Agent 会被指示按照这个结构来格式化其最终输出。
- Auto-fixing Output Parser (自动修复输出解析器): 尝试自动修复不符合预期格式的输出。
- Item List Output Parser (项目列表输出解析器): 用于期望输出一个项目列表的场景。
- 翔宇的实战理解: 这个选项极其重要！大型语言模型（LLM）虽然强大，但它们的输出格式有时并不稳定或完全符合预期。如果你需要将 Agent 的输出（比如提取的关键信息）可靠地传递给后续节点（如数据库节点、表格节点）进行处理，强烈建议开启此选项并使用 Structured Output Parser。通过提供一个清晰的 JSON 示例，你可以大大提高 Agent 输出结构化数据的可靠性，减少因格式错误导致工作流失败的可能性。这对于需要稳定运行的生产环境尤为关键。

Node Options (节点选项)

点击节点设置界面下方的 “Add Option” 按钮，可以选择添加以下选项来进一步微调 Agent 的行为：

System Message (系统消息): 这是向 Agent 提供持久性指令、上下文或角色设定的地方。这里的指令会在 Agent 的每次思考或与模型交互时都被考虑在内。
- 作用:
  - 定义角色/身份: “你是一个专业的旅游顾问…”
  - 设定目标: “你的任务是帮助用户找到合适的航班信息。”
  - 施加约束: “回答必须简洁，不要超过三句话。”, “绝对不能提供财务建议。”
  - 指导工具使用: “当用户询问天气时，必须使用 ‘Weather Tool’。”, “优先使用 ‘Database Tool’ 查询用户信息，如果查不到再使用 ‘Web Search Tool’。”
- 翔宇的实战理解: 系统消息是塑造 Agent 行为的关键。写好系统消息是成功构建 Agent 的一半。指令需要清晰、明确、无歧义。特别是关于工具使用的指令，一定要写清楚何时使用哪个工具，以及如何处理工具的输出。过于模糊的指令会导致 Agent 混乱、不使用工具或错误地使用工具。同时，也要注意指令的详细程度，过于冗长和复杂的指令也可能让模型难以完全遵循。需要反复测试和调整。
Max Iterations (最大迭代次数): 设置 Agent 在尝试生成最终答案的过程中，最多可以执行的内部循环次数（包括调用模型进行思考、选择工具、调用工具、处理工具结果等步骤）。默认值为 10 。
- 作用: 防止 Agent 因无法找到答案或陷入逻辑困境而无限循环，同时也限制了单次执行可能产生的 API 调用成本。
- 翔宇的实战理解: 对于简单的问答任务，默认值 10 通常足够。但对于需要多次调用工具、进行多步推理的复杂任务，可能需要适当增加此值。如果 Agent 经常因为达到最大迭代次数而失败，检查你的系统消息、工具描述是否清晰，或者任务本身是否过于复杂，需要拆分成更小的步骤。
Return Intermediate Steps (返回中间步骤): 一个开关选项，默认关闭。开启后，Agent 的最终输出会包含其内部执行的详细步骤（思考过程、工具调用及结果等）。
- 作用: 主要用于调试。通过查看中间步骤，可以清晰地了解 Agent 是如何做出决策、调用了哪些工具、工具返回了什么，从而诊断出 Agent 行为不符合预期的原因。
- 翔宇的实战理解:开发和调试阶段强烈建议开启！ 这是理解 Agent 为何“犯错”的最直接方式。例如，你可以看到 Agent 是否选择了正确的工具，传递给工具的参数是否正确，以及它如何理解工具返回的结果。一旦 Agent 运行稳定，进入生产环境后，如果不需要这些详细日志，可以关闭此选项，以简化输出数据结构，减少数据传输量。
Automatically Passthrough Binary Images (自动传递二进制图像): 一个开关选项，默认关闭。开启后，如果输入数据包含二进制图像文件，Agent 会将其作为图像类型的消息传递给支持多模态输入的聊天模型（如 GPT-4o, Gemini Pro Vision 等）。
- 作用: 使 Agent 能够理解和处理图像内容。
- 翔宇的实战理解: 这是实现图像问答、图像分析等场景的基础。需要配合支持视觉能力的聊天模型使用。

默认值与可选值

Prompt: 默认 Take from previous node automatically。
Require Specific Output Format: 默认关闭。
Max Iterations: 默认 10。
Return Intermediate Steps: 默认关闭。
Automatically Passthrough Binary Images: 默认关闭。

不同场景的推荐配置

根据不同的应用场景，可以参考以下配置建议：

场景一：简单的问答机器人（不使用工具）
- Prompt:Take from previous node automatically (连接 Chat Trigger)。
- Require Specific Output Format: 关闭。
- System Message: 定义机器人的角色和回答风格（例如：“你是一个友好的人工智能助手，请简洁地回答用户的问题。”）。
- Max Iterations: 可以考虑适当调低（例如 5），因为不需要工具调用。
- Return Intermediate Steps: 关闭。
- Chat Model: 选择性价比较高的模型即可（如 GPT-4o-mini, Gemini Flash）。
场景二：需要调用外部工具获取信息的 Agent（例如，查询天气、搜索网页）
- Prompt:Take from previous node automatically 或 Define below（如果需要组合输入）。
- Require Specific Output Format: 通常关闭，除非需要结构化输出工具结果。
- System Message:非常重要！ 必须清晰定义 Agent 的目标，并明确指示何时、如何使用连接的工具（例如：“当用户询问天气时，必须使用 ‘Get_Weather’ 工具，并将城市名作为输入。”）。
- Max Iterations: 保持默认 10 或根据工具调用的复杂性适当增加。
- Return Intermediate Steps:开发阶段开启，用于调试工具调用；生产环境可关闭。
- Chat Model: 建议选择工具使用能力较强的模型（如 GPT-4o, Claude 3.5 Sonnet）。
- Tools: 连接所需的工具节点（如 HTTP Request Tool 获取天气 API，SerpApi Tool 搜索网页）。
场景三：需要提取结构化信息并输出的 Agent（例如，从邮件中提取订单信息）
- Prompt:Take from previous node automatically 或 Define below。
- Require Specific Output Format:开启。
- Output Parser: 连接 Structured Output Parser，并在其中提供清晰的 JSON 示例，定义需要提取的字段及其类型。
- System Message: 定义 Agent 的任务（提取信息），并强调必须按照指定的 JSON 格式输出结果。
- Max Iterations: 保持默认 10。
- Return Intermediate Steps: 开发阶段开启，生产环境可关闭。
- Chat Model: 选择能够较好理解并遵循格式指令的模型。
- Tools: 可能不需要外部工具，或者连接用于获取原始文本的工具（如 Gmail Tool）。

通过理解并灵活运用这些参数和选项，你可以有效地引导 AI Agent 的行为，构建出满足特定需求的智能自动化工作流。记住，清晰的指令（尤其是 System Message 和 Tool Description） 和 充分的测试 是成功的关键。

数据映射与表达式

在 n8n 中，表达式是实现动态数据处理和节点间数据传递的核心机制。对于 AI Agent 节点及其连接的工具来说，熟练掌握表达式的写法和数据映射技巧尤为重要，它能让你的智能代理更加灵活和强大。

n8n 表达式基础

n8n 的表达式主要基于 JavaScript，并进行了一些扩展，让你能够方便地访问工作流中的各种数据。

基本语法: 所有 n8n 表达式都必须包裹在双大括号 {{ }} 中。
访问上一个节点的数据 ($json): 这是最常用的变量。它代表上一个节点输出的第一个数据项（Item）的 JSON 内容。你可以使用点 . 或方括号 “ 来访问其内部的属性。
- 示例：如果上一个节点输出 {"user": {"name": "翔宇", "city": "北京"}}，你可以用 {{ $json.user.name }} 或 {{ $json.user['city'] }} 来获取 “翔宇” 或 “北京”。
访问当前节点的参数 ($parameter): 可以获取当前节点配置界面中设置的参数值。
- 示例：在一个 HTTP Request 节点中，如果 URL 参数名为 url，你可以用 {{ $parameter.url }} 来引用它。
访问环境变量 ($env): 获取在 n8n 实例中配置的环境变量，常用于存储 API 密钥等敏感信息。
- 示例：获取名为 OPENAI_API_KEY 的环境变量：{{ $env.OPENAI_API_KEY }}。
访问特定节点的数据: 这是非常强大的功能。你可以通过节点名称来访问任意上游节点的输出数据。
- 访问第一个数据项:{{ $('节点名称').item.json.字段名 }}。这里的 节点名称 需要替换成你实际的节点名称（可以在节点设置中修改）。
- 访问所有数据项:{{ $('节点名称').all() }} 会返回一个包含该节点所有输出项的数组。你可以配合 JavaScript 的数组方法（如 .map(), .filter()）进行处理。例如，获取所有项的 email 字段：{{ $('节点名称').all().map(item => item.json.email) }}。
- 翔宇的实战理解: 给节点起一个清晰易懂的名称（比如 “获取邮件内容” 而不是默认的 “Gmail1″）对于后续使用表达式引用其数据至关重要。
内置方法和变量: n8n 提供了一些方便的内置方法和变量。
- DateTime: 用于处理日期和时间（基于 Luxon 库），例如 {{ DateTime.now().toISODate() }} 获取当前日期。
- $execution: 获取当前工作流执行的相关信息。
- 其他数据转换函数: n8n 还内置了许多用于字符串、数字、数组、对象操作的函数，可以在表达式编辑器中直接使用（输入 . 后会提示）。

AI Agent 节点中的表达式应用

表达式在 AI Agent 节点及其生态系统（工具、模型、记忆）中扮演着关键角色：

动态 Prompt: 当 Prompt 参数设置为 Define below 时，你可以使用表达式将来自上游节点的数据动态地插入到给 Agent 的指令中。
- 示例：请根据以下用户信息回答问题：姓名 - {{ $('获取用户信息').item.json.name }}，城市 - {{ $('获取用户信息').item.json.city }}。用户的问题是：{{ $json.chatInput }}
动态 System Message: 同样，System Message 也可以使用表达式来动态调整 Agent 的行为指令。
- 示例：你正在为用户 {{ $('获取用户信息').item.json.name }} 提供服务，请称呼他/她为 {{ $('获取用户信息').item.json.nickname }}。
动态工具参数: 这是表达式最重要的应用场景之一。当你将 App Node（如 Gmail, Google Sheets 等）作为工具连接到 AI Agent 时，这些工具节点的参数（如收件人地址、表格名称、搜索关键词等）可以使用表达式进行设置。这使得 Agent 能够根据上下文动态地操作这些工具。
- 示例（在 Gmail 工具的 “To Email” 字段）：{{ $('提取收件人').item.json.email }}
- 更强大的方式是结合 $fromAI() 函数，让 AI 自己决定参数值（详见下一节）。

动态参数 `$fromAI()` 函数详解

$fromAI() 函数是 n8n 中实现 AI Agent 动态工具参数填充的核心机制，值得重点掌握。

用途: 它的核心作用是授权 AI 模型根据当前的对话上下文和任务目标，自主决定并填充某个工具节点的特定参数值 。这与普通表达式不同，普通表达式是从已有的数据中取值，而 $fromAI() 是让 AI 生成或推断出参数值。这极大地增强了 Agent 使用工具的灵活性和智能性。
语法: 基本语法如下： {{ $fromAI('key', 'description', 'type', 'defaultValue') }}
- key (字符串, 必需): 参数的唯一标识符或名称。这是给 AI 的一个“提示”，告诉它需要填充的是哪种类型的信息。长度 1-64 字符，只能包含字母、数字、下划线、连字符。例如：'recipient_email', 'search_term', 'file_name'。
- description (字符串, 可选): 对该参数的描述，帮助 AI 模型更好地理解参数的含义和用途。例如："需要发送邮件的收件人邮箱地址", "用户想要搜索的关键词"。
- type (字符串, 可选): 指定期望的数据类型。可选值为 'string', 'number', 'boolean', 'json'。默认为 'string'。
- defaultValue (任意类型, 可选): 备用值。如果 AI 模型无法根据上下文确定合适的参数值，将使用此默认值。
工作原理 (翔宇的比喻): 想象你对一位真人助手说：“帮我给客户发封邮件，主题是‘会议纪要’，收件人你找一下。” 这里的“收件人你找一下”就类似于 $fromAI('recipient_email')。你没有直接告诉助手邮箱地址，而是让他根据当前的语境（比如你们正在讨论哪个客户）自己去查找或推断出正确的邮箱地址。key (‘recipient_email’) 就像是告诉助手你需要的是“邮箱地址”这个信息。
UI 快捷方式: 在 App Node 工具的参数配置界面，很多字段右侧会有一个星形图标（”Let the model fill in the parameter”）。点击这个图标，n8n 会自动在该字段中填入一个基本的 $fromAI('key') 表达式（key 通常是基于参数名称自动生成的）。这是一个非常方便的起点，你可以随后点击输入框旁边的 ‘X’ 切换回表达式模式，进一步编辑这个表达式，比如添加 description 或 defaultValue。
重要限制:$fromAI() 函数目前仅适用于连接到 Tools Agent 的 App Node 工具（如 Gmail, Google Sheets, Slack 等）。它不能用于核心的 Cluster Sub-node 工具，例如 Call n8n Workflow Tool, Code Tool, HTTP Request Tool 。
- 翔宇的踩坑提醒: 这是初学者非常容易遇到的一个“坑”。很多用户尝试在 HTTP Request Tool 的 URL 或 Body 中使用 $fromAI() 来动态构建请求，结果发现它并不生效。记住这个限制可以避免很多不必要的尝试和困惑。这可能是因为 $fromAI() 的实现依赖于 n8n 对标准 App Node 的深度集成，而这种集成方式对于更通用的核心工具来说比较困难。如果确实需要在这些核心工具中使用 AI 动态生成的参数，目前的变通方法可能是在 Agent 之前的节点（例如 Code 节点或另一个 LLM 调用）中让 AI 生成所需的参数，然后通过普通表达式将这些参数传递给核心工具节点。
使用示例:
- 在 Send Email 工具的 To Email 字段: {{ $fromAI('recipient_email', '收件人的邮箱地址') }}
- 在 Google Sheets 工具的 Sheet Name 字段: {{ $fromAI('sheet_name', '需要操作的表格名称', 'string', '默认表单') }}
- 在 HTTP Request 工具的 URL 字段 (注意：根据上述限制，直接使用 $fromAI() 可能无效，这里仅作语法演示): https://api.example.com/data?query={{ $fromAI('search_query') }} (实际使用中可能需要变通方法)
- 组合使用：在 Send Email 工具的 Subject 字段: AI 生成的主题：{{ $fromAI('email_subject') }}

映射技巧与常见易错点

在使用表达式，尤其是与 AI Agent 交互时，需要注意以下几点：

易错点 1: 理解 Agent 输出结构: 当 Return Intermediate Steps 开启时，Agent 的输出会变得复杂，包含多层嵌套的 steps 或 intermediateSteps 数据。直接用简单的 $json.output 可能无法获取到最终的文本响应。你需要仔细检查实际的输出数据结构（在 n8n 的执行结果视图中），找到最终响应所在的路径，然后使用正确的表达式来提取，例如 {{ $json.output }} 或 {{ $json.result }} 或更深层级的路径。
易错点 2: $fromAI() 的限制: 再次强调，不要尝试在 Call n8n Workflow, Code, HTTP Request Tool 中直接使用 $fromAI()，它不会按预期工作。
易错点 3: 表达式语法错误: 括号 {{ }} 是否闭合，属性访问的点 . 或方括号 “ 是否使用正确，函数调用是否规范等。微小的语法错误都会导致表达式执行失败。
易错点 4: 处理 null 或 undefined: 当表达式引用的上游数据不存在时（例如，一个可选的邮件附件字段为空），表达式可能会返回 null 或 undefined，这可能导致后续节点（包括 AI Agent）出错。虽然对于零代码用户来说比较复杂，但健壮的工作流有时需要检查数据是否存在，例如使用 IF 节点进行判断，或者在表达式中使用默认值（如 {{ $json.optionalField | | '默认值' }}）。
技巧 1: 使用节点重命名: 给你的节点起有意义的名字（例如 “获取邮件内容” 而不是 “Gmail1”），这样在后续节点中引用它们时 $('获取邮件内容').item.json... 会更清晰易懂。
技巧 2: 善用表达式编辑器: n8n 的表达式编辑器提供了语法高亮和自动建议功能。输入 $ 或 {{ 后，它会提示可用的变量和函数，减少拼写错误。对于复杂表达式，可以在编辑器中测试其输出。
技巧 3: 单独测试: 在将表达式用于 AI Agent 或其工具之前，可以在一个简单的 Set 节点中测试表达式，确保它能正确地提取或生成你想要的数据。

掌握 n8n 表达式和 $fromAI() 函数是精通 AI Agent 节点的关键一步。通过实践和注意上述技巧与易错点，你将能够构建出更加动态和智能的自动化流程。

工具 Tool

工具（Tool）是 AI Agent 节点的核心组成部分，可以说是 Agent 的“手”和“脚”，赋予了它与外部世界交互、执行具体任务的能力。没有工具，Agent 就只是一个空有“大脑”（聊天模型）但无法行动的实体。本节将深入探讨 n8n AI Agent 支持的工具。

工具 (Tool) 的概念与作用

在 AI Agent 的语境中，“工具”具有特定的含义。它不是指 n8n 界面上的某个按钮或功能，而是指 Agent 可以调用来完成特定子任务的接口或功能模块 。

定义: 工具是 AI Agent 用来与“世界”互动（包括获取信息、执行操作）的接口。你可以把它们想象成 Agent 可以调用的“函数”或“API” 。
作用:
- 扩展知识: 让 Agent 能够访问其训练数据之外的实时信息（如通过搜索引擎、API 获取最新数据）。
- 执行动作: 让 Agent 能够操作外部系统（如发送邮件、在数据库中增删改查、在项目管理工具中创建任务）。
- 执行计算: 让 Agent 能够执行精确的数学运算（LLM 本身不擅长精确计算）。
- 运行代码/工作流: 执行自定义逻辑或复用现有的 n8n 工作流。
重要性: 工具是实现 AI Agent 实用价值的关键。正是因为有了工具，Agent 才能将理解和推理能力转化为实际的行动和结果，完成复杂的自动化任务。
翔宇的比喻: 再次回到“工厂管理者”（Agent）和“专业工人”（Tool）的比喻。当管理者接到一个生产任务（用户请求），他会分析任务需求，然后指示相应的专业工人（比如操作切割机的工人 Tool A，操作焊接机的工人 Tool B，负责质检的工人 Tool C）按顺序或并行地完成各自的工序，最终产出合格的产品（最终响应）。
连接方式: 在 n8n 中，工具节点需要连接到 AI Agent 节点底部的专用 “Tool” 输入连接器上。你可以连接一个或多个工具。

支持的工具分类

n8n AI Agent 支持的工具种类繁多，可以大致分为以下几类：

核心工具 (Core Tools / Cluster Sub-nodes): 这是 n8n AI 框架内置的、功能强大的通用型工具。它们通常作为 AI Agent 的子节点存在，提供了基础但关键的能力。
App Node 工具 (Nodes as Tools): 这是 n8n 的一个重要特性（自 v1.62.1 引入）。它允许你将许多标准的 n8n 应用节点（如 Gmail, Google Sheets, Slack, MySQL, Postgres, HubSpot 等）直接作为工具连接到 AI Agent 。这极大地扩展了 Agent 的能力，使其能够轻松地与数百种服务进行交互。
其他 LangChain 工具: n8n 的 AI 功能基于 LangChain 框架构建，因此也集成了一些 LangChain 生态中常用的、独立的工具，如 Calculator（计算器）、Wikipedia（维基百科查询）、SerpApi（谷歌搜索）等。

核心工具详解

以下是三个最核心、最通用的内置工具，它们为 AI Agent 提供了基础的扩展能力：

Call n8n Workflow Tool (调用 n8n 工作流工具)

简介/作用: 这个工具允许你的 AI Agent 调用并执行另一个完整的 n8n 工作流，并将该子工作流的最终输出作为结果返回给 Agent 。
- 价值:
  - 模块化: 可以将复杂的任务拆分成独立的、可复用的子工作流，让主 Agent 逻辑更清晰。
  - 复用性: 已经构建好的工作流（例如，一个复杂的数据处理流程）可以直接被 Agent 调用，无需重写逻辑。
  - 能力扩展: 可以执行一系列复杂的操作，远超单个 App Node Tool 的能力。
配置项含义:
- Description (描述):极其关键！ 这里你需要用自然语言清晰地描述这个子工作流是做什么的，什么时候应该调用它，以及它期望接收什么样的输入，会返回什么样的输出 。Agent 会根据这个描述来判断是否以及何时使用这个工具。例如：“调用此工具来抓取指定 URL 网页的HTML内容。输入应该是一个包含 ‘url’ 字段的 JSON 对象。”
- Source (来源): 指定要调用的子工作流。
  - Database: 从当前 n8n 实例的数据库中选择。你可以通过下拉列表选择，或直接输入子工作流的 ID（工作流 ID 是其 URL 末尾的一串字符，例如 .../workflow/abCDE1f6gHiJKL7 中的 abCDE1f6gHiJKL7 ）。
  - Define Below: 直接将子工作流的 JSON 定义粘贴到配置框中。
- Workflow Inputs (工作流输入): 定义如何将数据传递给被调用的子工作流。
  - 前提: 子工作流必须以 Execute Workflow Trigger 节点开始，并且在该触发器节点中定义了期望的输入模式（Input data mode: Define using fields below 或 Define using JSON example）。
  - 配置: 在 Call n8n Workflow Tool 节点中，点击 Refresh 按钮可以拉取子工作流定义的输入字段。然后，你可以为每个输入字段提供值：
    - 固定值: 直接输入静态值。
    - 表达式: 使用 {{ }} 从当前（调用方）工作流的上下文中引用数据。
    - 注意:不能直接在此处使用 $fromAI() 让 Agent 动态决定输入值。Agent 决定的是是否调用这个工具，以及基于什么信息调用，但传递给子工作流的具体输入值需要通过上述两种方式（固定值或表达式）预先定义好。
翔宇的实战理解: 这是实现复杂 Agent 逻辑的“瑞士军刀”。当你发现一个任务需要多个步骤、多个节点的组合才能完成时，就可以考虑将其封装成一个子工作流，然后让主 Agent 调用。例如，一个“生成报告”的工具，可能需要先从数据库取数（DB Tool），然后进行数据处理（Code Node），最后格式化输出（Set Node），这些步骤可以封装在一个子工作流中。描述一定要写清楚，否则 Agent 不会用或者用错。
限制: 主要限制在于输入参数不能由 $fromAI() 动态填充。如果需要根据 AI 的判断动态传入参数给子工作流，你可能需要在调用 Call n8n Workflow Tool 之前，先用一个 Set 节点或 Code 节点准备好这些参数，然后通过表达式传入。

Code Tool (代码工具 – Custom Code Tool)

简介/作用: 这个工具允许 Agent 执行一小段自定义的 JavaScript 或 Python 代码。它提供了极高的灵活性，可以用来处理标准节点无法完成的特定逻辑、数据转换或与特殊 API 的交互。
配置项含义:
- Description (描述):同样关键！ 需要清晰地告诉 Agent 这段代码的功能是什么，它期望接收什么样的输入（通过 query 变量），以及它会返回什么。例如：“计算两个数字的和。输入应该是一个包含 num1 和 num2 字段的 JSON 字符串。”
- Language (语言): 选择 JavaScript 或 Python 。
- JavaScript / Python box (代码框): 编写代码的地方。
  - 输入: Agent 传递给工具的输入可以通过名为 query 的变量在代码中访问。
  - 输出: 代码执行后必须使用 return 语句返回一个结果给 Agent。这个结果可以是字符串、数字、JSON 对象等。
  - 示例 (JavaScript):JavaScript// 假设 Agent 传入的 query 是字符串 "hello world" let inputText = query; // 将字符串转为大写并返回 return inputText.toUpperCase(); // 返回 "HELLO WORLD"
  - 示例 (Python): (注意：Python 环境基于 Pyodide，并非所有库都可用 ) Python# 假设 Agent 传入的 query 是数字 5 input_number = int(query) # 计算平方并返回 return input_number * input_number # 返回 25
翔宇的实战理解: Code Tool 适合执行简单、独立的逻辑片段。比如，进行特殊的数据格式化、实现一个标准节点没有的简单计算、或者调用一个非常简单且没有 n8n 节点的 API（但对于 API 调用，通常优先考虑 HTTP Request Tool）。避免在 Code Tool 中编写过于复杂的逻辑，那样会使工作流难以理解和维护。如果逻辑复杂，优先考虑使用 Call n8n Workflow Tool 调用子工作流。虽然目标是零代码，但理解 Code Tool 的基本用法（如何接收 query 输入和如何 return 输出）对于释放 Agent 的全部潜力有时是必要的。
限制:
- 同样，不能在 Code Tool 的代码内部直接使用 $fromAI()。Agent 提供 query 输入，代码基于该输入执行并返回结果。
- Python 环境受 Pyodide 限制，不是所有标准 Python 库都能使用。
- 复杂的异步操作或依赖管理可能比较困难。

HTTP Request Tool (HTTP 请求工具)

简介/作用: 这个工具赋予 Agent 访问互联网、调用任意 API、抓取网页内容的能力。它是 Agent 获取外部信息、与绝大多数在线服务交互的基础。
重要提示 (版本变化): 旧版本的 n8n 有一个独立的 “HTTP Request Tool” 子节点。但现在（较新版本），推荐的做法是使用标准的 HTTP Request 节点，并将其作为工具连接到 AI Agent 。本教程将重点介绍这种新方式。如果你在旧工作流中看到独立的 “HTTP Request Tool”，其功能类似，但配置界面可能略有不同。
配置项含义 (标准 HTTP Request 节点作为工具时):
- Description (描述 – 在 Agent 连接处隐式需要): 你需要在连接此工具到 Agent 时，在 Agent 的配置中（或通过某种方式让 Agent 知道）清晰地描述这个 HTTP 请求是用来做什么的。例如：“使用此工具查询指定城市的当前天气信息。”，“调用内部 API 获取客户订单列表。”，“抓取指定 URL 的网页标题。”
- 标准 HTTP Request 参数: 节点本身包含所有标准 HTTP Request 节点的参数，如：
  - Authentication: 设置认证方式（如 Basic Auth, OAuth2, API Key in Header/Query）。
  - Method: GET, POST, PUT, DELETE 等。
  - URL: 要请求的网址或 API 端点。
  - Send Headers: 配置请求头（如 Content-Type, Authorization）。
  - Send Query Parameters: 配置 URL 查询参数。
  - Send Body: 配置请求体（如 JSON, Form-Data）。
  - AI 的影响: 理论上，当作为工具使用时，AI Agent 可以通过 $fromAI() 动态填充这些参数（例如，让 AI 决定 URL 中的查询关键词，或 POST 请求体的内容）。但是，根据社区反馈，在 HTTP Request 节点中直接使用 $fromAI() 似乎存在问题或不被完全支持 。需要谨慎使用或寻找变通方法。
- Options -> Optimize Response (优化响应 – 工具特定选项): 这是将 HTTP Request 节点用作 AI 工具时非常重要的一个选项。它允许你预处理 HTTP 请求的响应，只将最相关、最简洁的信息返回给 Agent (LLM)，而不是返回庞大的原始数据。这有助于：
  - 降低成本: 减少发送给 LLM 的 Token 数量。
  - 提高效率: 避免 LLM 被无关信息淹没，让它更容易聚焦关键内容。
  - 提高准确性: LLM 处理更简洁、相关性更高的数据时，通常表现更好。
  - 子选项:
    - Response Format: 选择期望的响应类型（JSON, HTML, Text, File）。
    - 针对 JSON: 可以配置 Field Containing Data (指定包含主要数据的字段路径), Include Fields (只保留特定字段), Exclude Fields (排除特定字段)。
    - 针对 HTML: 可以使用 Selector (CSS) (只提取特定 CSS 选择器匹配的内容), Return Only Content (去除 HTML 标签), Elements To Omit (排除特定元素), Truncate Response (截断响应长度)。
    - 针对 Text: 只有 Truncate Response 选项。
翔宇的实战理解: HTTP Request Tool 是连接外部世界的“万能钥匙”。强烈建议使用 Optimize Response 功能，尤其是在处理网页抓取（HTML）或复杂的 API 响应（JSON）时。直接将整个网页 HTML 或巨大的 JSON 返回给 LLM 不仅浪费 Token，还可能导致 LLM 无法有效提取所需信息。先用 Optimize Response 提取关键部分（如特定段落、标题、JSON 字段），再交给 Agent 处理。在将其作为工具连接到 Agent 前，务必先独立测试 HTTP Request 节点，确保它能正确获取并（如果配置了优化）处理你想要的数据。关于 $fromAI() 在此节点中的不稳定性，如果需要 AI 动态决定请求参数，可以考虑先让 AI 在上一步生成参数，然后通过普通表达式传入 HTTP Request 节点。
限制与问题:
- $fromAI() 的不稳定性: 如上所述，社区报告表明 $fromAI() 在 HTTP Request 工具中可能无法按预期工作。
- 二进制数据处理: 处理需要发送或接收二进制文件（如上传文件）的请求可能需要特殊配置，或者 Agent 可能不支持直接处理二进制数据传递给此工具。
- API 限制: 目标 API 可能有速率限制、复杂的认证流程或反爬虫机制，需要相应处理。

常用 App Node 工具详解

n8n 的强大之处在于其丰富的应用节点。将这些节点作为工具连接到 AI Agent，可以让 Agent 直接操作你常用的各种 SaaS 服务和数据库。

通用配置方法:

对于每一个 App Node 工具，配置思路是相似的：

连接: 将 App Node 连接到 AI Agent 节点的 “Tool” 输入端。
认证: 在 App Node 中选择或创建相应的凭证（Credentials），授权 n8n 访问该服务。
配置核心参数: 设置该节点执行特定操作所需的基本参数（例如，对于 Google Sheets Append 操作，需要设置 Spreadsheet ID 和 Sheet Name）。
设置动态参数 (使用 $fromAI()): 对于需要由 AI 动态决定的参数（例如，要发送的邮件内容、要查询的数据库记录 ID、要创建的任务标题），在该参数字段中使用 $fromAI('key',...) 表达式。
提供描述 (给 Agent): 虽然 App Node 本身没有独立的 “Description” 字段，但你必须在 AI Agent 的 System Message 中清晰地描述这个工具是做什么的、什么时候应该使用它，以及关键参数（尤其是那些用 $fromAI() 的）代表什么。这是指导 Agent 正确使用工具的关键。

翔宇的提醒: 在将 App Node 作为工具使用前，强烈建议先独立测试该节点，确保其基本功能（如连接、认证、执行特定操作）正常工作。

以下是一些常用 App Node 工具的详解：

数据库 (Databases)

支持节点示例: Google BigQuery , Microsoft SQL , MySQL , Postgres , MongoDB , Supabase 。
简介/作用: 让 AI Agent 能够根据用户的自然语言请求，查询、插入、更新或删除数据库中的数据。例如，用户可以问“查找客户 John Doe 的订单记录”或“将客户 Jane Smith 的状态更新为‘已联系’”。
配置项含义:
- Description (在 System Message 中): 描述数据库包含什么信息，以及 Agent 可以用它来做什么。例如：“这是一个客户关系管理数据库。使用此工具可以查询客户信息、订单历史或更新客户状态。”
- Operation: 选择要执行的操作（如 Execute Query, Insert, Update, Select, Get Many 等，具体操作因数据库节点而异）。
- Table/Collection: 指定要操作的表或集合。
- Columns/Fields: 指定要插入或更新的列/字段及其值。可以使用 $fromAI() 让 AI 决定这些值。
- Filters/Query/Match On: 定义查询、更新或删除的条件。可以使用 $fromAI() 让 AI 根据用户请求动态生成过滤条件或 SQL 查询语句（对于 Execute Query 操作）。
$fromAI() 应用: 非常适合用于动态生成 Filters 或 Query。例如，在 Filters 中设置 customer_name = {{ $fromAI('customer_name') }}，让 AI 从用户请求中提取客户名称。
翔宇的实战理解: 为了让 AI 能更准确地生成查询语句或过滤条件，最好在 System Message 或工具描述中提供数据库的关键表结构信息（表名、重要列名及其含义）。直接让 AI 写复杂的 SQL 可能不太可靠，更稳妥的方式是让 AI 提供查询条件（如客户名、日期范围），然后在节点中使用这些条件构建查询。对于敏感操作（如删除、更新），务必在 Agent 逻辑中加入确认步骤，或限制 Agent 的权限。

文件存储 (Storage)

支持节点示例: AWS S3 , Dropbox , Google Drive , Microsoft OneDrive 。
简介/作用: 使 AI Agent 能够与云存储服务交互，执行如上传文件、下载文件、搜索文件、创建文件夹等操作。例如，Agent 可以根据指令将生成的报告上传到指定的 Google Drive 文件夹，或者从 Dropbox 下载用户请求的文件。
配置项含义:
- Description (在 System Message 中): 说明此工具用于哪个存储服务，以及可以执行哪些文件/文件夹操作。例如：“使用此 Google Drive 工具来搜索、下载或上传文件到用户的云盘。”
- Operation: 选择具体的文件或文件夹操作（如 Upload, Download, Search, Create Folder）。
- File ID/Folder ID/Path: 指定要操作的文件或文件夹。可以使用 $fromAI() 让 AI 决定目标路径或搜索关键词。
- Binary Property Name: 对于上传/下载操作，指定包含文件二进制数据的属性名。
$fromAI() 应用: 可用于动态指定 File ID, Folder ID, Path, 或 Search Query。例如，在 Google Drive 的 Search 操作的 Query 字段中使用 {{ $fromAI('search_keyword') }}。
翔宇的实战理解:处理二进制文件是这里的难点。AI Agent 本身通常不直接处理二进制流。常见的做法是：
1. 上游节点（如 Webhook, Read File）将文件读入 n8n 的二进制数据存储中。
2. Agent 决定要对哪个文件进行操作（可能通过文件名或其他元数据）。
3. Agent 调用存储工具时，通过 $fromAI() 或表达式提供文件名或二进制属性名（例如 data）。
4. 存储节点根据提供的属性名从 n8n 的二进制存储中获取文件数据并执行操作。或者，如社区讨论中提到的，将文件先上传到临时存储，然后将文件 ID/路径传递给 Agent，Agent 再指示工具使用该 ID/路径。描述中要清晰指示 Agent 需要提供文件名或 ID。

通讯交流 (Communication)

支持节点示例: Discord , Gmail , Microsoft Outlook , Microsoft Teams , Slack , Telegram , Send Email 。
简介/作用: 让 AI Agent 能够通过各种通讯渠道（邮件、即时消息）与人或其他系统进行交互。可以发送通知、回复用户消息、读取新消息内容等。
配置项含义:
- Description (在 System Message 中): 清晰说明工具的用途，例如“使用此 Slack 工具向 #admin 频道发送紧急通知”，“使用 Gmail 工具回复用户邮件”。
- Operation: 选择具体操作（如 Send Message, Read Messages, React to Message）。
- Recipient/Channel ID/To Email: 指定消息接收者或频道。可使用 $fromAI()。
- Message Content/Subject/Body: 消息内容。可使用 $fromAI() 让 AI 生成内容。
$fromAI() 应用: 非常适合动态生成 Message Content, Subject, Body, 或确定 Recipient/Channel ID。例如，在 Send Email 工具的 Body 字段使用 {{ $fromAI('email_body', '邮件正文内容') }}。
翔宇的实战理解: 这是让 Agent 与用户或其他团队成员互动的关键。描述中要明确沟通的目的和对象。注意消息格式，如果需要发送富文本（如 HTML 邮件），直接让 AI 生成复杂的 HTML 可能不稳定，可以考虑让 AI 生成 Markdown，然后使用 n8n 的 Markdown 节点转换为 HTML 。对于需要等待用户响应的操作（如 Slack/Teams/Email 的 Send and Wait for Response），将其作为 Agent 工具使用可能比较复杂，需要仔细设计流程。

效率与项目管理 (Productivity/Project Management)

支持节点示例: Asana , Jira , Trello , monday.com 。
简介/作用: 让 AI Agent 能够与项目管理或任务跟踪工具交互，例如根据会议纪要或用户请求自动创建任务、更新任务状态、分配负责人等。
配置项含义:
- Description (在 System Message 中): 说明工具用于哪个项目管理系统，以及可以执行的操作。例如：“使用此 Jira 工具在‘产品 Bug’项目中创建新的 Bug 报告。”
- Operation: 选择具体操作（如 Create Task, Update Issue, Get Projects）。
- Project ID/Board ID/List ID: 指定操作的目标项目/看板/列表。可使用 $fromAI()。
- Task Title/Issue Summary/Card Name: 任务/问题的标题。可使用 $fromAI()。
- Description/Body: 任务/问题的详细描述。可使用 $fromAI()。
- Assignee/Due Date/Status: 其他任务属性。可使用 $fromAI()。
$fromAI() 应用: 适用于动态生成任务标题、描述、截止日期，或根据上下文决定分配给谁、设置什么状态。
翔宇的实战理解: 非常适合将沟通（如邮件、Slack 消息）转化为可行动的任务。例如，Agent 分析客服邮件，识别出需要技术支持的问题，然后自动在 Jira 中创建一个 Bug 报告，并将邮件内容填入描述，甚至尝试根据邮件内容建议优先级。描述中需要清晰指明目标项目或看板，避免 Agent 在错误的地方创建任务。

内容管理系统 (Content Management)

支持节点示例: Ghost , Notion , WordPress 。
简介/作用: 使 AI Agent 能够创建、更新或获取 CMS 中的内容，如博客文章、文档页面、Notion 数据库条目等。
配置项含义:
- Description (在 System Message 中): 说明工具用于哪个 CMS，以及可以执行的操作。例如：“使用此 WordPress 工具发布新的博客文章。”
- Operation: 选择操作（如 Create Post, Update Page, Get Database Item）。
- Title/Page Name: 内容标题。可使用 $fromAI()。
- Content/Body: 主要内容。可使用 $fromAI()。
- Database ID/Parent Page ID: 指定 Notion 中的目标数据库或父页面。
- Tags/Categories/Status: 其他元数据。可使用 $fromAI()。
$fromAI() 应用: 主要用于动态生成文章标题和正文内容，或设置标签、分类等元数据。
翔宇的实战理解: 是实现 AI 辅助内容创作流程的利器。例如，Agent 可以根据研究结果（可能来自 Web Search Tool）自动起草一篇博客文章，然后使用 WordPress Tool 发布。需要注意内容格式的兼容性，比如 AI 生成的 Markdown 可能需要转换才能在特定 CMS 中正确显示（可以使用 n8n 的 Markdown 节点或 Notion Markdown 社区节点）。

其他实用工具 (Other Utilities)

支持节点示例: Compression (压缩) , Crypto (加密) , DeepL (翻译) , Google Translate (谷歌翻译) , JWT (JSON Web Token) , TOTP (基于时间的一次性密码) , QuickChart (图表生成) , urlscan.io (URL 分析) 。
简介/作用: 提供各种辅助性的、原子化的功能，可以在 Agent 的工作流程中按需调用。
配置项含义:
- Description (在 System Message 中): 必须非常具体地描述该工具的单一功能。例如：“使用此工具将给定的文本翻译成法语。”，“使用此工具为服务 X 生成当前的 TOTP 验证码。”，“使用此工具压缩名为 ‘input_file’ 的二进制文件。”
- Operation: 选择该工具提供的具体操作（如 Translate, Generate, Hash, Sign, Create Bar Chart, Scan URL）。
- 特定参数: 每个工具节点有其独特的参数（如 Text to Translate, Target Language, Secret Key, Chart Data, URL to Scan）。这些参数可以使用 $fromAI() 动态填充。
$fromAI() 应用: 用于动态提供需要处理的数据（如待翻译文本、待签名字符串）、配置参数（如目标语言、哈希算法）或密钥/凭证信息（如果适用且安全）。
翔宇的实战理解: 这些是 Agent 工具箱里的“小零件”，在需要时调用。因为功能单一，描述一定要精准，避免 Agent 误用。例如，对于翻译工具，要明确是哪个工具、翻译方向是什么。

简要介绍其他支持的工具

除了上述核心工具和常用的 App Node 工具外，n8n 的 AI Agent 还支持一些来自 LangChain 生态的、更专用的工具：

搜索类工具:
- SerpApi (Google Search): 让 Agent 能够执行谷歌搜索，获取实时网页结果。对于需要最新信息或广泛网络知识的任务非常有用。
- Wikipedia: 直接查询维基百科，获取特定词条的信息。适合获取百科类知识。
- WolframAlpha: 连接到 WolframAlpha 计算知识引擎，可以进行复杂的科学计算、数据分析和获取专业知识。
向量存储交互工具:
- Vector Store Question Answer Tool: 专门设计用于与向量数据库（Vector Store）交互，进行 RAG（检索增强生成）。Agent 可以用它来基于私有文档或知识库的内容回答问题，而不是直接查询向量数据库本身。它通常会先从向量库检索相关文本块，然后让 LLM 基于这些文本块总结答案。
计算工具:
- Calculator: 一个简单的工具，用于执行基本的数学运算。当 Agent 需要进行精确计算时（LLM 本身可能出错），可以调用此工具。

如何查看所有可用工具？

n8n 的集成和工具列表是不断更新的。要查看当前版本 AI Agent 支持的所有工具，最直接的方法是：

在 n8n 工作流画布中添加一个 AI Agent 节点。
点击节点下方的 “Tool” 连接器上的 “+” 号。
在弹出的节点选择面板中，通常会展示所有可以作为工具连接的节点。你可以通过搜索或分类（留意是否有 “AI Tools” 或类似分类）来查找。

工具是 AI Agent 发挥作用的关键。合理选择、配置工具，并提供清晰的描述和指令，是构建强大、可靠的 AI Agent 的核心所在。

Chat Model

聊天模型（Chat Model）是 AI Agent 的“智慧核心”或“大脑引擎”。它负责理解输入信息（用户提示、系统消息、工具返回的结果、记忆中的历史对话），进行推理和决策（决定下一步该做什么，是否使用工具，使用哪个工具），并最终生成 Agent 的响应或下一步指令。选择和配置合适的聊天模型对 AI Agent 的性能、成本和可靠性有着至关重要的影响。

支持的所有 Chat Model 概览

n8n 的 AI Agent（特别是作为 Tools Agent 运行时）支持连接多种聊天模型。这些模型通过专门的“Chat Model”子节点接入。

连接方式: Chat Model 子节点需要连接到 AI Agent 节点底部的专用 “Chat Model” 输入连接器上。
支持的模型提供商: n8n 提供了对多家主流和特定用途的 LLM 提供商的支持。根据文档和社区信息，以下是一些常用的、可以连接到 AI Agent 的聊天模型节点：
- OpenAI Chat Model: 支持 GPT-4, GPT-4o, GPT-3.5 等模型。
- Anthropic Chat Model: 支持 Claude 系列模型，如 Claude 3.5 Sonnet, Claude 3 Opus/Sonnet/Haiku 。
- Google Gemini Chat Model: 支持 Gemini 系列模型，如 Gemini Pro, Gemini Flash 。
- Azure OpenAI Chat Model: 通过 Azure 平台使用 OpenAI 的模型。
- Ollama Chat Model: 支持通过本地运行的 Ollama 服务连接 Llama, Mistral 等开源模型。
- Groq Chat Model: 提供对 Groq 平台上运行的高速模型的访问（通常是 Llama, Mixtral 等）。
- Mistral Cloud Chat Model: 支持 Mistral AI 提供的云端模型。
- DeepSeek Chat Model: 支持 DeepSeek 提供的模型。
- OpenRouter Chat Model: 通过 OpenRouter 平台访问多种不同的模型。
- Cohere Model: 支持 Cohere 提供的模型（注意：可能主要是非聊天指令模型，需确认其与 Tools Agent 的兼容性）。
- Hugging Face Inference Model: 支持通过 Hugging Face Inference Endpoints 运行的模型（注意：社区反馈可能与 Tools Agent 不直接兼容，可能需要通过 Basic LLM Chain 或其他方式接入）。
兼容性注意: 虽然 n8n 提供了多种 Chat Model 节点，但并非所有模型都保证能完美地与 Tools Agent 配合工作，特别是对于复杂的工具调用和遵循指令方面。根据 n8n 文档（Tools Agent 部分）和 LangChain 的能力，OpenAI, Anthropic, Google Gemini, Azure OpenAI, Groq, Mistral Cloud 这些主流模型通常具有较好的工具调用（Function Calling / Tool Calling）能力，是 Tools Agent 的首选。使用其他模型（尤其是本地模型如 Ollama 或通过 Hugging Face 接入的模型）时，可能需要更仔细地设计 Prompt 和 System Message，并且其遵循指令和使用工具的可靠性可能会有所不同。

每个 Chat Model 的作用功能与设置方法

虽然每个模型节点对应不同的提供商，但它们的配置方式和核心参数通常是相似的。以下以几个主要提供商为例进行说明：

OpenAI Chat Model

作用功能: 提供访问 OpenAI 的 GPT 系列模型（如 gpt-4o, gpt-4-turbo, gpt-3.5-turbo）的能力，这些模型通常在理解指令、执行推理和使用工具方面表现出色。
设置方法:
- Credentials: 需要在 n8n 中配置 OpenAI 凭证，主要需要填入你的 OpenAI API Key 。也可以选择性地配置 Base URL（例如，如果使用兼容 OpenAI API 的第三方服务或本地模型服务）。
- Model: 从下拉列表中选择你想使用的具体 OpenAI 模型。列表是动态加载的。
- Node Options (常用):
  - Maximum Number of Tokens: 限制模型单次生成的最大 token 数量。
  - Sampling Temperature: 控制输出的随机性（0 表示最确定，接近 2 表示最随机）。
  - Top P: 另一种控制随机性的方法（通常与 Temperature 只用其一）。
  - Frequency Penalty / Presence Penalty: 调整模型重复内容或引入新话题的倾向。
  - Response Format: 可选 Text 或 JSON（强制输出 JSON）。
  - Timeout / Max Retries: 控制 API 请求的超时和重试。

Anthropic Chat Model

作用功能: 提供访问 Anthropic 的 Claude 系列模型（如 claude-3.5-sonnet, claude-3-opus）的能力，这些模型以其强大的上下文理解能力和较长的上下文窗口而闻名，同样具备良好的工具使用能力。
设置方法:
- Credentials: 需要配置 Anthropic 凭证，主要需要填入你的 Anthropic API Key 。
- Model: 从下拉列表选择具体的 Claude 模型（注意：n8n 节点中的模型列表可能需要手动更新或等待 n8n 版本更新才能包含最新发布的模型，如 Claude 3.7 ）。
- Node Options (常用):
  - Maximum Number of Tokens: 限制最大生成长度。
  - Sampling Temperature: 控制随机性。
  - Top K / Top P: 控制采样策略。

Google Gemini Chat Model

作用功能: 提供访问 Google 的 Gemini 系列模型（如 gemini-1.5-pro, gemini-1.5-flash）的能力，这些模型通常具有强大的多模态处理能力和较长的上下文窗口。
设置方法:
- Credentials: 需要配置 Google AI 凭证，通常需要一个 Google Cloud 项目并启用 Gemini API，然后获取 API Key 。
- Model: 从动态加载的列表中选择可用的 Gemini 模型。
- Node Options (常用):
  - Maximum Number of Tokens: 限制长度。
  - Sampling Temperature: 控制随机性。
  - Top K / Top P: 控制采样策略。
  - Safety Settings: 可以配置 Google 提供的安全过滤器级别。

Ollama Chat Model

作用功能: 允许你连接到本地运行的 Ollama 服务，从而使用开源模型（如 Llama 3, Mistral, Phi 等）作为 Agent 的大脑。主要优势在于数据隐私和成本节约（无 API 调用费用）。
设置方法:
- 前提: 你需要在本地或可访问的网络环境中安装并运行 Ollama 服务，并下载所需的模型。
- Credentials: 配置 Ollama 凭证，主要是指定 Ollama 服务的 Base URL（默认为 http://localhost:11434）。如果 n8n 和 Ollama 在不同的 Docker 容器中运行，可能需要配置网络或使用 http://host.docker.internal:11434 或容器 IP 地址。
- Model: 从下拉列表中选择你已通过 Ollama 下载并可用的模型（如 llama3, mistral）。
- Node Options (常用):
  - Sampling Temperature: 控制随机性。
  - Top K / Top P: 控制采样策略。
翔宇的实战理解: Ollama 是在本地运行 AI Agent 的绝佳选择，特别适合处理敏感数据或进行大量实验。但需要注意，本地模型的性能（速度和“智能”程度）可能不如顶级的云端 API 模型，对于复杂的工具调用任务，可能需要更强大的硬件和更精细的 Prompt 调优。同时，确保 n8n 能够访问到 Ollama 服务是配置的关键。

其他模型 (Azure, Groq, Mistral, DeepSeek, OpenRouter 等)

这些节点的配置方式与 OpenAI/Anthropic/Gemini 类似：

Credentials: 通常需要相应的 API Key，有时还需要指定特定的 Endpoint URL 或 Resource Name (如 Azure) 。
Model: 从节点提供的下拉列表中选择模型。
Options: 提供类似的参数来控制生成行为（Temperature, Max Tokens, Top P 等）。

模型选择建议

为 AI Agent 选择合适的聊天模型是一个需要权衡多方面因素的决策：

任务复杂度与工具使用:
- 如果 Agent 需要执行复杂的推理、理解细微指令、可靠地使用多个工具，那么更强大、更智能的模型通常是必需的，例如 OpenAI 的 GPT-4o、Anthropic 的 Claude 3.5 Sonnet 或 Google 的 Gemini 1.5 Pro 。虽然成本较高，但它们能更好地理解意图并减少错误。
- 对于简单的问答、文本总结或只使用一两个简单工具的场景，性价比较高或速度更快的模型可能就足够了，例如 GPT-4o-mini, Gemini Flash, 或通过 Groq 访问的模型（以速度著称）。
成本: 不同模型的 API 调用价格差异很大。需要根据预期使用量和预算来选择。本地模型（Ollama）在运行成本上最低，但需要硬件投入和维护。
速度/延迟: 对于需要实时交互的应用（如聊天机器人），模型的响应速度很重要。Groq 平台上的模型以低延迟著称。像 Gemini Flash, Claude 3 Haiku, GPT-3.5 Turbo 通常也比它们更强大的版本快。
上下文窗口: 模型能处理的输入和输出总长度（Token 数量）限制。如果 Agent 需要处理长文档、复杂的指令或保持非常长的对话记忆，需要选择具有较大上下文窗口的模型（如 Claude 3 系列、Gemini 1.5 Pro、GPT-4 Turbo）。
数据隐私: 如果处理高度敏感的数据，使用本地部署的 Ollama 模型是最佳选择，因为数据不会离开你的环境。
特定能力: 某些模型可能在特定任务上表现更好（例如，编码、多语言、视觉理解）。

翔宇的建议:

从性价比高的模型开始测试: 使用如 GPT-4o-mini, Gemini Flash 或 Groq 上的模型进行初步开发和调试，以控制成本。
根据需要升级: 如果发现 Agent 在理解复杂指令或使用工具方面表现不佳，再尝试升级到更强大的模型（如 GPT-4o, Claude 3.5 Sonnet）。
优先考虑官方支持工具调用的模型: 对于 Tools Agent，优先选择明确支持 Tool Calling/Function Calling 的模型提供商（OpenAI, Anthropic, Google, Azure, Mistral, Groq），这样通常更可靠。
本地模型用于特定场景: 如果数据隐私是首要考虑，或者需要进行大量低成本实验，并且硬件允许，可以深入研究 Ollama。但要准备好可能需要更多调优工作才能让它可靠地使用工具。
实验是关键: 没有绝对“最好”的模型。针对你的具体应用场景，进行充分的测试和比较，找到最适合的模型。

选择正确的聊天模型是构建成功 AI Agent 的重要一步，需要综合考虑任务需求、性能、成本和隐私等多个因素。

Memory

记忆（Memory）是让 AI Agent 能够进行连贯对话、理解上下文的关键组件。没有记忆，Agent 对每次输入的处理都是独立的，无法记住之前的交流内容，就像一个只能回答单个问题却记不住对话历史的人。

Memory 在 AI Agent 中的作用

定义: Memory 组件负责存储和检索 AI Agent 与用户之间的交互历史（包括用户的提问和 Agent 的回答）。
作用: 在 Agent 处理新的用户输入时，Memory 会提供之前的对话内容作为上下文（Context）。这使得 Agent 能够：
- 理解指代关系（例如，用户问“它怎么样了？”，Agent 能知道“它”指的是上一轮提到的某个事物）。
- 进行多轮对话，保持话题连贯性。
- 根据用户的历史偏好或信息提供更个性化的回应。
翔宇的比喻: 如果说 Chat Model 是 Agent 的“大脑”，Tool 是“手脚”，那么 Memory 就好比 Agent 的“短期记忆”。它记录了刚刚发生了什么，让 Agent 的思考和行动能够基于之前的交流。
连接方式: Memory 节点需要连接到 AI Agent 节点底部的专用 “Memory” 输入连接器上。一个 Agent 通常只连接一个 Memory 节点。

支持的所有 Memory 类型概览

n8n 提供了多种 Memory 节点，以满足不同的需求和技术栈：

Simple Memory (简单记忆):
- 曾用名: Window Buffer Memory 。
- 特点: 最简单易用，将最近 N 条对话历史存储在当前工作流执行的数据中。
- 优点: 无需外部依赖，配置简单。
- 缺点: 记忆是临时的，仅在单次工作流执行期间有效。如果工作流结束或 n8n 重启，记忆会丢失。不适用于 n8n 的队列模式 (Queue Mode) 。
数据库支持的 Memory (Database-backed Memory):
- 节点: Postgres Chat Memory , Redis Chat Memory , MongoDB Chat Memory 。
- 特点: 将对话历史持久化存储在外部的 PostgreSQL, Redis 或 MongoDB 数据库中。
- 优点: 记忆可以在多次工作流执行之间保持，甚至跨用户、跨会话（如果 Session Key 设计得当）。适用于需要长期记忆或在队列模式下运行 n8n 的场景。
- 缺点: 需要额外设置和维护相应的数据库服务及 n8n 中的凭证。
专业记忆服务 (Specialized Memory Services):
- 节点: Motorhead , Xata , Zep 。
- 特点: 连接到专门为 LLM 应用设计的外部记忆服务。这些服务通常提供更高级的功能，如自动摘要旧消息、语义搜索记忆内容、长期记忆管理等。
- 优点: 功能强大，可能比简单的数据库存储更智能、更高效地管理长对话历史。
- 缺点: 依赖外部服务，可能产生额外费用，配置相对复杂。
Chat Memory Manager (聊天记忆管理器):
- 注意: 这不是一种存储记忆的方式，而是一个用于在工作流中主动操作和管理由其他 Memory 节点（如 Simple Memory 或数据库 Memory）存储的记忆内容的工具节点 。

每个 Memory 的作用功能与设置方法

Simple Memory (简单记忆)

作用功能: 存储最近 N 条对话消息，提供基本的上下文保持能力。非常适合快速原型设计和简单的聊天机器人示例。
参数:
- Session Key (会话密钥): 必需。一个唯一的字符串，用于标识当前的对话会话。来自同一用户的连续消息应该使用相同的 Session Key。通常使用表达式从触发器数据中动态获取（例如，用户的聊天 ID {{ $trigger.userId }} 或 chat_with_{{ $trigger.chatId }} ）。
- Context Window Length (上下文窗口长度): 必需。一个数字，指定要保留并提供给 Agent 的最近消息的数量（包括用户和 AI 的消息）。例如，设置为 10 表示只记住最近的 10 条消息。
设置方法:
1. 将 Simple Memory 节点连接到 AI Agent 的 Memory 输入端。
2. 配置 Session Key，通常使用表达式动态生成。
3. 设置 Context Window Length。
限制:
- 记忆仅存在于当前工作流执行中，无法持久化。
- 不能在 n8n 队列模式下可靠工作，因为不同的执行步骤可能被分配到不同的工作进程，导致无法访问之前存储的内存。

Postgres/Redis/MongoDB Chat Memory

作用功能: 将对话历史持久化存储到指定的数据库中，实现跨执行、跨会话的记忆。
参数:
- Session Key (会话密钥): 必需。同样用于标识特定对话会话的唯一键。
- Context Window Length (上下文窗口长度): 必需。指定从数据库中检索多少条最近的消息作为上下文。
- Table Name (Postgres) / Collection Name (MongoDB): 必需。指定数据库中用于存储聊天记录的表名或集合名。如果不存在，系统通常会自动创建。
- Database Name (MongoDB, 可选): 指定要使用的数据库名称，如果未提供，则使用凭证中配置的默认数据库。
- Session Time To Live (Redis, 可选): 设置会话在 Redis 中的过期时间（秒）。
设置方法:
1. 确保你有一个正在运行的 PostgreSQL, Redis 或 MongoDB 实例，并且 n8n 可以访问它。
2. 在 n8n 的 Credentials 部分配置相应的数据库凭证（主机、端口、用户名、密码、数据库名等）。
3. 将对应的 Chat Memory 节点（Postgres, Redis 或 Mongo）连接到 AI Agent。
4. 在节点中选择配置好的数据库凭证。
5. 配置 Session Key, Context Window Length, 以及 Table Name/Collection Name 等参数。
优点: 实现了记忆的持久化，适用于需要长期对话或在队列模式下运行的场景。

Motorhead/Xata/Zep Memory

作用功能: 连接到外部专业的记忆服务，提供可能更高级的记忆管理功能（如自动摘要、语义搜索等，具体功能取决于外部服务本身）。
参数:
- Session ID (会话 ID): 必需。用于标识 Zep/Xata/Motorhead 中的特定会话。
- Context Window Length (Xata): Xata 节点似乎也有这个参数。Motorhead 和 Zep 的上下文管理可能主要由服务本身控制。
设置方法:
1. 注册并设置相应的外部记忆服务（Motorhead, Xata 或 Zep）。
2. 获取该服务的 API Key 或其他认证信息。
3. 在 n8n Credentials 中配置对应的凭证。
4. 将对应的 Memory 节点连接到 AI Agent。
5. 在节点中选择配置好的凭证并设置 Session ID。
优点: 可能提供比简单数据库存储更智能的记忆管理。
缺点: 增加了外部依赖和潜在成本。

单一记忆实例行为 (Single Memory Instance Behavior)

对于所有持久化的 Memory 类型（Postgres, Redis, MongoDB, Motorhead, Xata, Zep），需要注意：默认情况下，在同一个 n8n 工作流中，所有使用相同类型且具有相同 Session Key/ID 的 Memory 节点，都会访问和操作同一个记忆存储实例 。

影响: 如果你在工作流的不同分支或步骤中使用了多个指向同一会话的 Memory 节点，它们会共享状态。在一个地方修改（如删除或覆盖）记忆，会影响到其他所有地方。
解决方案: 如果你需要在一个工作流中处理多个独立的对话记忆（例如，同时与多个用户聊天），你必须为每个独立的对话使用不同的 Session Key/ID。这样可以确保每个 Memory 节点操作的是隔离的记忆空间。

Chat Memory Manager 节点详解

Chat Memory Manager 节点本身不存储记忆，它的作用是在工作流中显式地读取、写入或删除由其他 Memory 节点（如 Simple Memory, Postgres Chat Memory 等）管理的记忆内容。

用途:
- 无法直接连接 Memory 节点时: 在某些复杂的流程中，可能无法直接将 Memory 节点连接到需要记忆的节点（虽然 AI Agent 通常可以直接连接）。
- 复杂的记忆管理: 当你需要比标准 Memory 节点提供的功能更精细的控制时。例如：
  - 检查和修剪记忆: 获取当前记忆内容，检查其大小（Token 数量），如果过长，则进行总结或删除旧消息，然后将处理后的记忆写回，以控制传递给 LLM 的上下文大小，节省 Token 。
  - 注入上下文: 将一些预定义的系统信息或背景知识，伪装成用户或 AI 的消息插入到记忆中，以便为后续的 AI 处理提供更丰富的上下文。
- 显式操作: 在工作流的特定步骤强制读取、保存或清空记忆。
操作模式 (Operation Mode):
- Get Many Messages: 从连接的 Memory 中读取消息历史。
  - Simplify Output (选项): 开启后只输出发送者（AI/User/System）和消息文本。
- Insert Messages: 向连接的 Memory 中插入新的消息。
  - Insert Mode (子选项):
    - Insert Messages: 追加新消息到现有历史末尾。
    - Override All Messages: 清空现有历史，用新消息完全替换。
  - Chat Messages (参数): 定义要插入的消息列表，每条消息包含：
    - Type Name or ID: 消息类型 (AI, System, User)。
    - Message: 消息的文本内容。
    - Hide Message in Chat (选项): 是否在 n8n 聊天界面中对用户隐藏此条插入的消息（例如，注入的系统指令可能希望隐藏）。
- Delete Messages: 从连接的 Memory 中删除消息。
  - Delete Mode (子选项):
    - Last N: 删除最近的 N 条消息。
    - All Messages: 清空所有记忆。
  - Messages Count (参数): 当 Delete Mode 为 Last N 时，指定要删除的消息数量。
连接: Chat Memory Manager 节点需要连接到一个实际的 Memory 存储节点（如 Simple Memory, Postgres Chat Memory 等）来指定它要操作哪个记忆实例。
翔宇的实战理解: 这个节点相对高级。对于初学者，通常直接将 Memory 节点连接到 AI Agent 就足够了。当你遇到需要精细控制对话历史、管理 Token 成本、或者动态注入上下文的复杂场景时，Chat Memory Manager 才真正派上用场。例如，可以构建一个流程：用户提问 -> Agent 处理 -> 获取 Agent 回答和当前 Memory -> 使用另一个 LLM 节点总结旧的对话 -> 使用 Chat Memory Manager 删除旧消息并插入总结 -> 将新回答插入 Memory。

Memory 选择与使用建议

入门与测试: 对于初学者或构建简单的演示，Simple Memory 是最快、最容易上手的选择。只需关注 Session Key 和 Context Window Length 即可。
需要持久化/多用户: 如果你的 Agent 需要记住跨越多次运行的对话，或者需要为不同的用户维护独立的对话历史，那么基于数据库的 Memory（如 Postgres Chat Memory 或 Redis Chat Memory）是必要的。
高级功能: 如果你需要自动摘要、语义搜索记忆等高级功能，可以研究 Zep 或 Motorhead 等专业记忆服务。
关键在于 Session Key: 无论使用哪种持久化 Memory，为每个独立对话（通常是每个用户）动态生成并使用唯一的 Session Key/ID 是实现多用户、上下文隔离的关键。通常这个 Key 可以基于触发器提供的用户 ID 或聊天 ID 来生成。

选择合适的 Memory 类型并正确配置 Session Key，是确保 AI Agent 能够有效利用对话历史、提供连贯和个性化体验的基础。

应用场景

AI Agent 节点的强大之处在于其灵活性和适应性，使其能够应用于各种需要智能决策和自动化交互的场景。结合翔宇在实际工作中的经验，以下是一些常见且实用的应用场景：

翔宇常用应用场景举例

智能客服与聊天机器人:
- 场景描述: 构建能够理解用户自然语言提问，并能调用内部知识库（如 Notion、数据库）或外部工具（如网页搜索、天气查询）来回答问题的聊天机器人。
- 实现方式: 使用 Chat Trigger 或 Webhook 作为入口，连接 AI Agent。Agent 的 System Message 定义其客服角色和知识范围。连接 Vector Store Q&A Tool（用于 RAG 知识库问答）、HTTP Request Tool（用于调用 API 或搜索）、数据库节点 Tool 等。使用 Simple Memory 或数据库 Memory 保持对话上下文。
- 翔宇心得: 这是 AI Agent 最直观的应用。关键在于 RAG 的构建（知识库的质量和检索效果）以及清晰地指示 Agent 何时使用知识库、何时使用通用搜索、何时无法回答。
邮件/消息智能处理与分类:
- 场景描述: 自动读取新收到的邮件（Gmail/Outlook）或 Slack/Discord 消息，利用 AI Agent 理解内容，进行分类（如紧急、重要、垃圾邮件、销售线索、技术支持请求），提取关键信息（如发件人、主题、意图、联系方式、订单号），并根据分类结果执行后续操作（如打标签、转发给特定人员、存入 CRM）。
- 实现方式: 使用 Email Trigger 或消息类 Trigger 启动工作流。连接 AI Agent，System Message 指示其进行分类和信息提取任务。可能需要连接 Structured Output Parser 来规范输出。后续连接相应的 App Node（如 Gmail Tool 打标签、Slack Tool 转发、CRM Tool 存入数据）。
- 翔宇心得: 对于需要精确提取信息的场景，使用带有 JSON Schema 的 Structured Output Parser 非常重要。Prompt 需要引导模型专注于识别和提取你关心的字段。
自动化内容生成与分发:
- 场景描述: 根据输入的主题、关键词或数据，利用 AI Agent 自动生成初稿（如邮件回复、博客文章、社交媒体帖子、产品描述），然后通过相应的工具（Send Email, WordPress, Slack 等）进行分发。
- 实现方式: 触发器可以是 Webhook、Schedule Trigger 或手动触发。AI Agent 接收指令和上下文数据。System Message 定义生成内容的风格、格式和目标受众。可能需要连接 Web Search Tool 或数据库 Tool 来获取生成内容的素材。最后连接 Send Email Tool, WordPress Tool, Slack Tool 等进行发布。
- 翔宇心得: AI Agent 非常适合生成内容的初稿或进行改写、润色。但对于需要高度原创性或专业性的内容，仍需人工审核和修改。结合 RAG 或 Web Search 可以让生成的内容更具时效性和准确性。
自然语言数据库交互:
- 场景描述: 允许非技术用户通过自然语言查询公司的数据库（如查询销售额、客户信息、库存量），AI Agent 负责将自然语言转换为 SQL 查询（或数据库节点的操作参数），执行查询并将结果以易于理解的方式返回给用户。
- 实现方式: 使用 Chat Trigger 或 Webhook 作为入口。AI Agent 连接数据库节点（MySQL, Postgres, BigQuery 等）作为 Tool。System Message 中需要包含数据库关键表的结构信息（表名、列名、含义），并指导 Agent 如何根据用户问题生成查询条件或语句。
- 翔宇心得: 这是降低数据访问门槛的有效方式。但要特别注意数据安全，确保 Agent 执行的查询是安全的，不会意外修改或删除数据。对于复杂查询，让 Agent 生成过滤条件给预设的查询语句通常比让它直接写 SQL 更可靠。
自动化任务创建与分配:
- 场景描述: 监听邮件、Slack 或其他来源的信息，当识别到需要跟进的任务时，自动在项目管理工具（如 Asana, Jira, Trello）中创建任务，并根据内容尝试设置标题、描述、截止日期甚至分配给相关人员。
- 实现方式: 使用 Email/Slack Trigger 等。AI Agent 分析输入信息，提取任务要素。连接 Asana/Jira/Trello 节点作为 Tool。使用 $fromAI() 动态填充任务的各个字段。
- 翔宇心得: 可以有效连接沟通和执行。关键在于 Agent 能准确地从非结构化信息中提取出结构化的任务要素。

其他典型应用场景

除了上述翔宇常用的场景外，AI Agent 还可以应用于：

网页信息监控与摘要: 定期检查指定网页（使用 HTTP Request Tool），如果内容有更新，提取更新部分并生成摘要，发送通知（如 Slack, Email）。
会议/日程安排助手: 根据用户指令检查多人的 Google Calendar，找到空闲时间段，并创建会议邀请。
多语言沟通: 接收一种语言的消息，使用 DeepL 或 Google Translate Tool 翻译成另一种语言，再进行处理或回复。
金融/市场研究: 调用金融数据 API（通过 HTTP Request Tool）或搜索引擎（SerpApi Tool），获取最新的股票价格、市场新闻或研究报告，并进行总结分析。
语音交互: 结合语音转文字（STT）和文字转语音（TTS）服务（可能通过 HTTP Request Tool 调用外部 API，或使用 n8n 内置节点如 OpenAI Whisper/TTS），实现通过语音与 AI Agent 交互。

n8n 官方网站的模板库 (Templates) 中包含了大量由社区和官方贡献的 AI Agent 应用实例，是寻找灵感和学习实践的绝佳资源。

总而言之，AI Agent 节点的应用潜力巨大，几乎涵盖了所有需要超越简单规则、进行智能判断和与外部工具交互的自动化场景。关键在于清晰地定义目标、选择合适的工具和模型，并提供明确的指令。

常见报错及解决方案

在使用 AI Agent 节点时，遇到错误是在所难免的，尤其是在刚开始接触时。理解常见的错误类型、掌握排查思路和调试方法，能够帮助你更快地定位并解决问题。

常见错误类型解析

以下是一些在使用 AI Agent 节点及其相关子节点（Chat Model, Memory, Tools）时可能遇到的常见错误及其原因分析：

配置类错误 (通常在节点执行前或刚开始时出现):

A Chat Model sub-node must be connected (必须连接聊天模型子节点):
- 原因: AI Agent 节点缺少了必需的“大脑”——没有连接任何 Chat Model 子节点。
- 解决: 点击 Agent 节点下方的 “Chat Model” 连接器上的 “+” 号，选择并配置一个聊天模型节点（如 OpenAI Chat Model, Anthropic Chat Model 等）。
A Retriever sub-node must be connected (必须连接检索器子节点):
- 原因: 这个错误通常出现在 Question and Answer Chain 节点中，表示缺少用于从知识库检索信息的 Retriever 子节点。虽然不是直接针对 AI Agent，但原理类似——缺少了必需的组件连接。
- 解决: 确保所有必需的子节点（对于 Agent 来说主要是 Chat Model，以及至少一个 Tool，除非是极简单的场景）都已正确连接。
No prompt specified (未指定提示):
- 原因: Agent 节点未能获取到有效的用户输入。可能是：
  - Prompt 设置为 Define below，但 Prompt (User Message) 文本框为空，或者其中的表达式未能正确解析出值。
  - Prompt 设置为 Take from previous node automatically，但上一个节点的输出中缺少 chatInput 字段，或者该字段的值为 null。
- 解决: 检查 Prompt 设置和上游节点的输出数据，确保 Agent 能接收到有效的用户提示文本。
凭证错误 (Credential Errors):
- 表现: 连接失败、认证失败、权限不足等。
- 原因: API Key 错误或过期、Base URL 配置错误（尤其对于自托管模型或 OpenRouter 等）、账户权限不足、未在服务提供商处启用必要的 API 访问权限等。
- 解决: 仔细检查 n8n 中配置的凭证信息是否与服务提供商处的信息完全一致。确认 API Key 有效且具有所需权限。检查网络连接和防火墙设置。

运行时错误 (通常在 Agent 执行过程中出现):

Internal error: 400 Invalid value for 'content':
- 原因: 发送给聊天模型的提示内容中包含了 null 值或其他无效内容。这通常源于上游节点的表达式解析问题或数据处理错误。
- 解决: 检查传递给 Agent 的 Prompt 或在 System Message/Tool Description 中使用的表达式，确保它们引用的数据有效且不为 null。
Tool response was not in the expected format / Unable to parse JSON response:
- 原因: Agent（或其内部的 LangChain 框架）期望从聊天模型或工具那里得到特定格式的响应（通常是用于工具调用的 JSON），但实际收到的响应格式不符。这可能是因为 LLM 没有完全遵循格式指令，或者工具本身返回了非预期的内容。
- 解决:
  - 检查 System Message 和 Tool Description，确保对输出格式（尤其是 JSON 结构）的要求清晰明确。
  - 尝试使用更“聪明”的、更擅长遵循指令的聊天模型。
  - 如果期望 Agent 输出结构化数据，务必开启 Require Specific Output Format 并连接 Structured Output Parser，提供清晰的 JSON 示例。
  - 检查工具节点的执行结果，看是否是工具本身返回了错误或非预期格式的数据。
429 Too Many Requests (速率限制错误):
- 原因: 在短时间内向外部服务（如 OpenAI API, SerpApi 等）发送了过多的请求，超出了服务提供商设定的速率限制。这在 Agent 进行多次迭代或循环调用工具时容易发生。
- 解决:
  - 在工作流中引入 Wait 节点，在循环或连续的 API 调用之间增加延迟。
  - 如果处理大量数据项，考虑使用 n8n 的内置批处理（Batching）或循环（Looping）机制，结合 Wait 节点来控制请求速率。
  - 检查是否有可能升级你在外部服务上的账户等级以获取更高的速率限制。
工具调用错误 (Tool "X" not found, Tool execution failed):
- 原因:
  - Agent 试图调用一个未连接或未在 System Message/Tool Description 中正确定义的工具。
  - Agent 调用了工具，但工具节点本身在执行时出错了（例如，HTTP Request 失败、数据库连接失败、代码错误等）。
- 解决:
  - 确保所有需要使用的工具都已正确连接到 Agent 的 “Tool” 接口。
  - 仔细检查 System Message 和 Tool Description，确保工具名称和使用条件描述准确无误。
  - 开启 Return Intermediate Steps，查看 Agent 尝试调用哪个工具以及传递了什么参数。
  - 独立测试工具节点，确保其在没有 Agent 的情况下能够正常工作。
Max iterations exceeded (达到最大迭代次数):
- 原因: Agent 在达到 Max Iterations 限制之前未能完成任务并给出最终答案。通常是因为 Agent 陷入了逻辑循环（例如，反复调用同一个工具但无法取得进展）、对任务目标感到困惑、或者工具使用失败导致无法继续。
- 解决:
  - 开启 Return Intermediate Steps，分析 Agent 的循环行为，找出卡住的原因。
  - 改进 System Message 和 Tool Description，使其更清晰、更具指导性。
  - 检查工具的可靠性，确保它们能按预期返回结果。
  - 如果任务确实复杂，考虑增加 Max Iterations 的值，或者将任务拆分成更小的步骤（可能使用子工作流）。
Memory 错误 (Error in sub-node Simple Memory):
- 原因: 使用 Simple Memory 时，可能与 n8n 队列模式冲突，或者工作流模板使用了旧版本的 Memory 节点（Window Buffer Memory）。
- 解决: 如果使用队列模式，切换到数据库支持的 Memory 类型。如果是旧模板，尝试删除并重新添加 Simple Memory 节点。
表达式错误 (Can't get data for expression, Invalid syntax):
- 原因: 表达式语法错误，或者引用的上游节点数据不存在或尚未执行。
- 解决: 仔细检查表达式语法。确保引用的节点名称正确，并且该节点在工作流中会先于当前节点执行。使用表达式编辑器进行预览和调试。

排错思路与调试方法

遇到问题时，可以遵循以下思路进行排查和调试：

从简到繁，逐个击破:
- 先测试基础连接: 确保 Chat Model 凭证有效，能单独连接成功。确保 Memory 凭证有效（如果使用数据库或外部服务）。确保要使用的 Tool 节点凭证有效，并且能独立执行其基本操作。
- 构建最小可行 Agent: 先创建一个只有 Chat Model 连接的 Agent，测试基本的问答是否正常。
- 逐步添加组件: 一次只添加一个 Tool 或 Memory，然后进行测试。如果添加某个组件后出现问题，就重点排查该组件及其与 Agent 的交互。
检查配置，核对文档:
- Agent 配置: 仔细核对 Prompt 来源、System Message 的清晰度、Max Iterations 是否合理。
- Tool 配置: 检查 Tool 节点的具体参数设置是否正确。
- Chat Model 配置: 确认选择了合适的模型，API Key 等凭证无误。
- Memory 配置: 确认 Session Key 设置正确（特别是动态生成时），Context Window Length 合理，数据库连接正常（如果使用）。
- 参考官方文档: 对照本教程和 n8n 官方文档，检查是否有遗漏或错误的配置。
利用日志，洞察过程:
- 开启 Return Intermediate Steps: 这是调试 Agent 行为的最重要手段 。仔细分析输出日志中的 Thought, Action, Action Input, Observation，理解 Agent 的决策过程。
- 查看节点执行数据: 在 n8n 的执行日志 (Executions) 视图中，检查每个节点的输入和输出数据，确认数据是否按预期流动。
优化指令，引导 Agent:
- 改进 System Message: 如果 Agent 行为不符合预期（如不使用工具、用错工具、回答偏离主题），重点优化 System Message，使其更明确、更具体。
- 优化 Tool Description: 确保每个工具的描述清晰地说明了其功能和使用场景。
处理外部因素:
- API 限制: 如果遇到 429 错误，考虑引入 Wait 节点或调整请求策略。
- 网络问题: 确保 n8n 实例能够访问所需的外部服务（LLM API, 工具 API, 数据库等）。

日志定位技巧

当开启 Return Intermediate Steps 后，如何有效利用输出的日志信息？

寻找关键信息: 重点关注日志中的 Action: (Agent 决定使用哪个工具) 和 Action Input: (Agent 传递给工具的参数)。这能告诉你 Agent 是否正确选择了工具以及输入是否合理。
检查工具反馈: 查看紧随 Action 之后的 Observation: (工具返回的结果)。工具是否成功执行？返回的数据是否符合预期？Agent 能否正确理解这个结果？
理解思考链: 阅读 Thought: 部分，尝试理解 Agent 的“内心想法”。它为什么选择这个工具？它对当前情况的判断是什么？这有助于发现 Agent 推理逻辑上的问题。
定位循环: 如果 Agent 达到 Max Iterations，回溯日志，找到重复出现的 Thought -> Action -> Observation 模式，确定 Agent 卡在了哪个环节。
对比指令: 将日志中 Agent 的实际行为（特别是工具选择和参数）与你在 System Message 和 Tool Description 中给出的指令进行对比，找出偏差之处。

通过系统性的排查和对日志的细致分析，大部分 AI Agent 的问题都可以被定位和解决。耐心和细致是调试 AI Agent 的好伙伴。

注意事项

在使用 n8n AI Agent 节点构建智能工作流时，除了掌握基本配置和调试技巧外，还需要注意一些重要的事项，以确保工作流的稳定性、安全性和效率。

使用注意事项

优化 Prompt:

明确指令是关键 (Clear Prompting):

System Message: 这是与 Agent 沟通的最重要渠道。务必投入时间精心设计 System Message，清晰地定义 Agent 的角色、目标、行为准则、限制条件，以及最重要的——如何以及何时使用连接的工具 。模糊或有歧义的指令是导致 Agent 行为混乱或失败的主要原因之一。

Tool Description: 对于连接的每个工具（无论是核心工具还是 App Node 工具），都需要提供简洁而准确的描述，告诉 Agent 这个工具是做什么的，以便 Agent 能够做出正确的选择。

迭代式开发与测试 (Start Simple & Iterate):

不要试图一次性构建一个极其复杂的 Agent。从一个简单的目标开始，只连接必要的模型和少量工具。

独立测试组件: 在将 Chat Model、Memory 或 Tool 连接到 Agent 之前，先单独测试它们，确保它们各自能正常工作。

逐步增加复杂度: 在基础 Agent 工作正常后，再逐步添加更多的工具或更复杂的逻辑，每次添加后都要进行充分测试。

模型选择的重要性 (Model Selection Matters):

不同的 LLM 在理解复杂指令、遵循格式要求、可靠地使用工具等方面的能力差异很大。

对于需要精确执行指令或复杂工具交互的任务，通常需要选择更强大的模型（如 GPT-4o, Claude 3.5 Sonnet），即使成本更高。

对于简单任务或对成本敏感的应用，可以尝试更经济的模型，但需要接受其能力上的限制，并可能需要更详细的 Prompt 来弥补。

错误处理机制 (Error Handling):

AI Agent 的执行过程（尤其是涉及 LLM 调用和外部工具交互） inherently 存在不确定性。

利用 n8n 节点设置中的 “On Error” 选项（如 Continue (using error output), Stop Workflow）来定义工作流在遇到错误时的行为。

对于关键业务流程，考虑设置专门的 Error Workflow，在主流程失败时触发，用于记录错误、发送通知或执行回滚操作。

成本意识 (Cost Management):

AI Agent 的每次执行，尤其是涉及多次 LLM 调用（思考、工具选择、最终响应）和外部 API 工具调用时，都可能产生费用。

监控 Token 使用: 了解所选模型的 Token 定价。在开发和测试阶段，使用 Return Intermediate Steps 来观察 Agent 的迭代次数和大致的 Token 消耗。

Make中文教程：自动化基础

小红书自动化：如何利用Make制作个人自媒体中心，批量生成爆款笔记

微信公众号图文混排文章自动化实战：利用Make 批量制作