Structured outputs use a Pydantic BaseModel or JSON schema to enforce a response format on your agent, giving you typed, integration-ready data without extra parsing or post-processing. Use them when agent responses feed directly into external systems like APIs or databases, or when extracting structured information from unstructured content like documents and emails.

Define a schema with Pydantic

Define a Pydantic model in the response_format parameter:

Endpoint: POST /v1/threads/{thread_id}/runs Run agent

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

class ProductReview(BaseModel):
    product_name: str = Field(description="The full product name as listed")
    pros: List[str] = Field(description="List of positive aspects, maximum 3 items")
    cons: List[str] = Field(description="List of negative aspects, maximum 3 items")
    recommended: bool = Field(description="Whether the reviewer recommends this product")

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

Define nested Pydantic objects

You can also define multiple levels of Pydantic classes:

Endpoint: POST /v1/threads/{thread_id}/runs Run agent

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 = Field(description="The full product name as listed")
    specs: ProductSpecs = Field(description="Technical specifications of the product")
    reviewer: ReviewerInfo = Field(description="Information about the reviewer")
    pros: List[str] = Field(description="List of positive aspects, maximum 3 items")
    cons: List[str] = Field(description="List of negative aspects, maximum 3 items")
    recommended: bool = Field(description="Whether the reviewer recommends this product")

# 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
# }

Handle validation errors

When the agent cannot map its response to the defined schema, a validation error is returned.

Endpoint: POST /v1/threads/{thread_id}/runs Run agent

# 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
}

If you receive a validation error, handle the error as shown:

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 Exception as e:
    print("Structured output validation failed:", str(e))

Improve schema accuracy

When using structured outputs, we recommend the following:

Keep schemas simple and focused. Complex structures with excessive fields or deep nesting can reduce model accuracy. Limit nesting to one level deep. While multiple levels are supported, single-level nesting produces the most consistent results.
Use clear field names. Choose descriptive field names that help the model accurately map response content to your schema. For example, customer_email is clearer than email, and total_price_usd is clearer than price.
Use few-shot prompting. Include examples in your agent's instructions to guide accurate field mapping. Sample inputs and expected outputs help the model understand how to structure its response.
Test your schemas thoroughly. Validate your schemas against real queries and edge cases before deploying. Test with a range of input types to ensure consistent results.