Structured output forces the agent to respond with JSON matching a specific schema. This is useful when you need consistent, parseable output for downstream processing, API responses, or integration with other systems.
When to use structured output:
- Building API endpoints that need consistent JSON responses
- Data extraction and transformation pipelines
- Agents that feed into other automated systems
- Ensuring predictable output format for parsing
Configuration
Add structured_output to an agent definition:
agents:
analyzer:
model: openai/gpt-4o
description: Code analyzer that outputs structured results
instruction: |
Analyze the provided code and identify issues.
Return your findings in the structured format.
structured_output:
name: analysis_result
description: Code analysis findings
strict: true
schema:
type: object
properties:
issues:
type: array
items:
type: object
properties:
severity:
type: string
enum: ["error", "warning", "info"]
line:
type: integer
message:
type: string
required: ["severity", "line", "message"]
summary:
type: string
required: ["issues", "summary"]
Fields
Name identifier for the output schema. Used internally by the model provider.
structured_output.description
Description of what the output represents. Passed to the model to help it understand what to produce.
When true, the model output is constrained to exactly match the schema. Provides stronger guarantees but may limit flexibility.
Schema patterns
Simple object
structured_output:
name: result
schema:
type: object
properties:
name:
type: string
count:
type: integer
active:
type: boolean
required: ["name", "count"]
Array of objects
structured_output:
name: items
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
value:
type: number
required: ["id", "value"]
required: ["items"]
Enum values
structured_output:
name: classification
schema:
type: object
properties:
status:
type: string
enum: ["pending", "approved", "rejected"]
priority:
type: string
enum: ["low", "medium", "high", "critical"]
required: ["status"]
Strict mode
strict: false (default)
strict: true
The model aims to match the schema but may include additional fields or slight variations. More flexible, less predictable.
The model output is constrained to exactly match the schema. Stronger guarantees but less flexibility. Recommended for production pipelines.
Provider support
| Provider | Support | Notes |
|---|
| OpenAI | Full | Native JSON mode with schema validation |
| Anthropic | Full | Tool-based structured output |
| Google Gemini | Full | Native JSON mode |
| AWS Bedrock | Partial | Depends on underlying model |
| DMR | Limited | Depends on model capabilities |
Examples
models:
gpt4_structured:
provider: openai
model: gpt-4o-2024-08-06
temperature: 0.7
max_tokens: 1000
agents:
root:
model: gpt4_structured
description: Extracts structured information about people
instruction: |
You are an assistant that extracts structured information about people
from conversations. Always respond with valid JSON matching the schema.
commands:
demo: "My name is John Doe, I am 30 years old, my email is [email protected], and I enjoy hiking and photography."
structured_output:
name: person_info
description: Information about a person
strict: true
schema:
type: object
properties:
name:
type: string
description: The person's full name
age:
type: integer
description: The person's age
email:
type: string
description: The person's email address
hobbies:
type: array
items:
type: string
description: List of the person's hobbies
required: [name, age, email, hobbies]
additionalProperties: false
agents:
extractor:
model: openai/gpt-4o
description: Extract contact information from text
instruction: |
Extract contact information from the provided text.
Return all found contacts in the structured format.
structured_output:
name: contacts
description: Extracted contact information
strict: true
schema:
type: object
properties:
contacts:
type: array
items:
type: object
properties:
name:
type: string
email:
type: string
phone:
type: string
company:
type: string
required: ["name"]
total_found:
type: integer
required: ["contacts", "total_found"]
Ticket classification
agents:
classifier:
model: anthropic/claude-sonnet-4-0
description: Classify support tickets
instruction: |
Classify the support ticket into the appropriate category
and priority level based on its content.
structured_output:
name: ticket_classification
strict: true
schema:
type: object
properties:
category:
type: string
enum: ["billing", "technical", "account", "feature_request", "other"]
priority:
type: string
enum: ["low", "medium", "high", "urgent"]
confidence:
type: number
minimum: 0
maximum: 1
reasoning:
type: string
required: ["category", "priority", "confidence"]
When using structured output, the agent typically cannot use tools because its response format is constrained to the schema. Structured output works best for single-turn analysis or extraction tasks that don’t require tool use.