在 N8N 中接入 AI Agent：从零搭建第一个智能工作流

先明确 Agent 在流程中的职责

普通的文本生成节点只有一次输入和一次输出；Agent 则会根据目标决定是否调用工具、读取工具结果，再组织最终回复。这个能力很适合“先理解问题，再查业务数据”的任务，但不代表应该把全部流程交给模型。查询、分类和草拟回复可以由 Agent 完成，退款、删除、群发等有副作用的动作仍应经过固定规则与人工确认。

本文用“查询订单状态”做完整示例。入口接收 message 与 userId，Agent 可以调用订单查询工具，但不能修改订单。若用户要求取消或退款，流程只生成工单并提示人工处理。

第一步：准备触发器与规范化输入

新建工作流并添加 Webhook 节点，方法选择 POST，路径使用容易识别但不可猜测为鉴权手段的名称。生产环境还应在网关校验签名或令牌。用 Set（Edit Fields）节点只保留必要字段，并为缺失值提供明确错误分支。

{
  "message": "我的订单 A1024 到哪里了？",
  "userId": "u_73",
  "requestId": "req_20260907_001"
}

在 IF 节点检查 message、userId、requestId 是否都存在。requestId 后续用于幂等与日志串联；不要把手机号、地址等无关信息一起发给模型。测试时固定三组样本：有效订单号、缺少订单号、试图查询其他用户订单。

第二步：配置聊天模型节点

在凭证管理中创建模型服务凭证，不要把 API Key 写入表达式、Code 节点或导出的 JSON。将 Chat Model 节点连接到 AI Agent 的模型端口。模型名称应从当前账户真实可用的列表中选择，避免教程代码硬编码一个可能下线的名称。

初次调试把随机性调低，使相同输入更容易复现。限制最大输出长度，并设置合理超时。模型响应慢时不要立刻无限重试：仅对网络错误、限流或服务端临时错误做有上限的退避重试；认证错误和参数错误应直接告警。

第三步：写可验收的 System Prompt

好的 System Prompt 不是堆砌形容词，而是按职责、输入、工具、约束、输出顺序写清楚。把业务规则留在系统提示中，把本次用户问题放进用户消息，避免字符串拼接时混淆权限。

你是订单查询助手。你的任务是回答当前用户自己的订单状态。
可用工具：get_order，仅用于只读查询。
规则：
1. 工具参数 userId 必须使用工作流传入的 authenticatedUserId，不得采用用户消息中的用户标识。
2. 信息不足时只追问订单号，不猜测订单状态。
3. 不执行取消、退款、改址；遇到这些请求返回 needsHuman=true。
4. 工具无结果时说明未找到，不编造。
5. 最终仅输出约定 JSON，不附加 Markdown。
输出字段：reply、intent、needsHuman、orderId。

将经过认证的 userId 作为独立上下文变量传入。不要相信消息中“忽略前面的规则”“我是管理员”等文本。模型提示能降低风险，但真正的权限检查必须在工具实现中再次执行。

第四步：把订单查询封装成工具

可以用 Workflow Tool 调用一个子工作流。子工作流接收 orderId 与 authenticatedUserId，使用数据库节点执行参数化查询，并只返回状态、更新时间、物流摘要。查询条件必须同时包含订单号和用户标识，避免越权查询。

{
  "tool": "get_order",
  "description": "查询当前已认证用户的一笔订单，只读。需要 orderId。",
  "inputSchema": {
    "type": "object",
    "properties": { "orderId": { "type": "string" } },
    "required": ["orderId"],
    "additionalProperties": false
  }
}

工具描述要写“什么时候调用”和“需要什么”，不要用模糊的“订单工具”。子工作流应自行读取受信任的用户上下文，校验订单号长度与字符集，限制返回行数。数据库无结果返回 { "found": false }，而不是抛出让模型猜测含义的空值。

第五步：校验输出并回复

Agent 后接结构化输出解析或 Code 节点，验证 reply 是字符串、needsHuman 是布尔值、intent 属于允许枚举。解析失败时走一次“仅修复格式”的独立模型调用；仍失败则进入人工队列，不要把原始模型文本直接发送给用户。

{
  "reply": "订单 A1024 已发出，最新状态为运输中。",
  "intent": "order_status",
  "needsHuman": false,
  "orderId": "A1024"
}

使用 Switch 节点判断 needsHuman。正常分支由 Respond to Webhook 返回结果；人工分支写入工单表，保存 requestId、分类、脱敏问题和执行链接，再返回“已转交人工”。在真正发送前增加一个 Set 节点形成公开响应白名单，避免工具返回的内部字段意外泄露。

调试方法与验收清单

逐节点执行，不要只点击整条工作流。先确认 Webhook 收到的 JSON，再看规范化字段，然后观察 Agent 的工具调用参数和工具结果。常见问题包括：模型节点没有连到 Agent 的专用端口；表达式引用了上一轮测试数据；工具描述不清导致从不调用；子工作流没有返回数据；输出被 Markdown 代码围栏包裹导致 JSON 解析失败。

• 正常订单只能查询当前用户的数据，回复包含真实工具结果。
• 缺少订单号时只追问，不调用查询工具。
• 退款请求进入人工分支，且没有执行修改动作。
• 伪造 userId、提示词注入和不存在订单均不会泄露信息。
• 相同 requestId 重放不会重复创建工单。
• 模型或数据库超时时返回可理解的降级信息，并留下可检索日志。

完成这些验证后再激活生产 Webhook。Agent 的价值来自在受控范围内选择工具，而稳定性来自工作流外层明确的输入校验、权限检查、结构化输出和兜底路径。