症状
Agent 执行 Function Calling 或工具调用时，后端返回参数校验错误（如 invalid_tool_arguments 或 JSON parse error）。表现为：
- Agent 流程在工具调用环节中断，返回 JSON 解析失败的错误信息。
- 日志中可见模型生成的 JSON 包含语法错误——如尾随逗号、未闭合的引号或非法转义字符。
- 同一工具在手动构造参数时可以正常调用，排除工具本身的故障。
常见原因
- 模型生成质量不稳定：模型在复杂参数结构下容易生成不合法的 JSON，尤其在参数包含嵌套对象或数组时。
- 工具描述不够精确：Function schema 中的参数描述模糊、缺少类型约束或示例，导致模型理解偏差。
- 参数值包含特殊字符：用户输入中的引号、换行符或 Unicode 字符未经转义，被模型直接嵌入 JSON。
- 并发调用冲突：模型尝试同时调用多个工具时，生成的 JSON 结构出现混乱。
排查步骤
- 从日志中提取模型实际生成的 JSON 字符串，使用 JSON 校验工具（如
jq .或在线 JSON Validator）定位具体的语法错误位置。 - 审查工具的 Function schema 定义，确认每个参数都有明确的
type、description和enum（如适用），为复杂参数提供example。 - 在工具调用层添加 JSON 修复中间件，处理常见的格式问题（如去除尾随逗号、补全缺失的闭合括号）。
- 针对高频出错的工具，简化参数结构——将嵌套对象拍平为独立的顶层字段，降低模型生成复杂 JSON 的难度。
- 如果问题持续出现，启用结构化输出模式（Structured Output / JSON Mode），强制模型按照预定义的 JSON Schema 生成输出。
预防
- 所有工具定义遵循最小化参数原则，仅暴露模型必须填写的字段。
- 在每次工具调用前加入 JSON Schema 校验层，不合法的参数自动触发重试而非直接报错。
- 对用户输入进行预处理，转义可能破坏 JSON 结构的特殊字符。
- 建立工具调用的成功率监控，定期优化低成功率工具的参数设计。