Structured Output

Structured output ensures agents return responses in a defined, validated format. Rather than receiving free-form text that you need to parse and validate yourself, you get type-safe data objects (Pydantic models, dataclasses, or TypedDict) that are immediately usable in your application. This eliminates the need for manual parsing, reduces errors, and provides type safety throughout your codebase. Common use cases include extracting structured data from documents, parsing user input, generating API responses, and building data pipelines.

Structured output works with most models. DeepSeek and Qwen do not support structured output. Only Anthropic, OpenAI, xAI, and Cohere support tools + structured output together.

Schema Types

Define your response schema using Pydantic models, dataclasses, or TypedDict. Each has different strengths:

from pydantic import BaseModel
from typing import Optional

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

Best for: Validation, type safety, IDE support. Recommended for most use cases.

from dataclasses import dataclass
from typing import Optional

@dataclass
class Product:
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

Best for: Simple schemas, standard library only (no dependencies).

from typing import TypedDict, Optional

class Product(TypedDict):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str]

Best for: Dictionary-like structures, minimal overhead.

Non-Streaming

Get structured responses using run() or arun() with the output_type parameter:

from pydantic import BaseModel
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

model = OpenAIChat(model="gpt-5.2")

agent = Agent(
    model=model,
    output_type=Product
)

# Non-streaming structured output
response = agent.run(
    query="Wireless headphones, priced at $99.99, in the Electronics category, currently in stock. Great sound quality and noise cancellation."
)
print(response.content)
print(response.metadata)

import asyncio
from pydantic import BaseModel
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

model = OpenAIChat(model="gpt-5.2")

agent = Agent(
    model=model,
    output_type=Product
)

async def main():
    # Non-streaming structured output
    response = await agent.arun(
        query="Wireless headphones, priced at $99.99, in the Electronics category, currently in stock. Great sound quality and noise cancellation."
    )
    print(response.content)
    print(response.metadata)

asyncio.run(main())

Streaming

Stream structured responses using stream() or astream():

from pydantic import BaseModel
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

model = OpenAIChat(model="gpt-5.2")

agent = Agent(
    model=model,
    output_type=Product
)

# Streaming structured output
for event in agent.stream(
    query="Wireless headphones, priced at $99.99, in the Electronics category, currently in stock. Great sound quality and noise cancellation."
):
    if event.type == "content":
        print(event.content, end="", flush=True)

import asyncio
from pydantic import BaseModel
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

model = OpenAIChat(model="gpt-5.2")

agent = Agent(
    model=model,
    output_type=Product
)

async def main():
    # Streaming structured output
    async for event in agent.astream(
        query="Wireless headphones, priced at $99.99, in the Electronics category, currently in stock. Great sound quality and noise cancellation."
    ):
        if event.type == "content":
            print(event.content, end="", flush=True)

asyncio.run(main())

Response Format: When using structured output, response.content is an instance of your schema:

from pydantic import BaseModel
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

model = OpenAIChat(model="gpt-5.2")
agent = Agent(model=model, output_type=Product)

response = agent.run("Extract product info: Wireless headphones, $99.99, Electronics, in stock")

# response.content is a Product instance
product = response.content
print(product.name)        # "Wireless headphones"
print(product.price)       # 99.99
print(product.category)   # "Electronics"
print(product.in_stock)   # True

Get started

Agent

Workflow

Structured Output

Schema Types

Non-Streaming

Streaming

​Schema Types

​Non-Streaming

​Streaming

Schema Types

Non-Streaming

Streaming