零代码搭建AI Agent工作流：n8n从入门到实战-平芜编程栈

如果你接触 AI 应用开发已经有一阵子，大概率会碰上一个“断层”：大模型本身很强，聊天问答、文本生成一学就会；但真要把模型接到自己的数据、业务系统、定时任务、通知渠道里，立刻就被 API 文档、鉴权、参数拼接、异常处理、部署运维这些东西拦住。市面上不是没有框架，LangChain、Dify、Coze 各有拥趸，但对很多没有完整编程背景、又想把 AI 落地的产品、运营、数据分析师来说，它们的上手曲线依然太陡。

n8n 就是用来填这个断层的。它本身是一个开源的工作流自动化平台，后来加入了完整的 AI Agent 节点体系，让“连接大模型 + 调用工具 + 访问知识库 + 触发业务动作”这件事变得可视化、可配置、可维护。换句话说，你可以不写代码，也可能搭建出属于自己的 AI 自动化工作流。这也是本篇文章的核心判断：n8n 最值钱的地方，不是“可视化拖拽”这个形式，而是它把 AI Agent 开发中高频复用的工程逻辑做成了可组合的节点，让普通人也能把想法变成能跑的服务。

这篇文章会从基础概念讲起，然后带你把 n8n 部署起来，配置好大模型凭证，再动手搭建一个带知识库问答能力的 AI Agent 工作流，最后补上常见问题排查和工程化建议。文章内容较多，建议先收藏，再照着操作。

1. 这篇文章真正要解决的问题

先说清楚：n8n 不是唯一能做 AI Agent 的工具，但它在“接近真实业务落地”这件事上，比很多平台更贴近开发者的习惯。如果你属于下面三类人，这篇文章就是为你准备的：

第一类：没有编程基础，但想用 AI 解决重复工作的人。比如运营同学每周要整理十几个平台的评论，人工分类、打标签、生成汇总报告。用 n8n 可以搭一个工作流：定时抓取 → 大模型判断情绪与主题 → 写入表格 → 推送汇总到钉钉或飞书。整个过程不需要写业务代码，只需要把节点拖出来、连上、填好参数。

第二类：会一点代码，但不想维护复杂 AI 工程的开发者。用 LangChain 写 Agent，意味着要处理 Prompt 模板、工具函数注册、模型调用、历史消息管理、重试机制。n8n 把这些封装成了节点。你只需要关心“业务逻辑怎么编排”，而不是“底层抽象怎么设计”。

第三类：正在选型 AI 应用搭建平台的团队。到底选 n8n、Dify、Coze 还是自研？这篇会给出一个比较清晰的判断框架：团队有没有私有化需求、需不需要深度定制、工作流要连接多少外部系统。

要特别提醒的是：n8n 解决的是“编排”问题，不是“模型训练”问题，也不是“知识库算法”问题。它默认不负责优化大模型的推理质量，也不能替代向量数据库本身的调优。你要做的，是把模型能力、数据检索、业务触发三者组装起来。

2. n8n 与 AI Agent 的前置概念

2.1 n8n 是什么

n8n 是一个开源的工作流自动化工具，核心设计思路是“节点（Node）+ 连接（Connection）”。每个节点完成一个具体操作，比如发送 HTTP 请求、读取数据库、调用大模型、发送邮件；节点之间用连线串联起来，数据从一个节点流向另一个节点，形成完整的工作流。

n8n 最早对标的是 Zapier、Make 这类 SaaS 自动化工具。但它的关键差异在于：

开源，可以自托管，数据不出内网；
支持代码节点，能嵌入 JavaScript 或 Python 片段；
支持自建 Community Nodes，扩展性强；
对 AI 场景做了深度适配，内置了大量 AI Agent 相关节点。

这里要先破除一个常见误解：很多人看到“可视化工作流”，会下意识觉得“这是低代码玩具，干不了正经活”。其实 n8n 的底层是真正的运行时引擎，节点本质上是抽象后的函数调用，数据流是真实的类型化数据。它适合做生产级自动化，而不只是个人小工具。

2.2 AI Agent 是什么

AI Agent（智能体）这个概念在 2024 年到 2025 年是 AI 领域最重要的关键词之一。它的核心不是“聊天”，而是“执行”。

早期的大模型应用是人提问、模型回答，一轮结束。AI Agent 则是一个循环：模型先理解任务 → 决定需要调用什么工具 → 执行工具并获取结果 → 把结果带回来继续推理 → 重复直到任务完成。

举个例子：用户说“帮我查一下本周销售数据，并分析下降原因”。普通聊天机器人只会回复“我没有权限访问你的数据”。而一个 Agent 会：

判断需要查询数据库；
调用预设的“查询销售数据”工具；
拿到数据后继续判断是否需要生成趋势分析；
最后输出一份完整报告。

在 n8n 里，这个循环就是由一个 AI Agent 节点来承载的。你不需要写 while 循环，不需要管理工具返回结果怎么塞回模型上下文，n8n 已经把这些封装好了。

2.3 n8n、Dify、Coze 怎么选

这是写 n8n 教程绕不开的问题。简单给一个决策框架：

选型维度	n8n	Dify	Coze
核心定位	通用工作流自动化 + AI 节点	LLM App 开发平台	LLM App 开发平台
优势	连接器丰富、贴近工程化、可自托管	知识库/RAG 一体化强、Prompt 管理体验好	国内生态好、插件丰富、上手最快
知识库	需要配合外部向量库	内置完整 RAG 能力	内置知识库，但部分能力依赖平台
私有化	完全开源可私有化	社区版可用，部分能力受限制	受限，企业版为主
适合谁	想深度控制业务流程和数据流的人	想做知识库问答、LLM 应用原型的人	想快速验证想法、不关心部署的人

一个容易被忽略的结论是：n8n 和 Dify 并不是只能二选一。在实际项目里，有人用 Dify 做知识库管理，用 n8n 做上游数据采集和下游业务分发；也有人用 n8n 的向量存储节点直接对接 Qdrant、Pinecone，自己搭完整 RAG 链路。这篇文章的示例会采用“n8n + 大模型 + 外部向量库”的方式，目的是把知识库搭建的原理讲透。

3. n8n 环境准备与安装部署

3.1 安装方式选择

n8n 的部署方式非常灵活，常见的有：

npm 全局安装（适合本地轻量体验）；
Docker 部署（适合个人开发测试）；
Docker Compose 部署（适合团队和自托管环境）；
n8n Cloud 官方云服务（适合不想管运维的人）；
Kubernetes 部署（适合企业级高可用场景）。

如果你是第一次接触，推荐优先使用 Docker 部署。原因很简单：Docker 能帮你把 Node.js 运行时、依赖版本、数据目录全都隔离好，卸载也干净。避免出现“我在本地装好了，换个机器又跑不起来”的问题。

在开始之前，请确保你的机器已经安装好了 Docker 和 Docker Compose。版本方面没有严格的硬性要求，以 Docker 官方当前稳定版本为准即可。

3.2 Docker Compose 部署 n8n 的最小配置

下面是一个最小可用的 docker-compose.yml。为了后面演示知识库功能，我会在同一个编排文件里加入一个 Qdrant 向量数据库。如果你暂时用不到知识库，可以先只保留 n8n 服务。

version: "3.8" services: n8n: image: docker.n8n.io/n8nio/n8n container_name: n8n restart: unless-stopped ports: - "5678:5678" environment: - N8N_HOST=localhost - N8N_PORT=5678 - N8N_PROTOCOL=http - N8N_ENCRYPTION_KEY=please-change-me-to-a-random-string - GENERIC_TIMEZONE=Asia/Shanghai - TZ=Asia/Shanghai volumes: - n8n_data:/home/node/.n8n qdrant: image: qdrant/qdrant container_name: qdrant restart: unless-stopped ports: - "6333:6333" - "6334:6334" volumes: - qdrant_data:/qdrant/storage volumes: n8n_data: qdrant_data:

然后将这份配置保存为docker-compose.yml，在同一个目录下执行：

docker compose up -d

启动完成后，在浏览器里访问：

http://localhost:5678

首次访问会要求创建一个管理员账号。这个账号是 n8n 本地的管理账号，和后面要配置的大模型 API 凭证是两回事。

启动过程中如果出现镜像拉取缓慢或超时，可以先检查 Docker 的网络配置，或者使用本机构的镜像加速方案。注意：这里不讨论任何非正规网络手段。

3.3 配置环境变量

上面的 compose 文件里已经写了一个环境变量N8N_ENCRYPTION_KEY。这个变量非常重要，它用来加密 n8n 存储的敏感信息，例如各种账号凭证、API Key。第一次启动前就应该设置好，而且要妥善保存。如果中途改了这个值，n8n 将无法解密旧的凭证数据。

生产环境建议把敏感配置放到独立的.env文件，并在 docker-compose.yml 中通过${VAR}方式引用，而不是明文写在编排文件里。

4. n8n 的核心概念：工作流、节点与凭证

在开始搭建 AI Agent 之前，先花几分钟理解 n8n 最核心的三个抽象。这三个概念理解透了，后面操作会顺畅很多。

第一个概念：工作流（Workflow）。工作流是 n8n 的基本执行单元，可以理解成一个流程蓝图。一个工作流里包含若干个节点，以及节点之间的连线。点击“Execute Workflow”按钮可以手动触发，也可以用 Webhook、定时触发器、应用事件等方式自动触发。

第二个概念：节点（Node）。节点是具体动作的执行者。n8n 自带的节点多达几百个，覆盖 HTTP 请求、数据库、邮件、云存储、消息推送等领域。AI 相关的节点包括：AI Agent、Basic LLM Chain、Question Answer Chain、Tool、Embeddings、Vector Store 等。每个节点通常有几个核心配置：参数（Parameters）、凭证（Credential）、连接（Connections）。

第三个概念：凭证（Credential）。凭证相当于 n8n 帮你保存的密钥。你需要在 n8n 后台把大模型的 API Key、数据库的账号密码、第三方应用的访问令牌配置好。节点运行时通过凭证拿到授权。

理解这三者的关系，可以用一个类比：工作流是图纸，节点是工人，凭证是工人的工牌。图纸决定做什么，工人执行具体动作，工牌决定有权限访问哪些资源。

5. 核心流程拆解：搭建一个 AI Agent 工作流

5.1 选择一个具体场景

为了让教程不至于停在概念层，我们设定一个具体场景：搭建一个“会议室预定助手” AI Agent。

这个 Agent 的能力要求如下：

用户通过 Webhook 发起请求，例如“帮我查一下明天下午有没有可用的会议室”；
AI Agent 判断是否需要查询会议室数据；
如果需要，Agent 调用一个工具节点，去查一个模拟的数据源；
Agent 把查询结果整理成自然语言回复；
整个交互保持多轮对话能力。

这个场景虽然看起来简单，但它覆盖了 AI Agent 的完整链路：入口 → 意图判断 → 工具调用 → 结果返回 → 回复生成。你可以在掌握后把它替换成“查订单状态”“查库存”“生成周报”等真实业务。

5.2 工作流整体设计

在工作流编辑器中，建议先设计以下节点链：

Webhook 节点 → AI Agent 节点 → 工具节点（HTTP Request） ↑ └─ Chat Memory 节点（保存多轮上下文）

其中 Webhook 节点负责接收外部请求；AI Agent 节点是大脑，负责理解用户输入并决定是否调用工具；工具节点是 Agent 可调用的“手臂”，这个示例中是一个 HTTP Request 节点；Chat Memory 节点用于保存对话历史。

这里有一个新手最容易犯的错误：把 AI Agent 节点直接理解为“一次大模型调用”。实际上 AI Agent 节点内部是一个会反复推理的循环。如果一个任务需要调用两次工具、中间还要根据第一次结果判断下一步，Agent 节点会自动完成这个循环，而不是像普通 LLM Chain 那样只跑一次。

5.3 配置大模型连接

在 n8n 后台左侧菜单进入“Credentials”，点击“Add Credential”，选择对应的大模型服务商。

以 OpenAI 兼容接口为例，n8n 支持多种模型服务商，包括 OpenAI、Anthropic、Google Gemini、Azure OpenAI，以及各种本地部署的 OpenAI 兼容 API。如果你的模型服务商提供了 OpenAI 兼容接口，可以直接选 OpenAI 类型，把 API Key 和 Base URL 替换掉。

配置界面需要填写的核心字段：

API Key：模型服务商提供的密钥；
Base URL：大部分国内模型服务或本地部署框架都提供 OpenAI 兼容路径，按服务商文档填写；
模型名称：在 AI Agent 节点或模型节点里指定。

如果使用本地部署的大模型，比如通过 Ollama 或 vLLM 提供的 OpenAI 兼容接口，同样可以用这个方式接入。这一步可以说是 n8n 里打通“任意大模型”的关键。

5.4 配置工具节点

在 n8n 中，Agent 调用工具的方式和 LangChain 的 Tool 机制类似。每个工具节点需要描述清楚“这个工具能干什么、参数是什么”，模型才能决定何时调用。

以 HTTP Request 工具为例，我们需要告诉模型：

这个工具可以查询会议室占用情况；
参数包括日期、时间段；
返回的数据结构。

工具描述要写在节点配置的描述字段中。这里真正容易踩坑的地方是：给模型的工具描述要写自然语言，而不是写代码注释。模型依靠这个描述理解工具功能，描述越具体，调用准确率越高；描述含糊，模型会频繁误调用或者干脆不调用。

5.5 配置 Chat Memory

AI Agent 要支持多轮对话，必须配置 Chat Memory 节点。这个节点负责把前面的对话内容保存起来，在后续请求时自动回传给大模型，让它“记得”上下文。

Chat Memory 的存储方式可以选择内存、Redis 或数据库。生产环境建议使用 Redis 或数据库，避免 n8n 重启后上下文丢失。

6. 完整示例：n8n 搭建知识库问答 AI Agent

接下来把示例升级一下，做一个更接近生产场景的知识库问答 AI Agent。这个工作流的目标是：用户提问 → 系统在知识库中检索相关内容 → 把检索结果交给大模型生成回答。

这种模式在业界被称为 RAG（Retrieval-Augmented Generation，检索增强生成）。它解决的是大模型“不知道你私有数据”的问题。要理解 RAG 为什么有效，关键是理解两步：先检索到最相关的文本片段，再让大模型基于这些片段生成回答。这样模型不需要“记住”你的文档，只需要“阅读”你给的片段。

6.1 知识库写入流程

知识库搭建的第一步是把文档切块、向量化、存入向量数据库。在 n8n 中，这个流程可以通过一个独立的“索引工作流”完成。

文档 → 文本切分 → Embedding 向量化 → 写入 Qdrant

先准备一份 Markdown 格式的员工手册作为示例知识库文件，内容包含“休假申请流程”“会议室预定规则”“报销额度限制”等信息。

然后利用 n8n 的 Read/Write Files from Disk 节点读取文档，用 Text Splitter 节点切分文本。文本切分是 RAG 流程中容易被忽略但影响很大的环节。切分太小，检索到的片段缺乏上下文；切分太大，超出模型上下文窗口。常见的做法是按固定长度切分，并设置重叠区间。

Embedding 节点负责把文本转成向量。这里需要配置和大模型同服务商或者独立服务商的 Embedding 模型。向量化之后，用 Vector Store 节点把数据写入 Qdrant 集合。

6.2 知识库查询工作流

查询侧的工作流设计如下：

Webhook 节点 → AI Agent 节点 ├─ Chat Memory 节点 └─ 工具节点：Vector Store 查询

当用户提问时，AI Agent 判断这个问题需要知识库内容，于是调用 Vector Store 工具去 Qdrant 里做相似度检索，取出 Top K 条相关文本，再基于这些文本生成回答。

在 n8n 里，Vector Store 工具节点经过配置后，会自动完成“查询向量库 → 返回相关文档”的操作，不需要手动拼接数据。

6.3 通过 Webhook 测试查询

先用一个简单的 curl 命令测试工作流是否正常。确保工作流处于 Active 状态，然后在终端执行：

curl -X POST http://localhost:5678/webhook/<你的Webhook路径> \ -H "Content-Type: application/json" \ -d '{"sessionId": "test-123", "chatInput": "我本周想休假三天，需要走什么流程？"}'

注意：这里只是示意，<你的Webhook路径>需要替换成 n8n 工作流里 Webhook 节点实际生成的值，请求体字段名也要和你在 Webhook 节点中配置的保持一致。

如果一切正常，你会收到一个 JSON 响应，内容根据你的知识库材料而定。

6.4 前端接入方式

n8n 自带一个简易的 Chat Widget，可以把工作流嵌入网页，也可以使用官方提供的聊天组件。如果你想把 Agent 接入到飞书、钉钉、企业微信，可以在 Webhook 节点后面再加一个对应的消息节点。n8n 的渠道节点负责处理平台消息格式，Agent 的回调会用 Webhook 方式送回到 IM 平台。这种“统一 Agent + 多端接入”的结构，是 n8n 做 AI 应用很吸引人的地方。

7. 运行结果与效果验证

7.1 验证知识库检索质量

工作流跑通以后，第一步要验证的不是“大模型回答得好不好”，而是“知识库有没有召回正确内容”。在 Vector Store 的查询节点上可以单独执行一次，查看返回的文档片段是否符合问题主题。

如果召回结果不对，优先检查：

原始文档有没有被正确切分；
向量化用的 Embedding 模型是否统一（写入和查询必须使用同一个模型）；
查询时设置的相似度阈值是否过高。

7.2 验证 Agent 工具调用能力

在 AI Agent 节点上打开 “Execute Node”，查看模型调用工具的执行日志。你应该能看到模型“思考过程”的摘要：模型决定调用哪个工具、传入了什么参数、工具返回了什么结果。如果模型根本没调用工具，说明工具描述写得不清楚，或者模型上下文里没有收到可用的工具定义。

7.3 验证多轮对话

用同一 sessionId 再发几个问题，检查 Chat Memory 是否生效。例如先问“明天下午有会议室吗”，再问“那后天呢”。如果第二个问题模型还记得是在问会议室，说明上下文管理正常；如果模型回答“我没有上下文”，说明 Chat Memory 节点没有正确接入，或者 sessionId 没有传递。

8. 常见问题与排查思路

问题现象	可能原因	排查方式	解决方案
首次访问 n8n 页面空白或无法打开	容器启动失败，或端口被占用	查看`docker compose logs n8n`	确认端口未被占用，检查环境变量是否完整
配置大模型凭证后节点报错 401	API Key 错误，或 Base URL 不对	在凭证配置页点击 Test	重新生成 API Key，或按服务商文档检查 Base URL
模型返回“工具不存在”或“无可用工具”	工具节点未挂到 Agent 节点，或工具描述为空	检查 AI Agent 节点连接面板	确保工具节点连接到 Agent 的 Tool 输入，补全工具描述
AI Agent 不调用任何工具，总是直接回答	工具描述不清晰，或模型不支持工具调用	查看 Agent 执行日志	重写工具描述，改用结构化 JSON 描述参数；选用支持 function calling 的模型
知识库查询返回空结果	Qdrant 集合为空，或写入和查询的 Embedding 模型不一致	在 Qdrant 控制台查看集合条数	重建索引，使用相同 Embedding 配置
“请安装缺失的包以使用此工作流”	使用了 Community Node，但 n8n 运行环境缺少对应 Python 依赖	查看节点文档，确认依赖包	在容器内按文档安装依赖，或构建自定义 Docker 镜像
飞书多维表格记录很多，只拉到一部分	未处理分页，默认只读取第一页	查看 API 返回的分页字段	在节点或循环中处理分页，或多调用几次 API 再合并结果
工作流手动执行成功，但 Webhook 无法触发	工作流未设置 Active，或 Webhook 路径不一致	检查工作流右上角 Active 开关	将工作流设为 Active 状态，重新复制 Webhook URL
对话历史在多轮后丢失	Chat Memory 使用内存模式，服务重启后清空	查看执行日志中的 Session ID	改用 Redis 或数据库存储记忆

这里要重点说一个搜索热词里反复出现的问题——“请安装缺失的包以使用此工作流。要安装缺失的节点，请先在你的 python 环境中运行”。这个报错通常出现在使用基于 Python 的 Community Node 时。n8n 的官方 Docker 镜像为了保持体积和安全性，预装依赖不是万能的。遇到这种问题，更稳妥的做法是把 n8n 打包成自定义 Docker 镜像，在 Dockerfile 里提前安装好依赖，而不是在生产环境里临时进入容器安装。依赖变更应该进入镜像版本管理，而不是手工操作。

另外，n8n 有社区版和企业版的区别，很多人关心“n8n 收费吗”。官方开源版完全免费，可以自己部署使用；企业版主要多了 SSO 登录、高级权限控制等功能。对个人学习和小团队自托管来说，社区版已经足够。

9. 最佳实践与工程建议

9.1 把工作流当成代码来管理

n8n 支持把工作流导出为 JSON 文件。强烈建议把导出的 JSON 纳入 Git 仓库管理，每个功能变更都走提交记录。这样当你改坏一个工作流时，可以快速回滚到上一个可用的版本。

9.2 凭证管理要遵循最小权限

任何需要外部系统授权的凭证，在 n8n 中都应该使用独立的 API Token，而不是把个人账号密码填进去。这背后是一个基本的权限原则：给 Agent 的最小权限，应该是“刚刚够完成任务”，而不是“所有资源可访问”。尤其是涉及数据库写入、文件删除、生产环境变更时，一定要先用测试环境验证，并做好备份和回滚方案。

9.3 环境隔离

建议区分 development、staging、production 三套 n8n 环境。开发环境随便试验，staging 环境做集成测试，生产环境只部署验证通过的版本。很多团队为了省事，所有工作流都在一个环境里改，结果一次误操作把线上流程全部推乱。三套环境的维护成本并不高，但能避免大量事故。

9.4 日志与可观测性

每个关键节点都打开 “Always Output Data” 选项，或者添加一次性的日志节点。生产环境出现问题时，执行日志是排查的第一手资料。n8n 支持将日志输出到外部日志系统，也可以用 Prometheus 抓取指标做监控。对 AI Agent 来说，特别建议记录每次调用的 token 消耗和延迟，这直接关系到成本控制。

9.5 Prompt 与工具描述要维护成资产

Prompt 和工具描述是 AI 应用效果的核心，但它们不是写一次就完事的。需要像维护代码一样维护它们：版本化、评审、测试。每次修改 Prompt，都应该有一组固定的测试用例，用来验证修改没有破坏已有功能。这在大模型应用工程化中是一个容易被忽视但非常重要的习惯。

9.6 企业级部署注意点

如果要把 n8n 用于企业级场景，需要考虑几个问题：

高可用：n8n 应用多副本部署，数据库使用外部 PostgreSQL，而不是默认的 SQLite；
队列模式：开启 queue mode，把任务执行从主进程剥离；
加密密钥：使用专门的密钥管理服务保存 N8N_ENCRYPTION_KEY；
备份：定时备份 n8n 数据库和外部向量数据库；
网络策略：n8n 到各外部系统之间的访问控制要按业务需要收紧。

n8n 官方提供了企业级部署的推荐方案，但具体架构要结合团队的实际情况来设计，本教程不展开所有细节。

10. 总结与后续学习方向

通过这篇文章，你应该已经理解，n8n 真正降低的不是“AI 能力获取”的门槛，而是“AI 应用落地到业务系统”的门槛。大模型的推理可以交给各种模型服务商，但如何把模型接入到业务数据、如何编排工具调用、如何管理多轮对话、如何连接各类应用，这些才是 n8n 帮你解决的问题。

建议读完这篇文章后，不要直接去尝试搭建一个非常复杂的多智能体系统。先花一晚上时间，把环境搭起来，跑通一个最小的 AI Agent 工作流，比如一个能查天气、查时间的简单助手。然后再逐步加入知识库、加入多轮记忆、加入外部 API。

后续值得重点深入的方向有三个：

RAG 的知识库调优：切分策略、Embedding 模型选择、重排（Re-ranking）都在很大程度上影响问答质量；
Agent 的工具调用设计：工具描述、参数 schema、异常返回设计，决定了模型会不会用、用得好不好；
n8n 与现有业务系统集成：用 Workflow 接入企业内部 OA、CRM、数据库，才能真正释放自动化的价值。

最后再给你一个“兜底”的判断：如果某个工作流在 n8n 里越写越复杂，连线乱成一团，说明业务逻辑本身需要拆分了。这时候不要硬把十几个节点塞进一个工作流，拆成多个子工作流，用 Sub-workflow 节点串联，每一个都保持职责单一。这比任何技巧都重要。