AI 工具调用落地实战：JSON Schema、参数校验和人工兜底

把大模型接进业务系统后，最容易踩的坑不是“模型不会回答”，而是“模型想帮用户做事，却把参数理解错了”。例如用户说“帮我把昨天失败的订单重新通知一下”，AI 助手需要识别意图、选择工具、整理参数，再调用后端接口。如果中间缺少约束和确认，就可能误发通知、误改状态或查错数据。

适合人群：正在做 AI 助手、客服辅助、运营后台智能体、内部自动化工具的开发者。本文不绑定某个模型平台，重点讲工程链路：结构化参数、服务端校验、确认步骤和兜底策略。

目录

• 工具调用为什么要先定边界
• 用 JSON Schema 固定输入结构
• 服务端二次校验和确认步骤
• 失败兜底和审计日志
• 常见坑和上线检查

一、工具调用为什么要先定边界

AI 工具调用的本质，是让模型把自然语言请求转换成结构化的业务动作。模型可以负责理解用户意图，但真正改数据、发消息、扣库存、创建任务的动作，必须由业务服务按规则完成。

建议先把工具分成三类：

• 只读工具：查询订单、查库存、查日志，风险较低。
• 低风险写入：创建草稿、生成预览、添加备注，允许直接完成。
• 高风险写入：退款、删除、批量通知、状态变更，需要用户确认或人工审核。

二、用 JSON Schema 固定输入结构

工具参数要像接口契约一样明确。以“重新发送订单通知”为例，至少要约束订单号、通知渠道、原因说明、是否需要预览。这样模型只能在固定字段里填值，服务端也能按同一份结构做校验。

{
  "name": "resend_order_notice",
  "description": "为指定订单重新发送通知",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[0-9]{6,20}$"
      },
      "channel": {
        "type": "string",
        "enum": ["sms", "email", "site_message"]
      },
      "reason": {
        "type": "string",
        "minLength": 5,
        "maxLength": 120
      },
      "preview_only": {
        "type": "boolean",
        "default": true
      }
    },
    "required": ["order_id", "channel", "reason", "preview_only"],
    "additionalProperties": false
  }
}

这里最重要的是 `additionalProperties: false` 和枚举值。前者能减少多余字段混进来，后者能避免模型把“短信”“短消息”“手机号提醒”随意填成不同值。

三、服务端二次校验和确认步骤

即使模型输出已经符合 Schema，服务端也要再做一遍业务校验。Schema 只能保证字段格式，不能保证订单存在、用户有权限、渠道可用、当前状态允许重发。

async function handleToolCall(user, args) {
  const order = await orderRepo.findById(args.order_id);
  if (!order) {
    return {ok: false, message: "订单不存在"};
  }

  if (!canOperate(user, order)) {
    return {ok: false, message: "当前用户无权操作该订单"};
  }

  if (args.preview_only) {
    return {
      ok: true,
      need_confirm: true,
      preview: buildNoticePreview(order, args.channel, args.reason)
    };
  }

  if (!order.allow_notice_resend) {
    return {ok: false, message: "该订单当前状态不允许重发通知"};
  }

  await noticeService.send(order.id, args.channel, args.reason);
  return {ok: true, message: "通知已重新发送"};
}

高风险动作建议默认先走 `preview_only: true`。用户看到预览内容、目标对象和影响范围后，再点击确认。这样模型只是准备动作，最终决定仍然由用户或审批流程完成。

四、失败兜底和审计日志

工具调用一定会遇到失败：参数缺失、业务状态不允许、接口超时、用户取消确认。好的系统不会把失败藏起来，而是把失败原因返回给模型和用户，同时写入日志，方便排查和复盘。

{
  "trace_id": "ai-tool-20260613-10001",
  "user_id": "u_123",
  "tool": "resend_order_notice",
  "args": {
    "order_id": "100001",
    "channel": "sms",
    "preview_only": true
  },
  "result": "need_confirm",
  "message": "等待用户确认后再发送"
}

审计日志至少记录四类信息：谁发起、调用了什么工具、参数是什么、结果如何。涉及隐私或密钥的字段要脱敏，不能把完整手机号、邮箱、令牌直接写进日志。

五、常见坑和上线检查

1. 不要让模型直接拼接业务接口地址

工具名和接口映射应该由服务端维护。模型只选择工具和参数，不能决定真实后端地址，也不能绕开权限系统。

2. 不要把确认步骤做成可选装饰

高风险动作必须由规则强制确认。即使模型很确定，也应该先返回预览，让用户看到对象、数量、影响范围。

3. 失败信息要能被用户理解

不要只返回“工具失败”。更好的提示是“订单已关闭，不能重发通知”或“当前账号没有该订单权限”。这样用户知道下一步该怎么做。

4. 上线前自测清单

• 缺少必填字段时，工具不会调用业务接口。
• 枚举字段填错时，服务端能返回清晰错误。
• 高风险动作默认进入预览和确认流程。
• 每次工具调用都有 trace_id 和脱敏日志。

总结

AI 工具调用要落地，不能只看模型能不能选对工具。真正稳定的链路应该是：Schema 约束参数，服务端再次校验，高风险动作先确认，失败结果可解释，日志可追踪。这样模型负责理解和组织，业务系统负责规则和边界，整体才可控。