26b - n8n AI Agent 节点配置

本文是《AI Agent 实战手册》第 26 章第 2 节。 上一节：26a-n8n与Make对比 | 下一节：26c-工作流蓝图集

概述

n8n 的 AI Agent 节点是将普通自动化工作流升级为智能 Agent 系统的核心组件。与简单的 LLM 调用不同，AI Agent 节点能够自主推理、选择工具、执行操作并循环迭代直到完成目标。本节深入讲解 AI Agent 节点的完整配置：模型选择与参数调优、工具绑定策略、记忆系统设置、输出解析、Agent 类型选择，以及多 Agent 链式编排等高级主题，帮助你构建生产级 AI 工作流。

1. AI Agent 节点架构概览

核心组件

n8n 的 AI Agent 节点基于 LangChain 框架构建，由四个核心组件组成：

Agent 循环机制

AI Agent 节点的工作流程是一个”思考-行动-观察”循环：

1. 接收输入 → 用户消息或触发器数据到达
2. 思考（Think） → LLM 评估："我应该怎么处理这个输入？"
3. 决策（Decide） → LLM 选择：调用工具、直接回复、或放弃
4. 行动（Act） → 如果选择工具：n8n 执行工具并捕获结果
5. 观察（Observe） → LLM 接收工具结果，评估："问题解决了吗？"
6. 重复或响应 → 目标达成则生成最终回复，否则回到步骤 2

⚠️ 重要变更：自 n8n v1.82.0 起，AI Agent 节点已统一为 Tools Agent 类型，移除了之前的 Agent 类型选择下拉菜单。所有 AI Agent 节点现在都使用 LLM 原生的 function/tool calling 能力。旧版工作流中设置为”Tools Agent”的节点将继续正常工作。

2. 模型选择与配置

支持的模型提供商

n8n 通过子节点方式支持多种 LLM 提供商，每个提供商作为独立的 Chat Model 子节点连接到 AI Agent：

💡 价格信息截止日期：2025 年 7 月。各提供商价格可能随时调整，请以官方最新定价为准。

模型配置步骤

步骤 1：添加 Chat Model 子节点

1. 在画布上点击 AI Agent 节点
2. 点击 Chat Model 下方的 + 按钮
3. 搜索并选择你的模型提供商（如 “OpenAI Chat Model”）
4. 创建或选择已有的 API 凭证

步骤 2：配置模型参数

关键参数说明：
├── Model（模型）：选择具体模型版本
├── Temperature（温度）：0.0-2.0，控制输出随机性
│   ├── 0.0-0.3：确定性任务（数据提取、分类）
│   ├── 0.5-0.7：平衡模式（通用 Agent 推荐）
│   └── 0.8-1.2：创意任务（内容生成）
├── Max Tokens（最大 token 数）：限制单次回复长度
├── Top P：核采样参数，通常保持默认 1.0
└── Frequency/Presence Penalty：控制重复度

步骤 3：验证工具调用支持

关键要求：AI Agent 节点要求模型支持 function calling / tool calling。不支持此功能的模型将无法正常使用工具。

支持工具调用的模型：

• OpenAI：GPT-4o、GPT-4.1、GPT-4o-mini
• Anthropic：Claude 4 系列、Claude 3.5 系列
• Google：Gemini 2.5 Pro、Gemini 2.5 Flash
• Ollama：需选择支持 tool calling 的模型（如 Llama 3.3、Qwen 3）

本地模型配置（Ollama）

对于需要数据隐私或离线运行的场景，可通过 Ollama 连接本地模型：

# 1. 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
 
# 2. 拉取支持工具调用的模型
ollama pull llama3.3
ollama pull qwen3:14b
 
# 3. 启动 Ollama 服务（默认端口 11434）
ollama serve

在 n8n 中配置：

1. 添加 “Ollama Chat Model” 子节点
2. Base URL 设置为 http://localhost:11434（Docker 环境使用 http://host.docker.internal:11434）
3. 选择已拉取的模型

⚠️ 本地模型注意事项：部分本地模型的工具调用能力不如商业 API 稳定，可能出现只调用一个工具就生成最终回答的情况。建议先用简单工作流测试工具调用可靠性。

动态模型路由

在生产环境中，可以根据任务类型动态选择模型以优化成本：

[触发器] → [Switch 节点：分类任务类型]
             ├── 简单任务 → [AI Agent + GPT-4o-mini]（低成本）
             ├── 复杂推理 → [AI Agent + Claude Sonnet]（高质量）
             └── 编码任务 → [AI Agent + DeepSeek-V3]（高性价比）

提示词模板：System Prompt 配置

System Prompt 是 AI Agent 行为的核心定义。在 AI Agent 节点设置面板的 System Message 字段中配置：

你是 [角色名称]，负责 [核心职责]。

## 可用工具
- [工具1名称]：[何时使用、输入输出说明]
- [工具2名称]：[何时使用、输入输出说明]

## 行为准则
- [具体指令1]
- [具体指令2]
- [约束条件]

## 回复格式
[期望的输出格式说明]

## 错误处理
如果 [某种情况]，则 [采取的行动]。

动态 Prompt 示例（使用 n8n 表达式注入上下文）：

你正在协助用户 {{ $json.userName }}。
当前时间：{{ $now.format('yyyy-MM-dd HH:mm') }}
用户账户类型：{{ $json.accountType }}
{{ $json.accountType === 'premium' ? '请提供优先支持选项。' : '' }}

3. 工具绑定

工具类型总览

n8n 提供多种工具类型，通过子节点连接到 AI Agent 的 ai_tool 输入：

工具绑定步骤

步骤 1：添加工具子节点

1. 点击 AI Agent 节点上 Tool 下方的 +
2. 搜索并选择工具类型
3. 配置工具参数和凭证

步骤 2：编写清晰的工具描述

工具描述决定了 Agent 何时以及如何使用该工具。描述质量直接影响 Agent 的工具选择准确性。

❌ 差的描述："用于数据查询"
✅ 好的描述："通过客户邮箱查询客户数据库。返回客户档案，包含姓名、
   购买历史和账户状态。输入：客户邮箱地址字符串。"

Workflow Tool：最强大的工具类型

Workflow Tool 允许 Agent 调用其他 n8n 工作流作为工具，是构建模块化 Agent 系统的关键：

模式 1：专业化子 Agent

主 Agent
├── Tool: 客户查询工作流（查询 CRM）
├── Tool: 库存检查工作流（查询数据库）
├── Tool: 发送通知工作流（处理告警）
└── Tool: 数据分析工作流（生成报告）

模式 2：权限隔离

敏感操作放在独立工作流中，拥有独立的凭证和日志。Agent 可以触发但无法直接访问凭证。

配置要点：

• 被调用的工作流需要设置为”可被其他工作流调用”
• 工具描述要明确说明输入参数和返回格式
• 建议为每个子工作流添加错误处理

MCP 集成：连接外部 MCP Server

n8n 原生支持 Model Context Protocol（MCP），通过两个节点实现：

MCP Client Tool 配置：

1. 添加 “MCP Client Tool” 到 AI Agent
2. 配置 MCP Server 连接方式：
   • SSE（Server-Sent Events）：填写 MCP Server URL
   • Stdio：配置命令行启动参数
3. Agent 将自动发现 MCP Server 暴露的所有工具

工具选择最佳实践

1. 从少量工具开始：先用 1-2 个工具验证，再逐步添加。工具越多，Agent 决策越复杂
2. 控制工具数量：建议单个 Agent 不超过 5-6 个工具，超过时考虑路由或子 Agent 架构
3. 测试工具边界：验证 Agent 对不同输入是否选择了正确的工具
4. 考虑工具成本：搜索 API、高级 API 等有调用费用，添加使用限制或使用更便宜的替代方案

4. 记忆系统设置

n8n 采用模块化的记忆方案，通过子节点连接到 AI Agent 的 ai_memory 输入。不同记忆类型适用于不同场景。

记忆类型对比

各记忆类型配置详解

Simple Buffer Memory（入门推荐）

最简单的记忆选项，适合开发测试：

1. 点击 AI Agent 的 Memory 下方 +
2. 选择 “Simple Memory”
3. 无需额外配置

消息存储在 n8n 内存中，工作流执行完成或 n8n 重启后丢失。

Window Buffer Memory（成本控制）

限制记忆的消息数量，防止上下文无限增长：

1. 添加 “Window Buffer Memory”
2. 设置 Context Window Length（如 10 条消息）
3. 超出窗口的旧消息自动丢弃

推荐设置：

• 简单客服：5-8 条消息
• 复杂对话：10-15 条消息
• 成本敏感场景：3-5 条消息

💡 成本提示：记忆中的每条消息在每次交互时都会发送给 LLM，长历史会显著增加 token 消耗。

Postgres Chat Memory（生产首选）

适合需要持久化对话历史的生产应用：

1. 添加 “Postgres Chat Memory”
2. 连接 Postgres 凭证（Host、Port、Database、User、Password）
3. 配置 Session ID（每个对话的唯一标识）

// 动态 Session ID 示例——基于用户和对话
{{ $json.userId }}_{{ $json.conversationId }}
 
// 基于 Webhook 来源（如 WhatsApp）
{{ $('Webhook').item.json.body.from }}

关键注意事项：

• Session ID 决定加载/保存哪个对话，必须保持一致
• 如果 Session ID 每次都不同，Agent 将无法记住之前的对话
• 多个 Postgres Chat Memory 节点默认共享同一个记忆实例
• 使用 Chat Memory Manager 节点可以执行记忆的增删改操作

Vector Store Memory（语义召回）

与普通缓冲记忆不同，Vector Store Memory 将消息转换为向量嵌入存储，检索时通过语义搜索找到最相关的历史消息：

1. 添加 “Vector Store Memory”
2. 连接 Embeddings 子节点（必需，如 Embeddings OpenAI）
3. 连接 Vector Store 子节点（如 Pinecone、Qdrant、Supabase）
4. 配置 Session ID

与缓冲记忆的核心区别：

• 缓冲记忆：返回最近 N 条消息（按时间顺序）
• 向量记忆：返回语义最相关的消息（按相关性排序）

适用场景：

• 长期运行的对话，最近消息不一定最相关
• 知识库型 Agent，语义检索比时间顺序更重要
• 需要跨越上下文窗口限制的召回

记忆常见问题与解决

5. 输出解析

当需要 Agent 返回结构化数据（JSON、列表等）而非自由文本时，使用输出解析器。

启用输出解析

1. 在 AI Agent 节点设置中启用 Require Specific Output Format
2. 启用后出现 ai_outputParser 连接点
3. 添加输出解析器子节点

输出解析器类型

Structured Output Parser 配置

方法 1：从 JSON 示例生成 Schema

提供期望输出的示例，解析器自动推断 Schema：

{
  "customerName": "张三",
  "orderTotal": 149.99,
  "items": ["商品A", "商品B"],
  "priority": "high"
}

方法 2：手动定义 JSON Schema

精确控制输出结构：

{
  "type": "object",
  "properties": {
    "customerName": { "type": "string" },
    "orderTotal": { "type": "number" },
    "items": {
      "type": "array",
      "items": { "type": "string" }
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  },
  "required": ["customerName", "orderTotal"]
}

⚠️ Schema 限制：n8n 的 JSON Schema 实现不支持 $ref 引用，Schema 必须自包含。

Auto-fixing Output Parser

当 LLM 输出接近但不完全匹配 Schema 时，自动修复解析器提供容错能力：

1. 添加 “Auto-fixing Output Parser”
2. 连接一个 Structured Output Parser（作为目标格式）
3. 连接一个 Chat Model（用于修复格式）

工作原理：解析失败时，将格式错误的输出发送给 LLM 并要求修正格式。这会增加一次额外的 LLM 调用，但能恢复大多数常见格式错误。

生产环境最佳实践：分离推理与格式化

输出解析器在 AI Agent 节点中的可靠性不如在 LLM Chain 节点中。推荐的生产模式：

[AI Agent] → [Set 节点：提取响应] → [LLM Chain + Output Parser] → [输出]

Agent 负责推理和工具使用，单独的 LLM Chain 配合输出解析器处理最终格式化。这种分离比让 Agent 直接输出结构化数据更可靠。

6. Agent 架构模式

单 Agent 模式

最简单的架构，一个 AI Agent 连接多个工具：

[触发器] → [AI Agent + 工具 A, B, C] → [输出]

适用：简单任务、原型验证、工具少于 5 个 限制：工具过多会导致 Agent 混乱，调试困难

路由模式（分类分发）

先分类请求，再路由到专业 Agent：

[触发器] → [LLM 分类器] → [Switch 节点]
                            ├→ [Agent A：订单处理]
                            ├→ [Agent B：产品咨询]
                            └→ [Agent C：技术支持]

适用：请求类别明确、不同领域需要不同专业知识

编排器模式（层级多 Agent）

主 Agent 通过 Workflow Tool 委托给专业子 Agent：

[触发器] → [主编排 Agent]
             ├→ [Workflow Tool: 邮件 Agent]
             ├→ [Workflow Tool: 日历 Agent]
             └→ [Workflow Tool: 研究 Agent]

Workflow Tool 描述示例：

email_agent: 处理邮件相关任务，包括撰写、搜索收件箱和管理草稿。
当用户请求涉及发送或阅读邮件时使用此工具。

calendar_agent: 管理日历事件，包括安排、重新安排和检查可用时间。
当用户请求涉及会议或时间安排时使用此工具。

顺序链模式

Agent 按阶段处理，每个 Agent 处理管线的一部分：

[触发器] → [Agent A: 调研] → [Agent B: 分析] → [Agent C: 报告] → [输出]

上下文传递（使用 n8n 表达式）：

// Agent B 的 System Prompt
你正在分析上一步的调研结果。
调研发现：{{ $json.researchOutput }}
你的任务：提取关键洞察并结构化整理。

7. 高级配置

Temperature 与 Token 参数调优

错误处理配置

启用 Continue On Fail

1. 点击 AI Agent 节点 → 设置（齿轮图标）
2. 启用 Continue On Fail
3. 工具失败时 Agent 收到错误消息并决定如何继续

超时设置

• AI Agent 节点：检查超时选项
• HTTP Request 工具：设置明确的请求超时
• 工作流级别：设置整体执行超时

降级回退

在 Agent 后添加 Code 节点处理失败情况：

// Agent 后的 Code 节点
if ($json.error || !$json.response) {
  return [{
    json: {
      response: "抱歉，我暂时无法处理您的请求。请稍后重试或联系人工客服。",
      fallback: true
    }
  }];
}
return $input.all();

多 Agent 链式编排

共享记忆的多 Agent 系统：

多个 Agent 可以通过共享同一个 Postgres Chat Memory（使用相同的 Session ID）来实现记忆共享。但需注意：

• 确保不同 Agent 的输出不会互相干扰
• 使用 Chat Memory Manager 节点管理记忆的读写
• 考虑为每个 Agent 添加角色标识前缀

Manager-Worker 模式：

[用户输入] → [Manager Agent（带 Buffer Memory）]
               ├→ [Worker Agent 1（专业工具集 A）]
               ├→ [Worker Agent 2（专业工具集 B）]
               └→ [Worker Agent 3（专业工具集 C）]
             → [Manager Agent 汇总] → [输出]

Embeddings 配置

使用 Vector Store Memory 或 RAG 工作流时需要配置 Embeddings 子节点：

⚠️ 关键提醒：如果更换 Embedding 模型，必须重新嵌入所有已有数据。不同模型产生的向量空间不兼容。

实战案例：构建智能客服 Agent

场景描述

为电商平台构建一个能查询订单、搜索产品、处理退款请求的智能客服 Agent。

完整配置

1. Chat Model 配置

• 提供商：OpenAI
• 模型：GPT-4o-mini（成本效益最优）
• Temperature：0.3（客服场景需要一致性）
• Max Tokens：2048

2. 工具配置

3. 记忆配置

• 类型：Postgres Chat Memory
• Session ID：{{ $json.customerId }}_{{ $json.channelId }}

4. System Prompt

你是 TechStore 电商平台的客服助手。

## 可用工具
- order_lookup：通过订单号或客户邮箱查询订单。用于订单状态、物流追踪等问题。
- product_search：搜索产品目录。用于产品咨询、库存查询、价格确认。
- create_ticket：创建人工客服工单。用于退款超过 500 元、投诉、复杂技术问题。

## 行为准则
- 回复前先确认客户身份（订单号或注册邮箱）
- 退款请求超过 500 元，使用 create_ticket 转人工
- 不要透露内部定价或利润信息
- 产品缺货时，主动推荐类似替代品
- 保持友好专业的语气

## 回复格式
- 先确认理解客户的问题
- 提供答案或解决方案
- 结尾询问是否还需要其他帮助

## 不确定时
- 找不到订单：请客户核实订单号或邮箱
- 超出职责范围：说明并使用 create_ticket 转人工

5. 输出处理

Agent 后添加 Switch 节点，根据是否触发了 create_ticket 工具分流：

• 已创建工单 → 发送工单确认通知
• 未创建工单 → 直接返回 Agent 回复

测试验证

测试用例 1：
输入："我的订单 ORD-12345 到哪了？"
预期：Agent 调用 order_lookup，返回物流状态

测试用例 2：
输入："你们有蓝牙耳机吗？"
预期：Agent 调用 product_search，返回产品列表

测试用例 3：
输入："我要退款 800 元"
预期：Agent 调用 create_ticket，告知已转人工处理

避坑指南

❌ 常见错误

1. 未连接任何工具就使用 AI Agent

   • 问题：AI Agent 节点要求至少连接一个工具子节点，否则报错 “Agent requires at least one tool”
   • 正确做法：至少添加一个工具（即使是 Calculator 也行），如果只需要对话功能，使用 Basic LLM Chain 节点代替

2. 使用不支持工具调用的模型

   • 问题：部分模型（尤其是较旧的开源模型）不支持 function calling，导致 Agent 无法正常调用工具
   • 正确做法：确认所选模型支持 tool calling。OpenAI GPT-4o、Anthropic Claude 3.5+、Gemini 2.5 系列均支持

3. Session ID 不一致导致记忆失效

   • 问题：每次请求的 Session ID 不同，Agent 每次都从零开始，无法记住之前的对话
   • 正确做法：为同一用户/对话使用一致的 Session ID，如 {{ $json.userId }}_{{ $json.conversationId }}

4. 工具描述模糊导致选择错误

   • 问题：工具描述写得太笼统（如”处理数据”），Agent 无法准确判断何时使用
   • 正确做法：描述中明确说明输入格式、输出内容、使用时机

5. Agent 陷入无限循环

   • 问题：工具返回不明确的结果，Agent 反复调用同一工具
   • 正确做法：确保工具返回清晰可操作的数据；在 System Prompt 中定义完成标准；设置最大迭代次数限制

6. 直接在 Agent 中要求结构化输出

   • 问题：Agent 的推理循环会干扰结构化输出生成，导致 JSON 格式不稳定
   • 正确做法：Agent 负责推理，后接独立的 LLM Chain + Output Parser 处理格式化

7. 记忆过长导致成本失控

   • 问题：不限制记忆长度，长对话中每次交互都发送完整历史，token 成本指数增长
   • 正确做法：使用 Window Buffer Memory 限制历史长度（5-15 条消息），或使用 Vector Store Memory 按语义召回

8. 更换 Embedding 模型后未重新索引

   • 问题：更换 Embedding 模型后，旧向量与新向量不兼容，语义搜索结果混乱
   • 正确做法：更换模型后必须重新嵌入所有已有数据

✅ 最佳实践

1. 从简单开始，逐步增加复杂度：先用单 Agent + 1-2 个工具验证核心流程，再添加记忆、更多工具和子 Agent
2. 版本管理 System Prompt：将 Prompt 存储在版本控制系统中，Agent 行为异常时可以 diff 对比变更
3. 监控 token 消耗：添加 Code 节点记录每次执行的 token 使用量，设置成本告警
4. 设计降级方案：Agent 失败时提供友好的回退消息，而非让工作流崩溃
5. 使用 Staging 环境：Prompt 微调可能导致行为微妙变化，先在测试环境验证
6. 记录工具契约：为每个工具文档化输入格式、输出格式、错误条件和速率限制

相关资源与延伸阅读

1. n8n AI Agent 官方文档 — AI Agent 节点的完整参数参考和配置说明 https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/ 

2. n8n Advanced AI 文档 — n8n AI 功能的全面指南，包括所有 AI 子节点 https://docs.n8n.io/advanced-ai/ 

3. n8n 工作流模板库 — 社区贡献的 AI Agent 工作流模板，可直接导入使用 https://n8n.io/workflows/ 

4. n8n 社区论坛 — AI Agent 相关问题讨论、故障排查和经验分享 https://community.n8n.io/ 

5. n8n GitHub 仓库 — 开源代码、Issue 追踪和功能请求 https://github.com/n8n-io/n8n 

6. LangChain 官方文档 — n8n AI Agent 底层框架的技术文档 https://js.langchain.com/docs/ 

7. Ollama 官方网站 — 本地 LLM 运行工具，支持与 n8n 集成 https://ollama.com/ 

8. n8n MCP 集成指南 — 如何在 n8n 中使用 Model Context Protocol https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.toolmcp/ 

9. n8n 本地 LLM 设置指南 — 使用 Ollama 等工具在本地运行 LLM 的完整教程 https://blog.n8n.io/local-llm/ 

10. n8n AI Agent 架构模式 — Product Compass 的 AI Agent 架构深度解析 https://www.productcompass.pm/p/ai-agent-architectures 

参考来源

• n8n AI Agent Node Documentation （n8n 官方，持续更新）
• n8n AI Agents: Complete Guide to Agentic Workflows （Roland Softwares，2025-12）
• n8n AI Agent Node Tutorial, Examples, Best Practices （LogicWorkflow，2025-10）
• How to Build AI Agents with n8n （The Vibe Marketer，2025-10）
• n8n AI Agents: Build Intelligent Automation with OpenAI, Claude, and MCP （Flowmondo，2025）
• n8n Structured Output Parser Documentation （n8n 官方，持续更新）
• n8n Postgres Chat Memory Documentation （n8n 官方，持续更新）
• Complete Setup Guide for Local LLMs with n8n （n8n Blog，2025-05）
• n8n Plans and Pricing （n8n 官方，持续更新）
• How to Build an AI Agent in n8n for Beginners: Complete 2025 Guide （Snaplama，2025-12）

📖 返回 总览与导航 | 上一节：26a-n8n与Make对比 | 下一节：26c-工作流蓝图集