Structured Outputs

Working with typed AI responses

Structured outputs ensure AI responses are predictable and usable in downstream workflow nodes. This guide covers how to configure and work with different output types.

Why Structured Outputs?

Structured outputs provide:

Type safety - Outputs match expected data types
Reliability - Consistent format across executions
Integration - Easy to use in subsequent nodes
Validation - Errors caught early if parsing fails

Available Return Types

Scalar Types

Single values:

Type	Description	Example
`string`	Text response	"Meeting went well, deal progressing"
`integer`	Whole number	8
`boolean`	True or false	true
`float`	Decimal number	0.85

Array Types

Lists of values:

Type	Description	Example
`string_list`	List of strings	["Follow up", "Send proposal"]
`integer_list`	List of integers	[1, 3, 7]
`boolean_list`	List of booleans	[true, false, true]
`float_list`	List of decimals	[0.9, 0.7, 0.95]

Configuring Return Types

In Node Configuration

yaml

return_type: string_list

The AI automatically formats its response to match the specified type.

Type Selection Guidelines

Use Case	Return Type
Summaries, messages	`string`
Scores, counts	`integer`
Yes/no decisions	`boolean`
Confidence scores	`float`
Action items, tags	`string_list`
Rankings, priorities	`integer_list`

Accessing Outputs

Scalar Output

After an AI node with return_type: string:

liquid

{{ json.value }}

In a Slack message:

liquid

*Meeting Summary*
{{ json.value }}

Array Output

After an AI node with return_type: string_list:

liquid

{% for item in json.value %}
- {{ item }}
{% endfor %}

Output in Conditions

After an AI node with return_type: boolean:

cel

// In If node condition
json.value == true

After an AI node with return_type: integer:

cel

// Check if score is above threshold
json.value >= 7

Best Practices for Each Type

String Output

Prompt guidance:

liquid

Provide a summary in 2-3 sentences.
Do not use bullet points or headers.
Start directly with the content.

Example output:

text

The team reviewed Q4 goals and agreed to prioritize the enterprise launch. Key concerns about timeline were addressed with a phased approach.

Integer Output

Prompt guidance:

liquid

Rate this meeting on a scale of 1-10.
1 = Very poor, 10 = Excellent
Return only the number, nothing else.

Example output:

text

Boolean Output

Prompt guidance:

liquid

Determine if follow-up is needed within 24 hours.

Return true if ANY of these apply:
- Urgent issue was raised
- Customer requested immediate response
- Deadline is within 48 hours

Return false otherwise.

Example output:

text

true

Float Output

Prompt guidance:

liquid

Estimate the probability this deal will close.
Return a decimal between 0.0 and 1.0.
0.0 = Definitely won't close
1.0 = Definitely will close

Example output:

text

0.75

String List Output

Prompt guidance:

liquid

Extract all action items from this meeting.
Return as a list of strings.
Each item should be a complete, actionable sentence.

Example output:

json

[
  "Send proposal by Friday",
  "Schedule follow-up call for next week",
  "Share case study with prospect"
]

Integer List Output

Prompt guidance:

liquid

Rank the following items by priority (1 = highest).
Return a list of integers representing the ranking.

Example output:

json

[2, 1, 3, 4]

Handling Parse Errors

When AI output doesn't match the expected type:

What Happens

Output parsing fails
Error is sent to error output
Original AI response is available in error context

Common Parse Errors

Issue	Cause	Solution
"Expected integer, got string"	AI included text with number	Add "Return only the number" to prompt
"Invalid JSON array"	Malformed list output	Use simpler list format in prompt
"Expected boolean, got string"	AI returned "yes" instead of true	Specify "Return true or false only"

Error Recovery Pattern

text

[AI Prompt]
    ├── Success ──▶ [Use structured output]
    └── Error ────▶ [AI Prompt: Retry with simpler format]
                           │
                           └──▶ [Use output or default]

Working with Lists

Iterating Over List Output

After AI returns string_list:

liquid

*Action Items:*
{% for item in json.value %}
{{ forloop.index }}. {{ item }}
{% endfor %}

Processing Each Item

Connect to Select Many to process items individually:

text

[AI: Extract items] ──▶ [Select Many: json.value] ──▶ [Process each]

Checking List Length

liquid

{% if json.value.size > 0 %}
Found {{ json.value.size }} items:
{% for item in json.value %}
- {{ item }}
{% endfor %}
{% else %}
No items found.
{% endif %}

Using List in Conditions

cel

// Check if any items were extracted
json.value.size() > 0

// Check if specific item count
json.value.size() >= 3

Complex Data Patterns

Multiple Outputs

If you need multiple types of output, use multiple AI nodes:

text

[Load Data] ──┬──▶ [AI: Summary (string)] ──┐
              │                             ├──▶ [Zip] ──▶ [Use both]
              └──▶ [AI: Score (integer)] ───┘

Structured String Output

For complex structured output, use string with formatting:

Prompt:

liquid

Analyze this meeting and provide:
SENTIMENT: [positive/neutral/negative]
URGENCY: [high/medium/low]
SUMMARY: [1-2 sentences]

Then parse in subsequent node:

liquid

{% assign lines = json.value | split: "\n" %}
{% for line in lines %}
{{ line }}
{% endfor %}

Key-Value Extraction

For extracting named values:

Prompt:

liquid

Extract the following if mentioned:
- Customer name: [name or "Not mentioned"]
- Budget: [amount or "Not mentioned"]
- Timeline: [timeframe or "Not mentioned"]

Format exactly as shown above.

Output Validation Tips

1. Be Explicit About Format

❌ Vague:

text

Return a list of items.

✅ Explicit:

text

Return a JSON array of strings.
Example: ["item1", "item2", "item3"]

2. Constrain Output Range

For integers:

text

Return a number between 1 and 10.

For strings:

text

Response must be under 500 characters.

3. Handle Empty Cases

text

If no action items are found, return an empty list: []
Do not return null or "none".

4. Avoid Mixed Types

❌ Will fail:

text

Return the count or "none" if zero.

✅ Consistent:

text

Return the count as an integer. Return 0 if none found.

Type Coercion

Some downstream nodes can handle type conversion:

From	To	Behavior
Integer	String	Automatic in Liquid templates
Float	String	Automatic in Liquid templates
Boolean	String	Becomes "true" or "false"
String	Integer	Use `\| plus: 0` filter

Example conversions:

liquid

{# Integer to string (automatic) #}
Score: {{ json.value }}

{# Boolean to string (automatic) #}
Urgent: {{ json.value }}

{# String to integer #}
{% assign num = json.value | plus: 0 %}