> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypertic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  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.
</Note>

## Schema Types

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

<CodeGroup>
  ```python Pydantic Model theme={null} theme={null}
  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.

  ```python Dataclass theme={null} theme={null}
  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).

  ```python TypedDict theme={null} theme={null}
  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.
</CodeGroup>

## Non-Streaming

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

<CodeGroup>
  ```python Sync theme={null} theme={null}
  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)
  ```

  ```python Async theme={null} theme={null}
  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())
  ```
</CodeGroup>

## Streaming

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

<CodeGroup>
  ```python Sync theme={null} theme={null}
  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)
  ```

  ```python Async theme={null} theme={null}
  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())
  ```
</CodeGroup>

**Response Format:**

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

```python theme={null} theme={null}
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
```