Structured output

Structured output enforces a defined schema for AI agent responses, such as JSON, instead of free-form text.

Why use structured output

• Predictable responses that can be processed by other systems.
• Easier automation and system integration.
• Reduced ambiguity in free-form responses.

Use cases

• Hybrid chatbots: Detect when to transition from AI agent to chatbot control. Use parameters such as response (message to end user) and isLeaving: true/false.
• Multimodal responses: Send more than plain text, such as lists, buttons, images, or locations. Structured output supports these message formats by separating the text message (response) from the format (next_answer_type) and the extra content (suggested_answers).
• Escalation management: Use the escalate_to_human: true parameter to route to live agents.

Example schema

{
  "type": "object",
  "properties": {
    "response": {
      "type": "string",
      "description": "Message to display to the user."
    },
    "sentiment": {
      "type": "string",
      "enum": ["positive", "neutral", "negative"],
      "description": "Detected sentiment of the user's message."
    },
    "escalate_to_human": {
      "type": "boolean",
      "description": "True if human assistance is needed."
    },
    "next_answer_type": {
      "type": "string",
      "enum": ["text", "list", "buttons", "image"],
      "description": "Format of the next response."
    },
    "suggested_answers": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Quick replies or button labels."
    }
  },
  "required": ["response", "sentiment", "escalate_to_human"]
}

Use structured output in Chatbots

When you use structured output, the AI agent returns a JSON object instead of plain text.

To use structured output in Chatbots, do the following:

1. In the Agent connector element, extract the full response by using the JSON path $.content.
2. Use a Code element to parse the JSON and extract individual fields into separate attributes.
3. Use the extracted values to do the following:
   • Display the response text to the end user.
   • Route based on escalate_to_human or isLeaving flags.
   • Determine message format using next_answer_type.
   • Populate buttons or lists with suggested_answers.

For agent configuration steps, see Configure an AI agent. For guidance on defining output format in prompts, see Write prompts for AI agents.