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
json
1{
2 "type": "object",
3 "properties": {
4 "response": {
5 "type": "string",
6 "description": "Message to display to the user."
7 },
8 "sentiment": {
9 "type": "string",
10 "enum": ["positive", "neutral", "negative"],
11 "description": "Detected sentiment of the user's message."
12 },
13 "escalate_to_human": {
14 "type": "boolean",
15 "description": "True if human assistance is needed."
16 },
17 "next_answer_type": {
18 "type": "string",
19 "enum": ["text", "list", "buttons", "image"],
20 "description": "Format of the next response."
21 },
22 "suggested_answers": {
23 "type": "array",
24 "items": { "type": "string" },
25 "description": "Quick replies or button labels."
26 }
27 },
28 "required": ["response", "sentiment", "escalate_to_human"]
29}
Use structured output in Chatbots
When you use structured output, the AI agent returns a JSON object instead of plain text. In the response from the AI agent, the content field contains the JSON object as text, and the parsedOutput field contains the same JSON object, parsed. Use $.parsedOutput to save individual fields directly in attributes.
To use structured output in Chatbots, do the following:
- In the Connect to AI agent element, go to the Response tab. Add one output for each field that you want to save.
- In each output, complete the following:
- In Response field, select Custom response body expression.
- In Response expression, enter
$.parsedOutput.followed by the field name. Example:$.parsedOutput.escalate_to_human - In Target attribute / variable, select the attribute that stores the value.
- Use the saved values to do the following:
- Display the response text to the end user.
- Route based on
escalate_to_humanorisLeavingflags. - 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.
Was this page helpful?