langchain 0.2+ 中工具注册需显式传入工具列表，须用@tool装饰器或手动构造tool对象并确保name一致，再通过agent.tools验证；参数提取需核对schema与arguments；minimax端点与鉴权头须严格匹配；敏感词会导致静默清空content；工具调用须设timeout并配置熔断。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
确认工具注册是否生效
LangChain 0.2+ 版本中，Agent 不再自动扫描全局函数，必须显式传入工具列表，否则调用时会直接报 【Tool 'xxx' not found in the toolkit】。
方法一：用 @tool 装饰器定义工具，并确保创建 Agent 时将该函数作为元素传入工具列表，不能只写函数名字符串。
方法二：手动构造 Tool 对象，重点检查 name 字段——必须与模型生成的 tool_calls 中的 function.name 完全一致，包括大小写、连字符、下划线，任何差异都会导致匹配失败。
方法三：在 Agent 初始化后，打印 agent.tool_names 或遍历 agent.tools，确认目标工具名真实存在于输出列表中；若为空或缺失，说明注册路径中断，常见于 import 错误或装饰器未生效。
验证工具参数是否被正确提取
模型常因 description 模糊或上下文过长而传错参数，比如把 location 写成 city、把 int 类型转成字符串、漏掉必填字段。
第一步：在工具函数入口加 print(f"Received args: {locals()}")，确认实际收到的参数名和值。
第二步：比对工具定义中的 parameters JSON Schema 与模型生成的 arguments 字符串，注意枚举值是否拼写一致（如 "beijing" ≠ "Beijing"），日期格式是否为 ISO8601，数字是否被包裹在引号里。
第三步：若发现类型错位（如期望 int 却收到 str），需在工具封装层做自动转换，但【禁止在工具内部做容错性强制类型转换后再调用下游业务接口】，应前置拦截并返回结构化错误。
检查 MiniMax 端点与鉴权头是否匹配
国内版与国际版端点完全隔离，混用会导致 401 或 2049 错误，且不进入工具调用流程。
MiniMax Token Plan 工具——支持图片生成、图像理解、语音合成和视频生成。直接调用 MiniMax 官方 API，纯 JavaScript 实现，无需外部 MCP 服务器。
确认当前 API Key 来自 minimaxi.com 控制台 → 必须使用 https://api.minimaxi.com/v1 作为 base_url。
确认当前 API Key 来自 minimax.chat 控制台 → 必须使用 https://api.minimax.chat/v1 作为 base_url。
Authorization 头必须为 Bearer 后紧跟一个英文半角空格，再接完整密钥字符串；任何全角空格、换行、前缀（如 "Token "）、截断都会触发 token is unusable (1004)。
排查敏感词导致的静默失败
MiniMax 服务端会在预处理阶段对所有文本字段（messages.content、system、function.arguments）执行实时敏感词扫描，命中即清空 content 并返回空响应体，HTTP 状态码仍为 200。
启用 X-Debug-Filter: true 请求头，重新发起调用；若响应中出现 filter_reason: "keyword_match" 及 matched_tokens 字段，即可锁定具体被拦截的字符位置。
逐个检查 messages 数组中每个 content 的用词，特别注意政治人物全名、暴力动词组合、未授权医疗断言类短语的简繁体、拼音缩写、形近字变体。
验证工具调用链超时与熔断配置
工具调用未设 timeout 时，下游服务卡死会导致整个 Agent 响应挂起，用户侧表现为长时间无响应或直接超时断连。
在 execute_tool_with_trace 函数中，必须通过 asyncio.wait_for 设置明确 deadline，并在 OpenTelemetry span 中记录 timeout 属性。
熔断器需配置三态模型（closed → open → half-open），连续3次超时或异常后自动打开，避免打挂下游；恢复期需限制并发数与请求频率。
