Skip to main content

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 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.
/stream is disabled while structured output is on. If your integration relies on streaming responses, structured output is not compatible.
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.
Strict mode is always on: every field is required and nesting depth is capped at 3. Schema size is limited to 5 KB.

​
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: 
{
  "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: 
{
  "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.