> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Structured Outputs
> Configure named outputs for an AI step and link them to later Flow steps.
Structured outputs are named values produced by an AI step. Configure them in the step's **Parameters** sidebar, then use them as linked inputs in later steps.
Understanding structured outputs
Each output variable has a name, a **Data type** selector, a **Make array** control, and a required description. Add as many outputs as the AI step needs.
**Why use structured outputs:**
* Keep related results as separate, named values.
* Describe the value and data type the AI step should return.
* Link a selected output directly to a downstream input.
* Use **Make array** when an output needs multiple values of the same type.
Output variables are defined in an AI step's **Parameters** tab.
Open the agent's **Flow**, select the AI step that produces the result, and keep **Parameters** selected in the sidebar.
In **Output variables**, select **Add new**.
Enter the output name, select a **Data type**, optionally enable **Make array**, and provide the required description.
Select **Add new** again to define another value for the same node.
Multiple output variables
Use one output variable for each value a later step needs. For example, an AI step can return a summary, search terms, and a title as separate outputs.
Data types
**String:** Text data of any length. Use for names, descriptions, categories.
**Number:** Numeric values including integers and decimals. Use for IDs, quantities, amounts, scores.
**Boolean:** True or false values. Use for flags, status indicators, yes/no determinations.
**Object:** Nested data for complex, grouped values. Select **Object** in **Data type**, then select **Define structure** to add the properties the object should contain.
**Enum:** Constrained to specific allowed values. Use for fixed categories, status values.
**Example:**
```text theme={null}
Variable: priority_level
Type: Enum
Allowed values: HIGH, MEDIUM, LOW
```
Key principles
Order related values clearly
For a complex extraction, group related outputs together and use names that make their relationship clear.
**Example:**
```json theme={null}
{
"request_summary": "",
"urgency_analysis": "",
"is_urgent": "",
"category_reasoning": "",
"category": "",
"priority": ""
}
```
Keep rationale when it is useful
If a later step or reviewer needs the rationale behind a classification, add a separate reasoning output alongside the final value.
**Poor Design:**
```json theme={null}
{
"category": ""
}
```
**Better Design:**
```json theme={null}
{
"category_reasoning": "",
"category": ""
}
```
This keeps the classification and its explanation as distinct values that later steps can use independently.
Descriptions are directives
The description is a direct instruction to the AI. Be explicit.
**Examples:**
**Simple extraction:**
```text theme={null}
"Extract the 7-digit customer ID, numbers only"
```
**Conditional logic:**
```text theme={null}
"Extract language as ISO-639-1 code. If unknown, return 'N/A'"
```
**Constrained values:**
```text theme={null}
"Classify as one of: EXACT_MATCH, SIMILAR_MATCH, MISMATCH, or N/A"
```
Unique naming
Give each output a clear, unique name so it is easy to choose in a later step.
**Good naming:**
* `email_classifier_category`
* `invoice_extractor_total`
* `customer_analysis_id`
**Avoid:**
* `result`, `output`, `data` (too generic, likely duplicated)
Linking outputs to downstream nodes
To use an output in a later step, select that input's fill-method menu, choose **Linked fill**, then select the output variable.
The variable picker lists output variables from earlier steps in the Flow.
See [Variables & State](/02-building-agents/agent-configuration/variables-state/variables-state) for detailed linking patterns.
Common patterns
**Classification + Data Extraction:**
```json theme={null}
{
"classification": "",
"customer_id": "",
"urgency_level": ""
}
```
Use: Branch workflow based on `classification`, pass `customer_id` to CRM lookup, use `urgency_level` for prioritization.
**Validation with Confidence:**
```json theme={null}
{
"extracted_value": "",
"confidence_score": "",
"needs_review": ""
}
```
Use: Branch on `needs_review` - high confidence → automate, low confidence → human review.
**Handling Arrays:**
For multiple values of the same type, enable **Make array** for the output variable:
```text theme={null}
Variable: products
Data type: String
Make array: enabled
Description: Product names found in the order
```
Use **Object** and **Define structure** when each array item needs its own nested properties.
Best practices
**Naming Conventions:**
* Prefix with tool purpose: `email_classifier_category`, `invoice_extractor_total`
* Use descriptive names: `customer_priority_score` not `score`
* Avoid generic names: Don't use `result`, `output`, `data`
**Separation of Concerns:**
Don't combine everything into one field. Split outputs logically:
```json theme={null}
{
"customer_name": "",
"customer_email": "",
"order_id": "",
"priority": ""
}
```
**Error Handling:**
Design outputs to capture extraction confidence:
```json theme={null}
{
"extracted_date": "",
"date_confidence": "",
"extraction_notes": ""
}
```
**Performance Optimization:**
Minimize unnecessary reasoning fields in high-volume workflows. Use reasoning for critical extractions, skip for simple operations.
Troubleshooting
**Issue:** AI returns string when you expected number
**Solutions:**
* Make description more explicit: "Extract as a number, digits only, no text"
* Check if source data actually contains the expected type
* Add validation in description: "If not a number, return 0"
**Issue:** AI returns dates in different formats
**Solutions:**
* Be prescriptive: "Return date in YYYY-MM-DD format exactly"
* Provide examples in description: "Format: 2024-01-15"
* Use constrained values (Enum) when possible
**Issue:** Some outputs are empty or null
**Solutions:**
* Add fallback instructions: "If not found, return 'N/A'"
* Check if AI has access to required input data
* Verify previous nodes are passing data correctly
**Issue:** Downstream node can't access structured output
**Solutions:**
* Confirm the source step runs before the step that consumes it
* Open the destination input's fill-method menu and select **Linked fill**
* Select the expected output variable from the variable picker
Next steps
Learn how to link structured outputs between nodes
Choose AI steps and integrations for an agent Flow.
Pass linked outputs to integration steps.
Use structured outputs for branching and routing
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.