> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/chatbot-reply-mode-api.md).

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

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

`GET`／`PATCH /api/v1/chatbots/{id}/` 的 `replyMode`、`outputMode`、`rawOutputFormat` 三個欄位決定 Agent 怎麼回答。欄位型別以 API 文件 [AI 助理](https://docs.maiagent.ai/api/api-reference/ai-zhu-li) 為準，本頁補充值的意義與組合限制。

## 回答模式對照 <a href="#reply-modes" id="reply-modes"></a>

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

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

舊的 `workflow` 值已退場，既有 Agent 的處理方式見[內建工作流回覆模式退場](/tech/api-integration/endpoint-behaviors/workflow-reply-mode-retirement.md)。各模式的設定方式見使用者手冊 [建立 Agent：選擇適合的回答模式](https://docs.maiagent.ai/build/agent/setup#select-answer-mode-to-build-prompt)。

## 結構化輸出 <a href="#structured-output" id="structured-output"></a>

| 欄位                | 值                        | 說明                                                                                               |
| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `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，不會生效。

### 回應的形狀 <a href="#structured-response" id="structured-response"></a>

結構化輸出不改變回應的外層：`completions` 與訊息物件的 `content` 仍是字串，內容是符合 schema 的 JSON 文字，請自行解析（`JSON.parse`、`json.loads`）。因為回覆要整段產生完才能驗證，`isStreaming: true` 時 SSE 只會有一個 `done: true` 的事件，`content` 是完整的 JSON，見[不會進入串流的情況](/tech/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md#non-streaming-cases)。Web Chat 會把這段 JSON 當文字顯示，結構化輸出的 Agent 通常只透過 API 使用。

```json
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 時（罕見，多發生在模型能力不足），回覆仍以文字送出，平台不會回錯誤碼；解析失敗時請讓程式回退到人工處理，或換支援度更好的模型。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/chatbot-reply-mode-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.