Agent 回答模式與結構化輸出欄位

Agent 的回答模式（replyMode）與後台名稱的對照，以及結構化輸出欄位 outputMode、rawOutputFormat 的組合規則與回應形狀。

GET／PATCH /api/v1/chatbots/{id}/ 的 replyMode、outputMode、rawOutputFormat 三個欄位決定 Agent 怎麼回答。欄位型別以 API 文件 AI 助理 為準，本頁補充值的意義與組合限制。

回答模式對照

後台「回答模式設定」顯示的名稱與 API 的 replyMode 值對照如下；replyMode 與「串流或同步」無關，串流由 completions 請求的 isStreaming 決定。

後台名稱	replyMode	行為
Agent 模式（新 Agent 的預設）	agent	模型自行決定要檢索什麼、呼叫哪些工具，可多步驟執行；工具、Code Interpreter、資料庫、技能、MaiGPT 連接器與 Agent UI 都只在這個模式可用
RAG 問答	normal	每則訊息固定檢索一次知識庫再回答，見 RAG 知識庫檢索系統
模板（其他模式）	template	依知識庫與 FAQ 以分類方式回覆，不由模型自由生成
混合（其他模式）	hybrid	部分內容用模板格式、其餘自由回答

舊的 workflow 值已退場，既有 Agent 的處理方式見內建工作流回覆模式退場。各模式的設定方式見使用者手冊 建立 Agent：選擇適合的回答模式。

結構化輸出

欄位	值	說明
outputMode	text（預設）／json_schema	json_schema 代表每則回覆都是符合 rawOutputFormat 的 JSON
rawOutputFormat	JSON Schema 物件或 null	回覆要符合的結構；最外層用 "type": "object"，每個欄位寫 type 與 description。儲存時會驗證它是合法的 JSON Schema，不合法回 400

組合限制：

• 只在 replyMode 為 normal（RAG 問答）時生效；Agent 模式忽略這兩個欄位。

• 模型必須支援結構化輸出：GET /api/v1/large-language-models/ 每個模型的 outputMode 陣列列出它支援的值，只有包含 json_schema 的模型可以用。後台看不到「輸出格式」欄位時，就是目前模型或回答模式不支援。

• outputMode 為 json_schema 時 rawOutputFormat 不能是 null；改回 text 時可以保留原本的 schema，不會生效。

回應的形狀

結構化輸出不改變回應的外層：completions 與訊息物件的 content 仍是字串，內容是符合 schema 的 JSON 文字，請自行解析（JSON.parse、json.loads）。因為回覆要整段產生完才能驗證，isStreaming: true 時 SSE 只會有一個 done: true 的事件，content 是完整的 JSON，見不會進入串流的情況。Web Chat 會把這段 JSON 當文字顯示，結構化輸出的 Agent 通常只透過 API 使用。

PATCH /api/v1/chatbots/{id}/
{
  "replyMode": "normal",
  "outputMode": "json_schema",
  "rawOutputFormat": {
    "type": "object",
    "properties": {
      "intent": {"type": "string", "description": "問題分類：退貨、查詢、投訴、其他"},
      "orderId": {"type": "string", "description": "訊息中提到的訂單編號，沒有則為空字串"}
    },
    "required": ["intent", "orderId"]
  }
}

模型產生的內容不符合 schema 時（罕見，多發生在模型能力不足），回覆仍以文字送出，平台不會回錯誤碼；解析失敗時請讓程式回退到人工處理，或換支援度更好的模型。