Reasoning
为复杂任务配置推理投入，并正确读取结果、摘要和 Usage。
Reasoning 适合需要多步骤分析、复杂约束、数学推导、代码规划或工具协作的任务。推理模型通常允许应用控制推理投入，并可能返回推理摘要、Thinking Block 或相关 Usage；具体形式由模型和协议决定。
对于简单分类、格式转换或短问答，更高的推理投入不一定带来更好的业务结果，还可能增加响应时间和 Token 使用。
推理能力不是一个跨协议统一字段
Chat、Responses、Anthropic Messages 和 Gemini 对推理配置、公开结果和多轮状态的表达不同。不要把一个协议的字段直接复制到另一个协议中。
什么时候使用
| 任务 | 使用建议 |
|---|---|
| 多约束规划、复杂分析 | 选择支持推理的模型，并从较低或默认投入开始评估 |
| 数学、代码和逻辑问题 | 同时验证最终答案，不把推理投入等同于结果正确性 |
| 工具调用工作流 | 保留协议要求的调用、结果和状态结构，设置最大循环次数 |
| 简短改写、提取和分类 | 优先测试普通模型或较低推理投入，避免不必要开销 |
先在模型广场确认当前账户可用模型、协议和能力标签。示例中的 MODEL_ID 必须替换为当前账户中支持对应推理配置的模型。
使用 Responses 配置推理投入
Responses 将推理配置放在 reasoning 对象中：
curl 'https://api.agtcloud.cn/v1/responses' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
--data '{
"model": "MODEL_ID",
"input": "比较两种数据库迁移方案，并给出选择依据。",
"reasoning": {
"effort": "medium",
"summary": "auto"
}
}'effort 用于控制推理投入，summary 请求协议允许公开的推理摘要。可用值和是否生效取决于模型；完整定义见 Responses Reference。
不同协议如何表达推理
Chat 可通过 reasoning_effort 请求不同推理投入。推理 Token 在响应提供时通常记录在 Usage 的完成详情中；最终回答仍从 Assistant Message 读取。
{
"model": "MODEL_ID",
"messages": [
{"role": "user", "content": "分析这个部署方案的主要风险。"}
],
"reasoning_effort": "medium"
}示例值仅用于说明字段位置，不代表每个模型都接受相同档位或预算。分别查看 Chat Completions、Anthropic Messages 和 Gemini Generate Content Reference。
读取最终回答和公开推理信息
应用通常需要分别处理以下内容：
- 最终回答：真正展示给用户或交给下游业务的内容。
- 推理摘要或 Thinking Block：仅在协议和模型明确返回时读取，不假设它等于模型完整内部思维过程。
- Usage：记录输入、最终输出和推理 Token；字段位置随协议变化。
- 停止或不完整状态：判断回答是否因输出预算、内容策略、取消或错误而未完成。
如果业务只需要最终结论，不必持久化公开推理内容。保存这类内容前还应评估隐私、日志范围和数据保留策略。
Streaming 与工具调用
- 流式响应可能分别返回推理增量和最终文本增量，客户端应使用独立缓冲区。
- 工具调用前后都可能出现协议状态或 Thinking Block，不要只保留最终文本。
- 工具执行仍遵循 Tool Calling 的参数校验、权限和幂等要求。
- 续写时只回传目标协议要求的历史结构，不自行改写签名、调用 ID 或不透明状态。
完整流式处理方式见 Streaming。
设计输出预算
推理 Token 和可见回答可能共同占用输出预算。如果预算过小，模型可能完成分析却没有足够空间给出完整最终答案。
生产应用应同时观察：
- 最终回答是否完整；
- 停止原因或不完整原因；
- 推理与可见输出的 Usage；
- 不同投入档位下的质量、延迟和成本；
- 工具循环是否在允许的次数和总时限内结束。
上线前检查
- 当前账户支持目标模型，并已确认对应的推理接口与请求字段。
- 应用只发送目标协议接受的推理字段。
- 最终回答、公开推理信息和 Usage 分开处理。
- 流式、多轮和工具调用保留必要的协议状态。
- 输出预算不足、拒绝、超时和不完整响应都有明确分支。
- 不把推理强度、摘要或公开 Thinking 描述成正确性保证。