> 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/en/api-integration/endpoint-behaviors/chatbot-reply-mode-api.md).

# Agent Reply Modes and Structured Output Fields

Maps Agent reply modes (replyMode) to their names in the admin console, and explains the combination rules and response shape for the structured output fields outputMode and rawOutputFormat.

The `replyMode`, `outputMode`, and `rawOutputFormat` fields in `GET`／`PATCH /api/v1/chatbots/{id}/` determine how an Agent responds. For field types, refer to the API documentation for [AI Assistants](https://docs.maiagent.ai/api/api-reference/ai-zhu-li). This page explains what the values mean and which combinations are allowed.

## Reply Mode Mapping <a href="#reply-modes" id="reply-modes"></a>

The following table maps the names shown under “Reply Mode Settings” in the admin console to API `replyMode` values. `replyMode` does not control streaming versus synchronous responses; streaming is determined by `isStreaming` in the `completions` request.

| Admin console name                      | `replyMode` | Behavior                                                                                                                                                                                                |
| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent mode (the default for new Agents) | `agent`     | The model decides what to retrieve and which tools to call, and can execute multiple steps. Tools, Code Interpreter, databases, skills, MaiGPT connectors, and Agent UI are available only in this mode |
| RAG Q\&A                                | `normal`    | Retrieves from the knowledge base once per message before responding. See [RAG Knowledge Base Retrieval System](/tech/en/quickstart/rag.md)                                                             |
| Template (other modes)                  | `template`  | Responds by category based on the knowledge base and FAQ, rather than letting the model generate responses freely                                                                                       |
| Hybrid (other modes)                    | `hybrid`    | Uses a template format for some content and generates the rest freely                                                                                                                                   |

The legacy `workflow` value has been retired. For how existing Agents are handled, see [Retirement of the Built-in Workflow Reply Mode](/tech/en/api-integration/endpoint-behaviors/workflow-reply-mode-retirement.md). For instructions on configuring each mode, see the user manual: [Create an Agent: Choose a Suitable Reply Mode](https://docs.maiagent.ai/build/agent/setup#select-answer-mode-to-build-prompt).

## Structured Output <a href="#structured-output" id="structured-output"></a>

| Field             | Values                         | Description                                                                                                                                                                                                    |
| ----------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outputMode`      | `text` (default)／`json_schema` | `json_schema` means every reply is JSON that conforms to `rawOutputFormat`                                                                                                                                     |
| `rawOutputFormat` | JSON Schema object or `null`   | The structure that replies must conform to. Use `"type": "object"` at the top level and specify `type` and `description` for each field. The schema is validated on save; an invalid JSON Schema returns `400` |

Combination constraints:

* These fields take effect only when `replyMode` is `normal` (RAG Q\&A). Agent mode ignores both fields.
* The model must support structured output. Each model returned by `GET /api/v1/large-language-models/` has an `outputMode` array listing its supported values; only models whose array includes `json_schema` can use it. If the “Output Format” field is not visible in the admin console, the current model or reply mode does not support it.
* When `outputMode` is `json_schema`, `rawOutputFormat` cannot be `null`. When switching back to `text`, you can keep the existing schema, but it will not take effect.

### Response Shape <a href="#structured-response" id="structured-response"></a>

Structured output does not change the outer response structure: `content` in `completions` and message objects remains a string containing JSON text that conforms to the schema. Parse it yourself (`JSON.parse`, `json.loads`). Because the entire reply must be generated before it can be validated, when `isStreaming: true`, SSE contains only one event with `done: true`, and `content` contains the complete JSON. See [Cases Where Streaming Does Not Occur](/tech/en/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md#non-streaming-cases). Web Chat displays this JSON as text, so Agents using structured output are typically accessed only through the API.

```json
PATCH /api/v1/chatbots/{id}/
{
  "replyMode": "normal",
  "outputMode": "json_schema",
  "rawOutputFormat": {
    "type": "object",
    "properties": {
      "intent": {"type": "string", "description": "Question category: return, inquiry, complaint, other"},
      "orderId": {"type": "string", "description": "Order number mentioned in the message; an empty string if none is provided"}
    },
    "required": ["intent", "orderId"]
  }
}
```

If the model generates content that does not conform to the schema (rare, and usually due to insufficient model capabilities), the reply is still sent as text, and the platform does not return an error code. If parsing fails, have your application fall back to human handling, or switch to a model with better support.


---

# 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/en/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.