[!info] related notes

• 前置概念: Function Calling, 面向 Agent 的工具设计
• 并列概念: Orchestration
• 关系笔记: AI 的能力以及对应的协议

Function Calling 参数校验与重试机制

一句话定义

Function Calling 参数校验与重试机制，是在 Agent 调用工具时，通过 Schema 定义、运行时校验、错误反馈重试和高风险操作兜底，确保工具调用参数正确且安全的一套工程方案。

核心机制 / 工作原理

两层校验

1. 模型侧：Function Schema / JSON Schema

工具定义时就声明参数的 JSON Schema，约束类型、必填项、枚举值、格式。

{
  "name": "refund_order",
  "description": "对指定订单执行退款操作",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "description": "订单 ID" },
      "amount": { "type": "number", "minimum": 0 },
      "reason": { "type": "string", "enum": ["user_request", "quality_issue", "other"] }
    },
    "required": ["orderId", "amount", "reason"]
  }
}

2. 运行时侧：Zod / Ajv 校验

模型返回的参数不能直接信任，必须在执行前做运行时校验。

import { z } from 'zod';

const RefundParams = z.object({
  orderId: z.string().min(1),
  amount: z.number().positive(),
  reason: z.enum(['user_request', 'quality_issue', 'other']),
});

type RefundInput = z.infer<typeof RefundParams>; // 类型从 schema 推导

校验失败时进入 repair 流程，而非直接报错。

Repair-and-Retry 流程

1. 模型返回参数
2. Zod/Ajv 校验
3. 校验通过 → 执行工具
4. 校验失败 → 把错误信息 + 原始输出喂回模型，要求只修复格式
5. 重试（最多 3 次）
6. 连续失败 → 抛错，进入人工处理或降级

关键点：每次重试前要把具体校验错误反馈给模型，而不是简单重复请求。

高风险操作的额外兜底

退款、删除、支付等操作，光做参数校验不够，还需要：

• 幂等设计：相同参数重复调用不产生副作用
• 业务校验：订单是否存在、是否属于当前用户、是否已退款、金额是否超限
• 二次确认：高风险操作要求人工审批或 dry-run 预览
• 审计日志：记录每次调用的输入、输出和执行结果

最小例子 / 最小场景

用户说”帮我退款订单 A001，50 元”。模型返回 { orderId: "A001", amount: 50 }，但漏了 reason 字段。Zod 校验报错 reason: Required。系统把错误信息喂回模型，模型补充 reason: "user_request"，重试成功，执行退款。

边界与常见误解

• JSON Schema 只约束格式，不约束业务语义；业务校验必须在代码里做
• as type 断言不是校验，是绕过类型系统；运行时校验才是真正的保障
• 重试不是无限的；超过 3 次应该降级或报人工，避免死循环
• 幂等不是”忽略重复请求”，而是”重复执行结果一致”

Related notes

• Function Calling
• 面向 Agent 的工具设计
• Orchestration