智谱清言智能体工具调用失败需分三步排查：先确认智能体已开通工具权限并勾选对应工具；再用curl验证tool_name拼写、参数结构及必填字段；最后检查工具服务状态、文件上传有效性及超时设置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
智谱清言智能体调用工具失败时，页面卡在“执行中”、返回空响应或直接报错“tool call failed”“function not found”，导致RAG检索、网页抓取、代码执行等关键能力无法触发，整个工作流中断。
确认智能体是否已启用工具权限
登录智谱开放平台（https://open.bigmodel.cn/），进入「智能体管理」→ 找到目标智能体 → 点击「编辑」→ 切换到「工具配置」标签页。
检查右侧工具列表是否勾选了你实际调用的工具（如web_search、code_interpreter、file_parser）；若全部灰显不可选，说明该智能体未开通工具调用权限——【必须点击页面顶部“开通工具权限”按钮并完成实名认证后，工具列表才可编辑】。
开通后等待约30秒，刷新页面确认工具状态变为“已启用”。此时再测试，若仍失败，继续下一步。
验证工具调用请求结构是否合规
方法一：用curl直测工具端点（绕过SDK封装）
执行以下命令，将YOUR_API_KEY和AGENT_ID替换为真实值：
curl -X POST "https://open.bigmodel.cn/api/paas/v4/agents/AGENT_ID/tool-call" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"tool_name":"web_search","parameters":{"query":"今日AI新闻"}}'
若返回404，说明AGENT_ID错误或该智能体不支持tool-call接口；若返回400且error.message含“invalid tool name”，说明tool_name拼写与平台注册名不一致——注意大小写和下划线，例如file_parser不能写成fileParser或file-parser。
方法二：检查请求体中是否遗漏required字段
所有工具调用必须携带tool_name和parameters两个顶层字段；parameters内部字段依工具而定，但不能为空对象{}。例如code_interpreter的parameters至少需包含code字符串字段，填空值或缺失code会导致1223错误码。
排查工具执行环境问题
第一步：确认工具依赖服务是否在线
访问https://status.bigmodel.cn，查看「Tool Runtime」服务状态是否为绿色。若显示“Degraded”或“Outage”，说明底层沙箱或搜索服务异常，此时任何工具调用都会失败，无需修改代码。
第二步：检查上传文件是否被工具引用但未就绪
若工具为file_parser或pdf_analyzer，需确保文件已通过/upload接口成功上传，并在tool-call的parameters中传入的是file_id（如file_abc123），而非本地路径或URL。【传入http链接会被静默忽略，不报错但工具不执行】。
第三步：验证工具超时设置
默认工具执行时限为30秒。若调用web_search时遇到高延迟站点，或code_interpreter运行复杂计算，可能触发1302错误（tool execution timeout）。此时需在请求体中显式添加timeout字段，例如"timeout": 60。
