MiniMax Agent API 需要通过结构化 JSON 来定义多步骤任务，其中 steps 数组通常包含 id、prompt 和 depends_on 依赖关系。需要特别注意的是，ID 仅允许使用字母、数字与下划线，并且依赖项必须建立在已完成的前置步骤之上。通过 /v2/agent/task 创建任务后，需要持续轮询任务状态；当任务执行完成时，最终结果会在 final_result 字段中按照各步骤顺序自动拼接返回。

在使用 MiniMax Agent API 时，如果提交的是一个包含多个逻辑阶段的复杂任务，例如“先从三份PDF中提取合同条款→比对条款差异→生成风险提示报告”，就不能仅仅让模型以串行方式自行判断每一步如何执行。更推荐的做法是，明确声明任务结构、步骤之间的依赖关系，以及每个阶段的执行边界。否则，API 默认可能会将其当作单轮问答来处理，从而导致中间状态无法保留、过程无法中断校验、前序结果也难以复用。

构造带步骤定义的 JSON 请求体

第一步：在 POST 请求的 content 字段中，不要直接填写自然语言指令，而应使用数组封装多个 step 对象，每个对象都必须包含 id 和 prompt 两个关键字段。

第二步：为每个 step 设置唯一字符串 ID，例如 "extract_terms"、"compare_clauses"、"generate_risk_report"；ID 会作为后续状态查询与结果引用的唯一标识，【ID 中不能包含空格或特殊字符，只允许字母、数字、下划线】。

第三步：在 prompt 字段中，建议使用清晰明确的动词开头描述当前步骤目标，例如 "提取所有 PDF 文件中'违约责任'章节的完整文本，保留原文标点与换行"，避免使用“看看有没有违约条款”这类模糊表达。

第四步：如果某一步需要依赖前一步输出结果，就要显式写入 depends_on 字段，值为上一步的 id 字符串数组。例如第三步可写为 depends_on: ["compare_clauses"]；【depends_on 必须是已定义过的 step ID 数组，否则任务请求会被拒绝】。

调用 /v2/agent/task 创建任务

向 https://api.minimaxi.com/v2/agent/task 发起 POST 请求，Header 中需携带 Authorization: Bearer {your_api_key} 与 Content-Type: application/json。

请求体中必须包含 model 字段，目前仅支持 "minimax-m2.7" 或 "minimax-m2.7-highspeed"；如果填写其他模型名称，将会返回 400 错误。

body 示例结构如下（注意：steps 是顶层字段，并非嵌套在 content 内）：

{ "model": "minimax-m2.7", "steps": [ { "id": "extract_terms", "prompt": "从上传的 contract_a.pdf、contract_b.pdf、contract_c.pdf 中，定位并提取全部'违约责任'小节内容，逐份返回原始文本。" }, { "id": "compare_clauses", "prompt": "逐条比对上一步三份提取结果，标出完全一致、部分重叠、完全不同的条款，并说明差异位置。", "depends_on": ["extract_terms"] }, { "id": "generate_risk_report", "prompt": "基于比对结果，用中文撰写一份风险提示报告，分'共性风险'与'个性风险'两部分，每项附对应条款原文片段。", "depends_on": ["compare_clauses"] } ] }

轮询任务执行状态

方法一：使用 GET 请求访问 https://api.minimaxi.com/v2/agent/task/{task_id}，其中 task_id 来自上一步响应中的 id 字段。

方法二：建议每 3～5 秒发起一次状态查询，直到 status 字段变为 "completed" 或 "failed"；【不要将轮询频率设置为低于1秒，否则可能触发限流并返回 429 状态码】。

响应体中的 steps 字段会动态更新，每个 step 对象会新增 status（pending/running/done/failed）以及 result（仅在 done 时存在，输出为字符串格式）。

如果某个 step 的 status 为 failed，其 error 字段会说明失败原因，常见情况包括超时（step_timeout）、上下文截断（context_truncated）或工具调用失败（tool_call_failed）。

获取最终聚合结果

当整个 task 的 status 变为 completed 后，直接读取响应体中的 final_result 字段即可。它是一个字符串，会按照 steps 数组顺序自动拼接所有 done 步骤的 result，并以 "n---n" 作为分隔。

这一步实际操作非常直接，只需将 final_result 复制到你的业务系统中即可，无需再次遍历 steps 逐项提取。

如果你需要单独获取某一步的结果，例如只查看比对环节输出，就从 steps 数组中找到 id 为 "compare_clauses" 的对象，并读取其 result 字段。