如何在自有 VPS 上搭建 n8n AI Agent

n8n AI agent 是什么，以及它与 chain 的区别

n8n AI agent 是一个独立的 AI Agent 节点，并在其上连接子节点：一个聊天模型、一个或多个工具，以及可选的 memory。您只需用自然语言说明目标，模型就会决定调用哪些工具以及调用顺序，直到能够给出答案。下面的所有内容，都是围绕这一概念进行的配置。

chain 的工作方式正好相反。在 Basic LLM Chain 中，您决定执行步骤，模型只负责生成文本。在 agent 中，模型决定执行步骤，因此同一个问题今天可能只调用模型 1 次，明天却调用 9 次。这一差异决定了本指南中的每个设置。如果您还不熟悉这种循环机制，而不只是不了解 n8n 中的具体功能，那么在用节点组装之前，建议先手动编写一次。因为节点会隐藏您在本指南其余部分需要仔细分析的确切过程。

本文假设 n8n 已经在您控制的计算机上通过 HTTPS 运行。如果尚未完成，请先阅读在 Docker 上自行托管 n8n 并配置真实证书，因为您即将存储的 API key 需要该指南要求配置的 encryption key 备份。对于非 agent 模式的工作流，例如 webhook summarizer 和 scheduled classifier，请参阅Claude 和 n8n 工作流模式。

在确认这里的字段名称之前，请先检查您的版本，因为 n8n 经常修改 AI 节点。

docker compose exec n8n n8n --version

本指南中的名称与截至 2026 年 7 月的 n8n 当前稳定版本一致。从版本 1.82.0 开始，每个 AI Agent 节点都以 Tools Agent 运行，因此旧版的 agent-type 下拉菜单已不存在。

第 1 步：选择触发器

对于对话代理，添加一个 Chat Trigger 节点。在构建期间关闭 Make Chat Publicly Available，这样只有编辑器的聊天面板可以访问它。代理完成并确定身份验证方式后，再将其打开。

Chat Trigger 会向代理传递一个名为 chatInput 的字段。第 3 步会用到这个名称。名称写错是首次运行最常见的失败原因。

对于无人值守的代理，请改用 Schedule Trigger 或 Webhook 节点。这两者都不会生成 chatInput，因此需要自行编写提示词。

第 2 步：模型凭据

在画布上放置一个 AI Agent 节点。n8n 会立即在其下方显示一个空的 Chat Model 连接器。在此处连接一个 Anthropic Chat Model 子节点。

在 platform.claude.com 的 Anthropic Console 中创建凭据，依次打开 Settings 和 API Keys。密钥只显示一次。API 使用量按 token 计费，与 Claude.ai 订阅分开，因此账户需要先完成计费设置，才能首次运行。

按代理选择模型，而不是为整个公司统一选择模型。只需查询一项信息并报告结果的单工具代理使用 Haiku 即可正常运行。截至 July 2026，Haiku 的价格为每百万输入 token $1、每百万输出 token $5。代理拥有多个工具并需要跨工具规划时，再改用 Sonnet。需要避免的情况是：廉价模型连续 4 次调用错误工具，其成本反而高于昂贵模型正确调用 1 次。

在子节点的选项中设置 Maximum Number of Tokens。此设置限制模型每次生成的响应长度。如果保留较大的默认值，一次混乱的运行可能生成很长的答案，并因此产生额外费用。

n8n 文档中有一个容易忽略的注意事项：子节点中的表达式始终针对第一个输入项求值，而不会针对每个输入项分别求值。请将逐项表达式放在根节点的提示词字段中。

步骤 3：代理接收的提示词

打开 AI Agent 节点。Prompt 参数有两种设置方式。

• Take from previous node automatically 会读取名为 chatInput 的输入字段。在 Chat Trigger 后使用时，应选择此选项。
• Define below 会显示 Prompt (User Message) 字段，您可以在其中填写静态文本或表达式。在 Schedule Trigger 或 Webhook 节点后使用时，应选择此选项。

如果前面连接的是 Webhook 节点，POST 请求正文会存放在 $json.body 下，因此提示词字段如下所示。

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

第 4 步：为 Agent 提供一个工具

没有工具子节点的 AI Agent 节点不会运行。先添加一个工具，因为一个可正常工作的工具，比 4 个只完成一半配置的工具更有帮助。

将 HTTP Request 节点连接到 Agent 的 Tool 连接器。按照配置普通 HTTP Request 节点的方式完成配置，然后先从 shell 测试该端点。

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

如果该 curl 命令返回错误或 HTML 登录页面，Agent 也会失败。此时错误看起来像模型问题，实际原因却是 URL 或身份验证问题。应先在 shell 中修复，而不是在节点中修复。

工具的 Description 字段不是写给同事看的文档。模型只能通过该字段判断工具是否相关。请直接说明工具返回的内容：“以 JSON 格式返回一个受监控服务当前的正常或停机状态，以及停机持续时间。”

要让模型填充请求的一部分，请使用 $fromAI() 表达式。该表达式只能用于连接到 AI Agent 节点的工具，在 Code 工具中不可用。

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

参数依次为 key，以及可选的 description、type 和 defaultValue。键的长度必须为 1 到 64 个字符，只能使用字母、数字、下划线和连字符。类型可以是 string、number、boolean 或 json，默认值为 string。完整调用示例如下。

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

键只是提示，不代表对现有数据的引用。$fromAI('service') 不会从任何位置读取名为 service 的字段。它会告诉模型“生成一个值，并将其命名为 service”，然后模型会从对话、输入数据和其他工具结果中查找该值。在聊天工作流中，模型也可能直接询问用户。

Web 搜索通常是第二个工具。由于它只是另一个 HTTP 端点，因此可以将同一个节点指向您自己的 SearXNG 实例，而不是付费搜索 API，但必须将它返回的每个页面都视为不受信任的文本，因为这些内容现在已经进入提示词。

步骤 5：记忆，以及代理为何会遗忘

如果没有记忆子节点，每条消息都会从空白上下文开始。连接一个 Simple Memory 子节点，用于保存最近的对话。

它有两个参数。Session Key 用于确定当前对话，因此使用不同密钥的两个用户会获得彼此独立的历史记录。Context Window Length 表示会将多少次之前的交互重新放入提示词。

Context Window Length 不仅影响质量，也会影响成本，因为每次后续调用都会将记住的每轮对话作为输入 token 重新发送。对于一个消息频繁的代理，将窗口设为 20 意味着相同的早期消息会被计费 20 次。

n8n 以队列模式运行时，Simple Memory 不适用于活动中的生产工作流，因为历史记录保存在工作流自身的数据中，而不是共享存储中。在队列模式实例中，应改用 Postgres Chat Memory 子节点，并将其指向主进程和 worker 都能访问的数据库。

第 6 步：系统消息

打开 agent 的 Options，添加一条 System Message。作业描述应写在这里，这是整个工作流中影响最大的文本。

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

“Always call the status tool before answering” 在这里确实会发挥作用。如果没有这条指令，认为自己已经知道答案的模型可能会跳过工具调用，直接根据记忆回复；基础设施一旦发生变化，这种回复就会立即变得自信但错误。

为什么代理会循环，以及如何停止循环

Options 中还有 Max Iterations，默认值为 10。一次迭代包括一次模型调用，以及将一次工具结果反馈到上下文中。因此，一次代理运行不只对应一次 API 调用，最多可能执行 10 次调用，并且每次调用都会将不断增长的完整对话作为输入。

请降低该值。大多数只使用一个工具的代理会在 2 次迭代内完成，将限制设为 3 或 4 次，就能把失控循环变成执行列表中可见的明确失败。

调试期间，请启用 Return Intermediate Steps。最终输出会包含代理在执行过程中发起的工具调用。这样可以区分“模型从未调用工具”和“工具没有返回有用结果”。正式上线前请将其关闭，因为这些步骤对最终用户而言只是干扰。

从 shell 观察运行过程。

docker compose logs -f n8n

防止无人值守的 Agent 静默消耗资源

Chat Trigger 后的 agent 有人工监督；当答案看起来不正确时，人工可以停止它。Schedule Trigger 后的 agent 没有人监控。这里需要关注的是模型费用，而不是许可证费用，因为 agent、tool 和 memory 节点都可在免费的 self-hosted 版本中运行，而确实需要付费密钥的功能主要与团队协作和治理有关。完整说明请参阅在始终运行的 VPS 上控制 AI agent 成本。以下 4 个设置最为关键。

• 在模型子节点上设置 Maximum Number of Tokens 上限，避免单次响应运行过长。
• 将 Max Iterations 设置为仍能完成任务的最小值。
• 控制工具响应的大小。返回 4,000 行 JSON 的工具会将全部内容放入下一次模型调用，并继续放入本次运行中的后续每次调用。
• 先确认 Agent 是否确实需要定时运行。每 5 分钟运行一次的任务每天会触发 288 次。单次运行的成本是多少，就将该成本乘以 288。

迭代期间请停用工作流。处于活动状态的工作流会按照 n8n 已保存的版本持续运行，该版本不一定是您当前屏幕上显示的版本。

FAQ

为什么我的 AI Agent 节点拒绝执行？

AI Agent 节点需要一个 chat model 子节点和至少一个工具子节点。只有模型而没有工具的节点会在发起任何 API 调用前失败。添加一个工具，即使是简单工具，然后重新运行。

Agent 可以回答，但从不调用我的工具。问题在哪里？

几乎总是工具的 Description 字段有问题。模型通过读取这些描述来选择工具，因此像 “HTTP Request” 这样的描述无法说明工具何时适用。将描述改写为说明工具会返回什么数据，以及在什么情况下有用；然后在 System Message 中添加一行指示 Agent 在回答前调用该工具。

为什么每次运行相同问题的成本不同？

因为模型会选择执行的步骤数。每次迭代都会重新发送截至当前的完整对话，包括之前的工具输出。因此，执行 4 次迭代的运行成本可能远高于单次调用成本的 4 倍。Max Iterations 设置迭代次数上限，Return Intermediate Steps 显示某次运行实际使用了多少步骤。

我的记忆在编辑器中有效，但在生产环境中无效。发生了什么变化？

检查实例是否以队列模式运行。Simple Memory 将历史记录存储在工作流自身的执行数据中。将数据交给独立 worker 进程后，这些数据不会保留，因此运行中的生产工作流会丢失历史记录。改用 Postgres Chat Memory 子节点。它会将历史记录保存在所有 worker 共享的数据库中。