从0到1搭建可落地的AI Agent与工作流(19):第19期|Agent总把参数传错?给n8n工具接口加一道「合同层」,3个测

从0到1搭建可落地的AI Agent与工作流｜第19期

Agent又传了个缺字段的请求，下游系统直接报500。你盯着日志想骂人，但问题不在模型，在工具接口没上锁。这期我们就给n8n工具调用加一道「合同层」，让错误在进入业务前被拦住。

本期你将完成

🗺 BUILD MAP · 本期构建路径

上一期我们搞定了灰度发布，新版本能小流量试错。但灰度只保证发布过程不炸，如果Agent调工具时经常传错参数、缺字段、乱填枚举，那再平滑的发布也救不了业务错误。

真实案例：LangChain博客总结了Lyft、Vodafone等客服Agent生产经验，工具集成和参数不一致是排名前三的故障源。很多团队把工具接口当摆设，模型自由发挥，结果就是下游API被脏数据打挂。

所以这期我们不聊大模型，只解决一个问题：如何用n8n给工具调用加一层可验证的接口合同。你不需要重构整个Agent，加一个校验节点就行。

工具调用的可靠性从契约开始。每个工具必须有明确的JSON Schema，声明参数类型、枚举、必填项和约束。别让模型猜你要什么。

例如一个查询订单的工具，输入参数必须包含order_id，类型string，长度8到16位；status可选open、closed、pending，默认open。输出结构必须有data和error两个字段。

在n8n里，你可以把这个Schema配置在工具节点或Function节点里。推荐用Function节点做前置校验，因为可以自定义错误返回。

在n8n工作流中，最简单可靠的位置是在工具调用节点之前插入一个Function节点，作为参数校验器。Agent节点输出工具调用意图后，先进入这个校验器，通过后再调用真实工具。

校验器职责：解析Agent输出的工具名和参数；根据预定义的Schema逐项检查；如果通过，原样放行；如果不通过，构造结构化错误对象返回给Agent，让它修正后重试。

同时，在工具调用节点之后再加一个输出校验，确保下游返回的结构符合预期，避免把异常数据传给后续节点。

下面给出一段在n8n Function节点中可运行的JavaScript伪代码逻辑，不是完整代码但可以直接照抄思路。假设你的Agent节点输出格式是{ tool_name: 'query_order', parameters: { order_id: 'xxx', status: 'open' } }。

在Function节点中写：定义schema对象，检查每个required字段是否存在；检查类型是否符合；检查枚举是否在允许列表；任何失败，返回{ error_code: 'TOOL_PARAM_INVALID', message: '缺少参数order_id或类型错误', details: { field: 'order_id', expected: 'string' } }，并设置节点输出为错误，触发重试。

重试机制：在Agent节点配置里启用重试，让模型看到错误后调整参数。n8n的Agent节点支持在收到工具错误时再次调用模型。

测试1（正常）：输入参数{ order_id: '12345678', status: 'open' }，校验通过，工具正常调用，返回订单数据。预期：流程继续。

测试2（边界）：status传入'pending'，枚举包含，但order_id长度为7，不满足8-16位约束。校验返回TOOL_PARAM_INVALID，Agent收到错误后修正为8位，重试成功。预期：最终成功。

测试3（失败）：order_id缺失，required校验失败，返回TOOL_PARAM_MISSING，Agent尝试补充但无上下文，重试两次后放弃，流程进入人工失败分支，发送通知。预期：自动降级。

当工具调用失败，先在n8n执行日志里看Function节点的输出。如果错误码是TOOL_PARAM_MISSING，说明必填缺失；TOOL_PARAM_INVALID说明类型或枚举问题。

如果Agent没有重试或重试也失败，检查Agent节点的重试配置，以及错误返回的message是否足够清晰，让模型能判断下一步。

还有一个隐蔽问题：函数节点里字符串比较大小写敏感。建议将枚举全部转小写进行比较，然后在输出时恢复。

权限：校验节点不应该拥有业务系统凭据，只做参数检查，工具节点单独持有凭据，实现最小权限。

成本：多一次校验几乎不增加Token消耗，因为只处理结构化数据。但重试会增加模型调用，建议设置最大重试2次。

安全：参数校验可以防止一部分注入，但不能替代输入消毒。如果参数包含自由文本，需要额外做长度限制和危险字符过滤。

验收标准：所有工具接口都有Schema定义；100%的工具调用经过校验；错误返回结构化率达到100%；工具调用成功率提升20%以上（基于你的历史基线）。