Function Calling 踩坑复盘：工具定义的 10 个常见错误

Function Calling 踩坑复盘工具定义的 10 个常见错误一、明明传了参数LLM 却说参数缺失——Function Calling 的第一道坎Function Calling 看起来简单定义 Tool SchemaLLM 输出 JSON代码解析并执行。但实际落地时错误率比预期高得多。在一个客服 Agent 项目中3 个月内遇到了 47 种不同的工具调用错误其中 10 种占据了 90% 的错误量。这些错误不是 LLM 本身的 Bug而是 Tool 定义和执行防护的工程欠债。以下是 10 个最高频的错误和修复方案。二、10 个常见错误分布三、Top 5 高频错误详解错误 1Tool 描述模糊导致选错工具问题定义了query_order和query_refund两个工具描述分别是查询订单和查询退款。用户问我上周的退款处理好了吗模型调用了query_order而不是query_refund。根因描述中缺少关键的区分性信息。修复后query_order: 根据订单ID查询订单详情商品、金额、状态。 不支持查询退款信息。参数order_id (必需) query_refund: 根据订单ID查询退款记录退款金额、退款状态、 退款时间。仅用于查询退款信息。参数order_id (必需)关键原则每个 Tool 的描述要写明做什么和不做什么。模型需要负面示例来避免误调用。错误 2枚举值未在描述中列出问题update_order_status的参数status只定义了类型string没有列出可选值。模型传了取消但系统只认cancelled。修复在参数描述中显式列出所有枚举值status: 订单新状态。必须是以下之一: pending(待支付), paid(已支付), shipped(已发货), cancelled(已取消), refunded(已退款)。不支持中文状态值。错误 5JSON 格式错误这是最高频的执行期错误约 15% 的调用。模型有时会输出不合法的 JSON末尾多了逗号、字符串用了单引号。修复方式不是优化 Prompt而是在代码层对 JSON 做容错解析// 容错解析 JSON自动修复常见格式错误 func robustJSONParse(raw string, target interface{}) error { // 1. 尝试直接解析 if err : json.Unmarshal([]byte(raw), target); err nil { return nil } // 2. 尝试修复常见错误 fixed : raw // 去掉尾部多余的逗号 fixed regexp.MustCompile(,(\s*[}\]])).ReplaceAllString(fixed, $1) // 单引号替换为双引号仅限 JSON key/value 部分 // ... 更多修复规则 return json.Unmarshal([]byte(fixed), target) }错误 8超时未处理Tool 调用外部 API如 CRM 查询客户信息时API 响应可能 10 秒都回不来。如果 Agent 的主链路被 block 住等待这个 Tool整个对话会超时。修复func safeToolCall(ctx context.Context, tool func(...) (*Result, error), timeout time.Duration) (*Result, error) { ctx, cancel : context.WithTimeout(ctx, timeout) defer cancel() resultCh : make(chan *toolResult, 1) errCh : make(chan error, 1) go func() { result, err : tool(...) if err ! nil { errCh - err return } resultCh - toolResult{data: result} }() select { case result : -resultCh: return result.data, nil case err : -errCh: return nil, fmt.Errorf(工具执行失败: %w, err) case -ctx.Done(): return nil, fmt.Errorf(工具执行超时(%v): 返回降级结果, timeout) } }错误 10错误结果被模型采信某个 Tool 返回了数据查询错误如数据库繁忙但 LLM 把这个错误当作了查询结果——告诉用户你的订单号是数据库繁忙。修复// 对所有 Tool 返回做结构化包装 type ToolResponse struct { Success bool json:success Data interface{} json:data,omitempty Error string json:error,omitempty } func wrapToolResponse(result interface{}, err error) ToolResponse { if err ! nil { return ToolResponse{ Success: false, Error: fmt.Sprintf(工具执行失败请稍后重试。(错误码:INTERNAL_ERROR)), // 不暴露原始错误信息给模型防止幻觉输出 } } return ToolResponse{Success: true, Data: result} }四、系统性预防方案Schema 规范文档制定统一的 Tool Schema 编写规范模板包含名称动词_名词、场景何时使用/何时不使用、参数类型必填枚举值格式示例、示例至少 3 个成功调用示例 2 个不应调用的示例。调用前校验Service 层对 LLM 输出的 Tool Call 做校验参数类型、枚举值、必填检查校验失败时返回格式化错误给 LLM让它重新生成而不是直接抛出异常。调用后守护Tool 执行结果在返回给 LLM 前通过规则检查输出是否合理如金额不能为负数、时间不能是未来、字符串不能包含明显的 SQL 错误信息。统计面板用 Grafana 面板追踪每个 Tool 的调用成功率、平均耗时、参数错误类型分布。排名前 3 的错误类型必须在下个迭代修复。五、总结Function Calling 的坑主要集中在定义和防护两个阶段。定义阶段要遵循精确描述 明确边界 枚举值 示例的原则防护阶段要有调用前校验 调用中超时 调用后审核的三段保护。10 个常见错误中的大部分描述模糊、JSON 格式、枚举值缺失等是可以在工程层面系统性避免的——不需要模型升级只需要更规范的 Tool Schema 设计和更健壮的解析代码。核心认知不要把 LLM 的输出当作可信的把它当作可能是对的必须验证的。