> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivi.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Output

Structured output forces your agent to reply with a typed JSON object that conforms to a defined schema, instead of returning free-form text. This is designed for programmatic use cases where a downstream system needs to parse or act on the agent's response directly.

***

## Enabling Structured Output

Structured output is configured per agent. To enable it, open your agent, expand the **Structured Output** section, and toggle it on.

<Warning>
  `/stream` is disabled while structured output is on. If your integration relies on streaming responses, structured output is not compatible.
</Warning>

Once enabled, define your schema using one of three input modes:

***

## Defining a Schema

### Visual

The Visual editor lets you build your schema field by field without writing JSON directly. For each field, set a name, type (Text, Number, Integer, True/False, Group, or List), and an optional description. Check **Required** to mark a field as mandatory.

Use **Add field** to add more fields, and **Reset** to clear the schema back to its default state.

<Note>
  Strict mode is always on: every field is required and nesting depth is capped at 3. Schema size is limited to 5 KB.
</Note>

### JSON Schema

The JSON Schema tab lets you write or paste a raw JSON Schema directly. Edits here sync back to the Visual tab automatically.

The schema must be strict-compatible: the root must be an object, all properties must be required, and every object must include `"additionalProperties": false`.

*Example:*

```json theme={null}
{
  "title": "Response",
  "type": "object",
  "properties": {
    "newField": {
      "type": "string"
    }
  },
  "required": ["newField"],
  "additionalProperties": false
}
```

Use the **Copy**, **Paste**, and **Format** buttons to manage your schema. The editor validates your schema in real time and displays the current size against the 5 KB limit.

### From JSON Document

The **From JSON Document** tab lets you generate a schema automatically from a JSON sample. Paste a JSON object representing the desired response shape and click **Generate schema**.

Keys become property names and values are used to infer types — strings become `text`, numbers become `number`, booleans become `true/false`, arrays become `list`, and nested objects become `group`. Descriptions and choice lists are not inferred and should be refined in the Visual tab afterward.

*Example input:*

```json theme={null}
{
  "productName": "Widget Pro",
  "priceUsd": 19.99,
  "inStock": true,
  "keyFeatures": ["durable", "lightweight"]
}
```

***

## When to use it

Structured output is intended for API-driven workflows — specifically the `/invoke` and `/batch` endpoints — where the response needs to be machine-readable rather than conversational.

**Good use cases:**

* Extracting structured data from a user's input (e.g., filling a form, classifying a request)
* Returning a consistent response format to a backend system or integration
* Powering workflows where the agent's output feeds directly into another process

**Not recommended for:**

* Agents deployed on conversational channels such as Web Chat, WhatsApp, or Microsoft Teams
* Any use case where a natural, human-readable response is expected

***

## Best Practices

* Use **From JSON Document** to quickly scaffold a schema from an existing sample, then refine field descriptions in the Visual tab.
* Keep schemas minimal — only include fields your downstream system actually needs. Simpler schemas are easier for the model to conform to reliably.
* Test your schema thoroughly using **Test Agent** before deploying to production.
* If you need both a conversational channel and a structured API integration, create two separate agents with different configurations rather than trying to serve both from one.