MiniMax Agent编程场景工具调用教程
必须选用MiniMax-H3或M2.5模型并配置系统提示词启用工具调用，添加工具（内置/自定义/本地脚本），请求中声明tools数组，解析返回的tool_calls执行工具，再将结果以tool_responses格式回传触发最终推理。
要在MiniMax Agent中让模型自动调用工具完成编程任务（比如查文档、运行代码、读取文件），必须绕过“人工写API请求+手动解析响应”的老路，直接启用H3或M2.5系列模型原生支持的结构化工具调用能力。这一步不做对，Agent永远只能输出伪代码，无法真正执行。
确认模型与平台支持
第一步，先登录Minimax开发者控制台，进入「Agent」模块，依次点击「创建Agent」。到了模型选择这一步，
【一定要选 MiniMax-H3 或 MiniMax-M2.5】
第二步：在Agent配置页的「系统提示词」区域，开头必须加入明确指令：“你具备调用外部工具的能力。当用户需求涉及代码执行、文件读取、网络查询等操作时，你必须生成符合JSON Schema的tool_calls字段，不得自行虚构结果。”
第三步：点击「保存并发布」，获取Agent ID。注意：只有发布后的Agent才启用tool_calls解析引擎，草稿状态下的测试请求不会触发工具调用。
定义可调用工具（Tools）
方法一：使用平台内置工具模板（适合快速验证）
在Agent编辑页点击「添加工具」→ 选择「代码执行器（Python）」→ 勾选「启用沙箱环境」→ 设置超时时间为8秒（超过将强制终止，避免死循环占用资源）。该工具会自动注入requests、numpy、pandas等常用库，无需额外声明依赖。
方法二：自定义HTTP工具（适合对接内部服务）
先点「添加工具」，再选择「自定义工具」，把名称填写为get_user_profile。接着，在 Schema 里粘贴标准的 OpenAI 格式 JSON Schema。这里有个关键细节一定不能漏：parameters里必须带上"type": "object"，同时"required"字段不能是空数组。
【如果required为空，或者压根没填，Agent会直接跳过这个工具，不会发起调用】
方法三：上传本地Python脚本（适合私有逻辑）
准备一个db_query.py文件，首行必须是#!/usr/bin/env python3，函数需以def run(params: dict) -> dict:签名定义，返回值必须为字典。上传后平台自动校验语法，通过即显示「已就绪」状态。未通过校验的脚本不会出现在工具列表中，也不会报错提示——这是最容易卡住的无声失败点。
构造含工具调用的用户请求
第一步：准备测试请求体。在Postman或curl中构造POST请求，URL为https://api.minimaxi.com/v1/text/chatcompletion。
第二步：Header中设置Authorization: Bearer sk-xxx（你的API Key）和Content-Type: application/json。
第三步：Body中填入以下结构：
{
"agent_id": "agt_xxx",
"messages": [
{"role": "user", "content": "帮我查一下用户ID为U7890的订单状态，并用折线图展示他过去3个月的消费金额变化"}
],
"tools": [
{"name": "get_order_status", "description": "根据用户ID查询最新订单状态", "parameters": {"type": "object", "properties": {"user_id": {"type": "string"}}, "required": ["user_id"]}},
{"name": "plot_monthly_spending", "description": "生成指定用户近3个月消费折线图", "parameters": {"type": "object", "properties": {"user_id": {"type": "string"}}, "required": ["user_id"]}}
]
}
注意：tools数组必须与Agent配置页中已启用的工具完全一致，字段名、参数结构、required项缺一不可。多传一个未启用的工具，整个请求会被拒绝返回400错误。
解析模型返回的tool_calls
发送请求后，检查返回JSON中的choices[0].message.tool_calls字段。它不是字符串而是数组，每个元素含name（工具名）、arguments（JSON字符串，需json.loads()解析）、id（唯一标识符）。
关键动作：提取arguments字符串，用Python执行json.loads(tool_call['arguments'])得到真实参数字典。若直接用eval()或未处理转义字符，会因单引号/换行符导致解析失败——这是本地调试时最常踩的坑。
拿到参数后，调用对应工具函数（如get_order_status.run({"user_id": "U7890"})），捕获返回值。将结果按如下格式组装回传：
{
"tool_responses": [
{"tool_call_id": "call_abc123", "content": '{"status": "shipped", "tracking_no": "SF123456789"}'}
]
}
注意：content字段必须是字符串，即使内容是JSON也要双引号包裹并转义。传入原始字典会导致后续推理中断。
触发工具调用后继续推理
将上一步组装的tool_responses连同原始messages一起，再次POST到同一接口，但这次Body中要增加"tool_responses"字段，且messages末尾追加一条role为assistant、content为空的占位消息——这是MiniMax协议要求的上下文锚点，缺少则模型无法识别工具结果已注入。
第二次响应中，choices[0].message.content将包含自然语言结论（如“用户U7890的订单已发货，物流单号SF123456789。过去三个月消费趋势图已生成…”），此时Agent才算真正完成了“调用→执行→归纳”闭环。
