MiniMax Agent工具调用失败需在关键节点拦截修复：工具注册须显式注入且name严格匹配；参数须用Pydantic校验并提供正反例；HTTP失败按错误码分层处理；启用JSON Mode并清洗arguments；确保tool_call id全局唯一。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
MiniMax Agent工作流中工具调用失败会导致任务中断、结果幻觉或死循环，必须在执行链路的每个关键节点做针对性拦截和修复。
确认工具是否已正确注册到Agent
工具名匹配失败是最高频的“找不到工具”错误，LangChain 0.2+不再自动扫描函数，必须显式注入。
方法一：用@tool装饰器定义并传入工具列表
在工具函数上方加@tool，创建Agent时把该函数直接放进tools参数里，不要传Tool对象或字符串名。
方法二：手动构造Tool对象时严格校验name字段
确保name="search_db"与LLM生成的function.name完全一致——大小写、下划线、连字符都不能差，【name值必须与模型输出的tool_call.function.name一字不差】。
方法三：检查工具注册时机
如果工具在Agent初始化之后才注册，或被包裹在条件分支里未执行，注册表始终为空。把工具定义和注册代码提到main入口最顶部，避免延迟加载。
验证工具调用参数合法性
参数幻觉占生产环境工具失败的58%，模型常传入虚构字段、类型错乱或枚举值越界。
第一步：启用Pydantic Schema强校验
定义工具时绑定input_schema，执行前用schema.parse_obj(arguments)做解析，字段缺失、类型不符、枚举非法全部拦截。
第二步：给模型喂正反例
在tool description末尾追加两行：
✅ 正确示例：{"query": "保单号ABC123", "doc_type": "health"}
❌ 错误示例：{"id": "ABC123", "type": "insurance"}（字段名错、缺少必填项）
第三步：拒绝裸JSON传参
禁止将原始字符串直接塞进func调用，必须先json.loads再校验。否则{"query": "北京"}会被当str传给需要dict的函数，立刻报TypeError。
处理HTTP类调用失败
网络超时、认证失效、服务端错误都会导致工具执行中断，需按错误码分层应对。
方法1：区分401/403与429/5xx
401和403说明鉴权失败，立刻停机检查端点URL与Authorization头——国内版密钥只能配https://api.minimaxi.com/v1，国际版密钥必须用https://api.minimax.chat/v1，混用必报401。
方法2：对429/500/503实施指数退避
第一次失败后sleep(1)，第二次sleep(2)，第三次sleep(4)，超过3次直接熔断。不要无脑重试，避免触发下游限流雪崩。
方法3：捕获空结果并反馈给LLM
工具返回{}、null或{"status":"no_data"}时，不能当作成功，要组装成system消息：“你调用search_knowledge_base返回空结果，请换关键词重试或改用get_document_by_id”，再送回模型重规划。
修复模型生成的tool_call格式错误
OpenAI-style function calling要求LLM输出严格JSON结构，MiniMax兼容此格式但不自动修正语法错误。
启用JSON Mode强制输出
初始化MiniMax客户端时设置response_format={"type": "json_object"}，配合schema约束，让模型无法输出非法JSON。
预处理器清洗arguments字段
拿到tool_call.function.arguments后，先用arguments.strip().replace('\n', '').replace('\r', '')去空白符，再json.loads——很多模型会在JSON里塞换行和缩进，直接解析必报JSONDecodeError。
校验id字段唯一性
每个tool_call必须带id且全局不重复，若模型连续两次生成相同id，执行器会覆盖前次结果。发现重复id立即丢弃该调用，返回error提示重试。
