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 描述成正確性保證。