n8n AI Agent 自建教程：VPS部署与成本控制

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

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

链的工作方式正好相反。在 Basic LLM Chain 中，您决定执行步骤，模型只负责生成文本。在 agent 中，模型决定执行步骤。因此，同一个问题今天可能只需调用模型 1 次，明天可能需要调用 9 次。这一差异决定了本指南中的每项设置。

本文假设 n8n 已在您控制的计算机上通过 HTTPS 运行。如果尚未运行，请先阅读 使用真实证书在 Docker 上自行托管 n8n，因为您即将保存的 API key 需要该指南要求备份的 encryption-key。对于非 agent 模式，例如 webhook 摘要器和计划任务分类器，请参阅 Claude 和 n8n 工作流模式。

请先检查您的版本，再依赖本文中的字段名称，因为 n8n 经常更改 AI 节点。

docker compose exec n8n n8n --version

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

步骤 1：选择触发器

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

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

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

步骤 2：模型凭据

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

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

按代理选择模型，而不是按公司统一选择。对于只需查询一项内容并报告结果的单工具代理，Haiku 已经足够。截至 2026 年 7 月，Haiku 的价格为每百万输入 token $1、每百万输出 token $5。当代理拥有多个工具并且需要在这些工具之间进行规划时，改用 Sonnet。要避免的情况是：低价模型连续 4 次调用错误的工具，其成本反而高于高价模型正确调用工具 1 次。

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

n8n 文档中有一个容易被忽略的注意事项：子节点中的表达式始终根据第 1 个输入项解析，不会按每个输入项分别解析。请将按输入项变化的表达式放在根节点的提示字段中。

第 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步：为代理添加一个工具

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

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

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

如果该 curl 命令返回错误或 HTML 登录页面，代理也会失败。此时错误看起来像是模型问题，实际却是 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”，然后模型会从对话、输入数据和其他工具结果中查找该值。在聊天工作流中，模型也可能直接询问用户。

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

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

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

Context Window Length 既影响成本，也影响质量，因为每次后续调用都会将记住的每轮对话作为输入令牌重新发送。对于消息频繁的代理，窗口设为 20 意味着您会为最初的消息重复支付 20 次费用。

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

步骤 6：系统消息

打开代理的 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.

“始终先调用 status 工具再回答”在这里起着实际作用。如果没有这条指令，认为自己已经知道答案的模型就会跳过工具调用并凭记忆回答。基础设施一旦发生变化，这种回答就会立即变成自信但错误的答案。

为什么代理会循环，以及什么会阻止它

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 没有人监控。完整说明请参阅 始终运行的 VPS 上的 AI agent 成本控制。这里的主要控制项有 4 个。

• 在模型子节点上限制 Maximum Number of Tokens，这样单次响应就不会运行过久。
• 将 Max Iterations 设置为仍能完成任务的最小值。
• 保持工具响应简短。返回 4,000 行 JSON 的工具会将全部内容放入下一次模型调用，以及同一次运行中之后的每次调用。
• 确认 agent 是否确实需要计划任务。每 5 分钟运行一次的任务每天会触发 288 次。单次运行的成本是多少，就将该成本乘以 288。

迭代期间停用工作流。处于活动状态的工作流及其 Schedule Trigger 会继续使用 n8n 已保存的版本运行，而该版本不一定是屏幕上显示的版本。

FAQ

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

AI Agent 节点需要一个聊天模型子节点和至少一个工具子节点。配置了模型但没有工具的节点会在发起任何 API 调用前失败。添加一个工具，即使是简单工具，然后再次运行。

Agent 会回复，但从不调用我的工具。哪里出了问题？

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

为什么相同的问题每次运行的费用不同？

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

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

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