Structured Outputs

Structured Outputs allow you to define JSON schemas that your AI agents must follow when responding. This ensures consistent, machine-readable responses that can be easily integrated with other systems, APIs, or automated workflows.

Overview

Structured Outputs enable you to:

Define Response Format - Create custom JSON schemas for agent responses
Ensure Consistency - Guarantee agents always return data in the same structure
Enable Integration - Make responses easily consumable by other systems
Improve Parsing - Eliminate the need for complex text parsing

How It Works

1. Create JSON Schema

Define the structure you want your agent to follow:

Fields - Specify required and optional fields
Data Types - Define types (string, number, boolean, array, object)
Nested Structures - Create complex nested JSON objects
Examples - Provide example values for clarity

2. Assign to Agent

Select the structured output schema for your agent:

General Tab - Choose from available structured outputs
Agent-Specific - Each agent can use a different schema
Dynamic Selection - Change schemas as needed

3. Agent Response

When enabled, the agent will:

Format as JSON - Return responses in the specified JSON structure
Follow Schema - Include all required fields
Maintain Structure - Preserve nested objects and arrays
Validate Format - Ensure responses match the schema

Creating Structured Outputs

Step 1: Access Output Tab

Navigate to Agents in the sidebar
Select an agent or create a new one
Click Edit to open the agent builder
Go to the Output tab

Step 2: Create New Schema

Click Create New button
Enter a descriptive title for your structured output
Use the JSON builder to define your schema

Step 3: Define Schema Structure

Use the visual JSON builder to create your schema:

Basic Structure

{
  "status": "string",
  "message": "string",
  "data": {
    "result": "string"
  }
}

With Arrays

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "value": "number"
    }
  ],
  "total": "number"
}

Complex Nested Structure

{
  "response": {
    "summary": "string",
    "details": {
      "category": "string",
      "subcategory": "string",
      "metadata": {
        "created_at": "string",
        "updated_at": "string"
      }
    },
    "items": [
      {
        "id": "string",
        "properties": {
          "name": "string",
          "value": "number"
        }
      }
    ]
  }
}

Step 4: Save Schema

Click Save to store your structured output
The schema is now available for use in agents

Assigning to Agents

Method 1: From General Tab

Open the agent you want to configure
Go to the General tab
Find the Response Format section
Select your structured output from the dropdown
Save the agent

Method 2: From Output Tab

Open the agent you want to configure
Go to the Output tab
Select a structured output from the list
The agent will use this schema for all responses

Use Cases

API Integration

Scenario: You need agent responses in a format that can be consumed by your API. Schema Example:

{
  "status": "success",
  "code": 200,
  "data": {
    "result": "string",
    "timestamp": "string"
  }
}

Agent Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "result": "Task completed successfully",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Data Extraction

Scenario: Extract structured data from unstructured text. Schema Example:

{
  "entities": [
    {
      "type": "string",
      "value": "string",
      "confidence": "number"
    }
  ],
  "summary": "string"
}

Agent Response:

{
  "entities": [
    {
      "type": "person",
      "value": "John Doe",
      "confidence": 0.95
    },
    {
      "type": "company",
      "value": "TechCorp",
      "confidence": 0.88
    }
  ],
  "summary": "Extracted 2 entities from the text"
}

Formatted Reports

Scenario: Generate consistent report structures. Schema Example:

{
  "report": {
    "title": "string",
    "date": "string",
    "sections": [
      {
        "heading": "string",
        "content": "string",
        "metrics": {
          "value": "number",
          "unit": "string"
        }
      }
    ],
    "summary": "string"
  }
}

Workflow Automation

Scenario: Structure responses for automated workflow processing. Schema Example:

{
  "action": "string",
  "parameters": {
    "key": "value"
  },
  "next_step": "string",
  "metadata": {
    "workflow_id": "string",
    "step_number": "number"
  }
}

Best Practices

Schema Design

Be Specific - Clearly define all fields and their types
Use Examples - Include example values in your schema
Keep It Simple - Avoid overly complex nested structures when possible
Document Fields - Use descriptive field names
Consider Optional Fields - Mark fields as optional when appropriate

Field Naming

Use Clear Names - user_name instead of un
Be Consistent - Follow a naming convention (snake_case, camelCase)
Avoid Abbreviations - Use full words when possible
Group Related Fields - Use nested objects for related data

Schema Structure

Flat When Possible - Prefer flat structures for simple data
Nest for Organization - Use nesting for complex, related data
Arrays for Lists - Use arrays for collections of similar items
Objects for Groups - Use objects to group related fields

Testing

Test with Real Queries - Verify the schema works with actual user questions
Check All Fields - Ensure all required fields are populated
Validate Types - Confirm data types match the schema
Handle Edge Cases - Test with unusual or missing data

Managing Structured Outputs

Viewing All Schemas

In the Output tab, you can:

List All Schemas - See all structured outputs in your project
Search - Find schemas by name
Sort - Sort by creation date or title
View Details - See schema structure and metadata

Editing Schemas

Click on a schema in the list
Modify the JSON structure using the visual builder
Click Save to update the schema
Changes apply to all agents using this schema

Deleting Schemas

Find the schema in the list
Click the Delete icon
Confirm deletion
Agents using this schema will revert to normal text responses

Deleting a structured output will affect all agents currently using it. Make sure to update those agents before deleting.

Response Format

Normal Response (Default)

When no structured output is selected, agents return free-form text:

The user requested information about project status.
The project is currently in progress with 75% completion.
All milestones are on track.

Structured Response

When a structured output is selected, agents return JSON:

{
  "status": "in_progress",
  "completion_percentage": 75,
  "milestones": [
    {
      "name": "Phase 1",
      "status": "completed"
    },
    {
      "name": "Phase 2",
      "status": "in_progress"
    }
  ],
  "on_track": true
}

Integration with System Prompt

When a structured output is assigned to an agent:

Schema Included - The JSON schema is added to the system prompt
Format Instructions - Agent receives explicit formatting instructions
Example Provided - The schema serves as an example format
Validation - Agent attempts to match the exact structure

Advanced Features

Dynamic Field Values

Schemas can include fields that adapt to the response:

{
  "response_type": "string",
  "content": {
    "text": "string",
    "metadata": {}
  }
}

Conditional Structures

Use different schemas for different response types:

{
  "type": "success|error|warning",
  "message": "string",
  "data": {} // Structure varies by type
}

Array Responses

Handle multiple items in responses:

{
  "count": "number",
  "items": [
    {
      "id": "string",
      "data": {}
    }
  ]
}

Troubleshooting

Agent Not Following Schema

Possible Causes:

Schema not assigned to agent
Schema structure too complex
Agent needs clearer instructions

Solutions:

Verify structured output is selected in General tab
Simplify the schema structure
Add more explicit field descriptions
Test with simpler queries first

Invalid JSON Responses

Possible Causes:

Schema has syntax errors
Agent struggling with complex structure
Missing required fields

Solutions:

Validate schema syntax in the JSON builder
Check for JSON validation errors
Simplify the schema if too complex
Review agent responses for parsing errors

Missing Fields

Possible Causes:

Fields not clearly defined
Agent doesn’t understand field requirements
Schema too vague

Solutions:

Add clear field descriptions
Provide example values in schema
Make fields optional if not always available
Test with specific queries

Examples

Example 1: Customer Support Response

Schema:

{
  "ticket_id": "string",
  "status": "open|resolved|pending",
  "response": "string",
  "next_actions": ["string"],
  "priority": "low|medium|high|urgent"
}

Agent Response:

{
  "ticket_id": "TKT-12345",
  "status": "resolved",
  "response": "Your issue has been resolved. The problem was related to account permissions.",
  "next_actions": ["Refresh your browser", "Log out and log back in"],
  "priority": "medium"
}

Example 2: Data Analysis Response

Schema:

{
  "analysis": {
    "summary": "string",
    "findings": [
      {
        "category": "string",
        "insight": "string",
        "confidence": "number"
      }
    ],
    "recommendations": ["string"]
  },
  "data_points": "number"
}

Agent Response:

{
  "analysis": {
    "summary": "Sales data shows 15% increase in Q4",
    "findings": [
      {
        "category": "revenue",
        "insight": "Revenue increased by 15% compared to Q3",
        "confidence": 0.95
      },
      {
        "category": "customers",
        "insight": "New customer acquisition up 20%",
        "confidence": 0.88
      }
    ],
    "recommendations": [
      "Continue current marketing strategy",
      "Focus on customer retention"
    ]
  },
  "data_points": 1250
}

Example 3: Task Management Response

Schema:

{
  "task": {
    "id": "string",
    "title": "string",
    "status": "todo|in_progress|completed",
    "assignee": "string",
    "due_date": "string",
    "description": "string"
  },
  "related_tasks": [
    {
      "id": "string",
      "title": "string"
    }
  ]
}

Permissions

Creating Structured Outputs

Project Admin - Can create, edit, and delete structured outputs
Project Member - Depends on project permissions (flows.edit)
Viewer - Can view but not modify structured outputs

Using in Agents

Agent Owner - Can assign structured outputs to their agents
Project Admin - Can assign to any agent in the project
Project Member - Can assign to agents they have access to

Agent Configuration - Configure agent personality and behavior
Tools - Use tools that return structured data
API Integration - Integrate structured responses with external APIs
Workflows - Use structured outputs in automated workflows

Agent Configuration

Learn how to configure your agents

Support

Need help with structured outputs? Contact support at [email protected].

Get Started!

SDK

Chat

Agents

Workflows

Interfaces

Knowledge Base

Settings

Platform Admin

My Account

Public Chatbot

General Information

​Structured Outputs

​Overview

​How It Works

​1. Create JSON Schema

​2. Assign to Agent

​3. Agent Response

​Creating Structured Outputs

​Step 1: Access Output Tab

​Step 2: Create New Schema

​Step 3: Define Schema Structure

​Basic Structure

​With Arrays

​Complex Nested Structure

​Step 4: Save Schema

​Assigning to Agents

​Method 1: From General Tab

​Method 2: From Output Tab

​Use Cases

​API Integration

​Data Extraction

​Formatted Reports

​Workflow Automation

​Best Practices

​Schema Design

​Field Naming

​Schema Structure

​Testing

​Managing Structured Outputs

​Viewing All Schemas

​Editing Schemas

​Deleting Schemas

​Response Format

​Normal Response (Default)

​Structured Response

​Integration with System Prompt

​Advanced Features

​Dynamic Field Values

​Conditional Structures

​Array Responses

​Troubleshooting

​Agent Not Following Schema

​Invalid JSON Responses

​Missing Fields

​Examples

​Example 1: Customer Support Response

​Example 2: Data Analysis Response

​Example 3: Task Management Response

​Permissions

​Creating Structured Outputs

​Using in Agents

​Related Features

Agent Configuration

​Support

Structured Outputs

Overview

How It Works

1. Create JSON Schema

2. Assign to Agent

3. Agent Response

Creating Structured Outputs

Step 1: Access Output Tab

Step 2: Create New Schema

Step 3: Define Schema Structure

Basic Structure

With Arrays

Complex Nested Structure

Step 4: Save Schema

Assigning to Agents

Method 1: From General Tab

Method 2: From Output Tab

Use Cases

API Integration

Data Extraction

Formatted Reports

Workflow Automation

Best Practices

Schema Design

Field Naming

Schema Structure

Testing

Managing Structured Outputs

Viewing All Schemas

Editing Schemas

Deleting Schemas

Response Format

Normal Response (Default)

Structured Response

Integration with System Prompt

Advanced Features

Dynamic Field Values

Conditional Structures

Array Responses

Troubleshooting

Agent Not Following Schema

Invalid JSON Responses

Missing Fields

Examples

Example 1: Customer Support Response

Example 2: Data Analysis Response

Example 3: Task Management Response

Permissions

Creating Structured Outputs

Using in Agents

Related Features

Support