Structured Output

Structured output enables your agents to return data in a predefined schema instead of free-form text. This is essential for integrating agents with databases, APIs, or any system that requires consistent data formats.

Overview

When you enable structured output, your agent will:

Process the input normally
Extract information according to your schema
Return validated, typed data matching your specification
Ensure type safety and consistency

Structured output uses runtime schema generation and validation to ensure your agents return properly formatted data.

Important: Structured output is NOT included in the conversation history array. This means structured output from previous agents is only accessible through template variables in prompts (e.g., {{ agent_name.output.field }}) and will not appear in the {{ history }} or {{ history[N] }} variables.

When to Use Structured Output

Data Extraction

Extract structured information from unstructured text (resumes, invoices, documents)

API Integration

Generate responses that match your API schema requirements

Database Inserts

Create records with validated fields for database operations

Multi-Agent Pipelines

Pass typed data between agents in complex workflows

Basic Configuration

Add the structured_output field to your agent configuration:

agents:
  - name: "data_extractor"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: "Extract contact information from the provided text."
    
    structured_output:
      enabled: true
      schema:
        name:
          type: "str"
          description: "Full name of the person"
        email:
          type: "str"
          description: "Email address"
        phone:
          type: "str"
          description: "Phone number"

Type Notation

Define field types using our type notation syntax:

Basic Types

type

Text data

name:
  type: "str"
  description: "Person's full name"

type

Integer numbers

age:
  type: "int"
  description: "Age in years"

type

Decimal numbers

confidence:
  type: "float"
  description: "Confidence score between 0.0 and 1.0"

type

Boolean values (true/false)

is_verified:
  type: "bool"
  description: "Whether the information is verified"

Collection Types

type

List of items of type T

skills:
  type: "list[str]"
  description: "List of technical skills"

scores:
  type: "list[float]"
  description: "List of test scores"

type

Dictionary mapping keys of type K to values of type V

metadata:
  type: "dict[str, str]"
  description: "Additional metadata fields"

scores_by_subject:
  type: "dict[str, float]"
  description: "Subject name to score mapping"

Nullable Types

type

Optional/nullable value of type T

middle_name:
  type: "str | None"
  description: "Middle name if available, null otherwise"

score:
  type: "float | None"
  description: "Score if calculable, null otherwise"

You can also use Optional[T] syntax:

notes:
  type: "Optional[str]"
  description: "Optional notes"

Enum types are not currently supported. Use str type with clear descriptions for fields that should have restricted values. Guide the LLM via your system prompt to output specific allowed values.

Quick Start Example

Extract contact information from text:

agents:
  - name: "contact_extractor"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: "Extract contact information from the provided text."
    
    structured_output:
      enabled: true
      schema:
        name:
          type: "str"
          description: "Person's full name"
        
        email:
          type: "str"
          description: "Email address"
        
        phone:
          type: "str"
          description: "Phone number"
        
        company:
          type: "str"
          description: "Company name"

Input:

John Smith from Acme Corp can be reached at john@acme.com or 555-1234

Output:

{
  "name": "John Smith",
  "email": "john@acme.com",
  "phone": "555-1234",
  "company": "Acme Corp"
}

Multi-Agent Data Passing

Use structured output to pass typed data between agents in workflows. Downstream agents can access structured outputs from previous agents using template variables in their system prompts.

Accessing Structured Output in Prompts

Use the {{ agent_name.output.field }} syntax to inject structured output into agent prompts:

agents:
  - name: "data_extractor"
    agent_type: "llm_agent"
    structured_output:
      enabled: true
      schema:
        company_name:
          type: "str"
          description: "Company name"
        revenue:
          type: "float"
          description: "Annual revenue in millions"
  
  - name: "analyzer"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: |
        Analyze the company data:
        - Company: {{ data_extractor.output.company_name }}
        - Revenue: ${{ data_extractor.output.revenue }}M
        
        Provide insights on market position and growth potential.

Supported template variables:

{{ agent_name.output.field }} — Access specific field from structured output
{{ agent_name.output.nested.field }} — Access nested fields (dot-separated path)
{{ agent_name.output }} — Access entire structured output as JSON string
{{ variables.name }} — Access custom variables (see Variables System)
{{ user_input }} — Latest user message
{{ history[N] }} — Last N messages from conversation (structured output NOT included)

Critical: Structured output is excluded from history variables. Use the specific {{ agent_name.output.field }} template variables to access structured data from previous agents.

Complex data types (lists, dicts) are automatically serialized to JSON when injected into prompts.

Multi-Agent Example

Pass structured data between agents:

name: "Data Pipeline"
architecture: "workflow"

agents:
  - name: "extractor"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: "Extract key metrics from the report."
    
    structured_output:
      enabled: true
      schema:
        revenue:
          type: "float"
          description: "Annual revenue in millions"
        growth_rate:
          type: "float"
          description: "Year-over-year growth percentage"
  
  - name: "analyzer"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: |
        Analyze the company metrics:
        Revenue: ${{ extractor.output.revenue }}M
        Growth: {{ extractor.output.growth_rate }}%
        
        Provide insights on performance and recommendations.

edges:
  - from: "__start__"
    to: "extractor"
  - from: "extractor"
    to: "analyzer"
  - from: "analyzer"
    to: "__end__"

entry_point: "extractor"

Template variables: Use {{ agent_name.output.field }} to access structured output from previous agents

Best Practices

Clear Descriptions: Always provide detailed descriptions for each field. The agent uses these to understand what to extract.

Appropriate Types: Choose the most specific type possible. For fields with restricted values, use str type and specify allowed values in the description and system prompt.

System Prompt Alignment: Ensure your system prompt explicitly mentions the structured output requirements.

Type Validation: All output is validated against your schema. Invalid data will cause errors. Test your schemas thoroughly.

Nested Structures: For complex nested objects, consider breaking them into multiple agents or using dict types with clear descriptions.

Configuration Reference

Schema Structure

The structured_output field has the following structure:

object

Configuration for structured output generation

Show Properties

boolean

Enable or disable structured output for this agentWhen true, the agent will return data matching the defined schema instead of free-form text.Default: true

object

required

Schema definition mapping field names to field specificationsEach key is a field name, and each value is an object with type and optional description.Required when enabled: true

Field Specification

Each field in the schema must have:

string

required

Type notation for the fieldSee Type Notation Reference for all supported types.Supported types: str, int, float, bool, list[T], dict[K, V], T | None, Optional[T], Any

string

Human-readable description of what this field represents (optional but strongly recommended).The agent uses this description to understand what data to extract. Be specific and clear. Fields without descriptions may produce less accurate results.

Agent Type Support

llm_agent: ✅ Fully supported - LLM agents can generate structured output for any schema

react_agent: ✅ Fully supported - ReAct agents generate structured output after completing their tool-calling iterations

supervisor: ❌ Not supported - Supervisor agents focus on coordination and do not produce structured output

Validation and Error Handling

The system automatically validates structured output:

Type Checking: Values must match the declared type

Required Fields: All fields in the schema must be present in the output

Format Validation: Basic format checking for strings, numbers, etc.

Common Errors

Error	Cause	Solution
`Invalid type notation`	Unsupported type syntax	Check Type Notation Reference
`Missing required field`	Agent didn’t provide all fields	Improve system prompt to mention all fields
`Type validation failed`	Value doesn’t match expected type	Ensure agent outputs correct type for the field
`Type mismatch`	Wrong data type	Ensure agent outputs correct type (e.g., number not string)

Example Error Response

If validation fails, you’ll receive a detailed error:

{
  "error": {
    "type": "StructuredOutputValidationError",
    "message": "Field 'age' has invalid value 'thirty'. Expected type: int",
    "field": "age",
    "expected": "int",
    "received": "thirty"
  }
}

Variable Assignments

Structured output fields can be automatically mapped to system variables using variable_assignments. This creates a data pipeline: structured output → variables → downstream prompt substitution.

variables:
  customer_name:
    type: "str"
    description: "Extracted customer name"
  priority:
    type: "str"
    default: "medium"

agents:
  - name: "extractor"
    agent_type: "llm_agent"
    structured_output:
      enabled: true
      schema:
        name:
          type: "str"
          description: "Customer name"
        urgency:
          type: "str"
          description: "Priority level"
    variable_assignments:
      customer_name: "extractor.output.name"
      priority: "extractor.output.urgency"
  
  - name: "responder"
    agent_type: "llm_agent"
    prompt_config:
      system_prompt: |
        Customer: {{ variables.customer_name }}
        Priority: {{ variables.priority }}
        Respond appropriately.

Variable assignments also support static values and non-structured output. The system applies automatic type coercion during variable assignment, converting strings to types like integers, booleans, or JSON arrays to ensure they match the variable’s defined type. See Variables System for details.

Limitations

Structured output is currently supported for llm_agent and react_agent types
Complex nested objects may require careful prompt engineering
Very large schemas (>20 fields) may impact performance
Use str | None or Optional[str] for optional fields
Output must be valid JSON
Enum types are not supported

Next Steps

Conditional Edges

Learn how to route agents based on structured output values

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

Overview

When to Use Structured Output

Data Extraction

API Integration

Database Inserts

Multi-Agent Pipelines

Basic Configuration

Type Notation

Basic Types

Collection Types

Nullable Types

Quick Start Example

Multi-Agent Data Passing

Accessing Structured Output in Prompts

Multi-Agent Example

Best Practices

Configuration Reference

Schema Structure

Field Specification

Agent Type Support

Validation and Error Handling

Common Errors

Example Error Response

Variable Assignments

Limitations

Next Steps

Conditional Edges

​Overview

​When to Use Structured Output

Data Extraction

API Integration

Database Inserts

Multi-Agent Pipelines

​Basic Configuration

​Type Notation

​Basic Types

​Collection Types

​Nullable Types

​Quick Start Example

​Multi-Agent Data Passing

​Accessing Structured Output in Prompts

​Multi-Agent Example

​Best Practices

​Configuration Reference

​Schema Structure

​Field Specification

​Agent Type Support

​Validation and Error Handling

​Common Errors

​Example Error Response

​Variable Assignments

​Limitations

​Next Steps

Conditional Edges

Overview

When to Use Structured Output

Basic Configuration

Type Notation

Basic Types

Collection Types

Nullable Types

Quick Start Example

Multi-Agent Data Passing

Accessing Structured Output in Prompts

Multi-Agent Example

Best Practices

Configuration Reference

Schema Structure

Field Specification

Agent Type Support

Validation and Error Handling

Common Errors

Example Error Response

Variable Assignments

Limitations

Next Steps