MiniMax_Agent工具调用教程

MiniMax Agent需手动启用工具调用能力：登录控制台→进入Agent编辑页→「工具配置」标签页开启开关并保存；API请求中须显式声明tools数组和tool_choice策略，响应分步返回tool_calls，需按id回传tool_result完成闭环。

确认Agent是否已启用工具调用能力

MiniMax Agent默认不自动开启工具调用，必须手动在控制台配置权限，否则所有工具请求都会被静默忽略。

登录 Minimax开发者控制台 → 左侧导航栏点击【Agent】→ 找到目标Agent → 点击右侧【编辑】按钮 → 切换到「工具配置」标签页。

检查「工具调用开关」是否为开启状态；若为关闭，请点击切换并保存。⚠️

此时页面会列出已接入的工具列表，如M2.5-Search、Python执行器、Shell命令行等。只有打钩启用的工具，后续API请求中才能被Agent识别并调用。

在API请求中声明并触发工具调用

工具调用不是靠提示词“请调用搜索”就能触发的，必须在JSON请求体中显式声明tools数组与tool_choice策略。

方法一：强制指定某个工具（更适合确定性流程）
做法其实很直接：在 POST 请求 Body 的 JSON 里加上这个字段："tool_choice": {"type": "function", "function": {"name": "m25_search"}}。同时别漏掉另一点，tools 数组中也要提前放好对应 name 的工具定义。

方法二：由模型自主决策（推荐新手起步）
设置"tool_choice": "auto"，并提供完整tools数组。MiniMax M2.5及以上模型会根据用户问题语义自动判断是否需调用、调用哪个工具——例如问“今天北京天气如何”，模型可能跳过工具直接回答；问“神舟十八号最新在轨任务进展”，则自动触发m25_search。

注意：tools数组必须是标准OpenAI格式，每个tool对象含name、description、parameters（JSON Schema）。漏掉parameters或格式错误将导致400响应，且错误信息不提示具体哪一行出错。

解析带工具调用的多段式响应

当Agent决定调用工具时，API不会直接返回最终答案，而是分步返回：先返回tool_calls字段（含id和参数），你需执行工具后，再把结果用tool_result形式发回同一会话。

第一步：收到首次响应后，检查choices[0].message.tool_calls是否存在。若存在，说明模型已生成调用指令。

第二步：提取每个tool_call.id与function.arguments，按工具文档执行本地或远程调用。例如m25_search需将arguments JSON转为查询字符串，调用其独立API端点。

第三步，就是基于现有的messages历史继续构造新请求，并在末尾补上一条role=“tool”消息：{"role":"tool","content":"{result_json}","tool_call_id":"abc123"}。⚠️

第四步：再次POST至/v1/text/chatcompletion，不改agent_id，不重置messages，仅追加tool消息。模型将基于工具返回内容生成最终回复。