Structured Outputs Overview

Structured outputs allow you to define exact data schemas that agents must follow when returning responses, eliminating the need for additional parsing steps. By enforcing response formats at the model level, you get predictable, integration-ready data that matches your specified Pydantic models or JSON schemas.

Benefits of Structured Outputs

Leveraging structured outputs has many benefits, includingL

• Guaranteed Type Safety: Eliminate the need to validate or retry malformed responses. Agents automatically return data that conforms to your defined schema with built-in type checking and validation.
• Programmatic Error Handling: Safety-based model refusals and validation errors are returned in a structured, detectable format, making error handling predictable and programmatically manageable.
• Simplified Prompting: Remove complex prompt engineering focused on output formatting. No more lengthy instructions or strongly worded prompts trying to coerce consistent structure from free-form responses.
• Reduce Need for Additional LLM Calls: Eliminate the additional inference calls typically required to transform unstructured agent outputs into formats needed by downstream system consumption. Structured outputs provide integration-ready data without secondary processing steps, reducing both cost and latency.

Leveraging Structured Outputs

SeekrFlow structured outputs currently support two schema definition methods: Pydantic BaseModel classes and their JSON Schema equivalents. You must define your desired output structure using one of these approaches and pass it to the response_format parameter when running your agent.

Pydantic Example

from pydantic import BaseModel, Field
from typing import List
from seekrai import SeekrFlow

class ProductReview(BaseModel):
    product_name: str
    pros: List[str]
    cons: List[str]
    recommended: bool

# Use structured output with your agent
result = client.agents.runs.run(
    agent_id="your-agent-id",
    thread_id=thread.id,
    response_format=ProductReview
)

Multilevel Pydantic Objects

The user can also define multiple levels of Pydantic classes. An example is below:

from pydantic import BaseModel, Field
from typing import List
from seekrai import SeekrFlow

# Define nested objects first
class ReviewerInfo(BaseModel):
    name: str
    verified_purchase: bool
    review_date: str

class ProductSpecs(BaseModel):
    brand: str
    model: str
    price: float
    category: str

# Main object that includes nested objects
class ProductReview(BaseModel):
    product_name: str
    specs: ProductSpecs           # Nested object
    reviewer: ReviewerInfo        # Nested object
    pros: List[str]
    cons: List[str]
    recommended: bool

# Use structured output with your agent
result = client.agents.runs.run(
    agent_id="your-agent-id",
    thread_id=thread.id,
    response_format=ProductReview
)

# Agent will return nested data matching this structure:
# {
#   "product_name": "Wireless Headphones",
#   "specs": {
#     "brand": "Sony",
#     "model": "WH-1000XM4",
#     "price": 299.99,
#     "category": "Electronics"
#   },
#   "reviewer": {
#     "name": "John Smith",
#     "verified_purchase": true,
#     "review_date": "2024-01-15"
#   },
#   "pros": ["Great sound quality", "Long battery life"],
#   "cons": ["Expensive", "Heavy"],
#   "recommended": true
# }

Structured Output Validation Error

When the agent cannot successfully map the natural language output to the defined schema, it will throw a validation error. The validation error response can be found below:

# Validation Error - 422
{
  "error": "Value Error",
  "feedVersion": "1.0.0",
  "message": "Value error, Response format JSON schema could not be validated: <error>",
  "requestUrl": "https://services-api.seekr.com/v1/agents/runs",
  "status": 422
}

Structured Output Best Practices

When leveraging Structured outputs, the Seekr team recommends the following best practices:

1. Keep Schemas Simple and Focused: Design clear, straightforward schemas as complex structures with excessive fields or deep nesting can reduce model accuracy and reliability. We recommend limiting nesting to one level deep—while multiple levels are supported, single-level nesting provides the most consistent results.
2. Use Clear Field Names: Choose descriptive field names that help the reasoning model accurately map natural language output to your structure. Well-named fields like customer_email instead of email or total_price_usdinstead of price improve the model's ability to correctly populate each field with relevant data.
3. Use Few-Shot Prompting When Appropriate: Include examples in your agent's instructions to guide accurate field mapping. Providing sample inputs and expected structured outputs helps the model better understand how to transform natural language responses into your defined schema format.
4. Test Your Schemas Thoroughly: Validate your schemas against real queries and edge cases from your specific use cases. Test with various input types and scenarios to ensure consistent, accurate structured responses across different conditions before deploying to production.
5. Handle Errors Gracefully: Structured outputs can fail validation when the model cannot generate data matching your defined constraints. Always implement proper error handling in your application code to catch validation failures and provide appropriate fallback responses or retry logic.

Validation Error Handling

The SDK will throw a ValueErrorif a validation error occurs. An example error handle can be seen below:

from seekrai import SeekrFlow
from pydantic import BaseModel, Field
from typing import List

class ProductReview(BaseModel):
    product_name: str
    specs: ProductSpecs           # Nested object
    reviewer: ReviewerInfo        # Nested object
    pros: List[str]
    cons: List[str]
    recommended: bool

try:
    result = client.agents.runs.run(
        agent_id="your-agent-id",
        thread_id=thread.id,
        response_format=ProductReview
    )
     print(result)
except ValueError as e:
    print("Structured output validation failed:", e.message)

Structured Output Common Use-Cases

Structured outputs are not for every use-case. A few use-cases that do make sense to leverage structured outputs are:

Downstream System Integration: Use structured outputs when agent responses feed directly into external systems like APIs, databases, or business applications that require specific data formats. This eliminates additional parsing steps and reduces integration errors.
Data Extraction and Analysis: Apply structured outputs when extracting specific information from unstructured content like documents, emails, or web pages. The structured format enables immediate analysis and comparison across multiple extracted data points.