---
title: Structured Output Example
sidebar:
  label: "Structured Output"
redirectFrom:
  - docs/examples/python/structured_output
---

Structured output lets you get type-safe, validated responses from language models. Instead of raw text that you need to parse manually, you define the exact structure you want and receive a validated object.

Each language uses its own schema library for defining output structures. See the tabs below for language-specific examples.

## Basic Structured Output

Define a schema and pass it to the agent. The agent returns a validated object matching your schema.

<Tabs>
<Tab label="Python">

```python
from pydantic import BaseModel
from strands import Agent

class PersonInfo(BaseModel):
    name: str
    age: int
    occupation: str

agent = Agent()
result = agent(
    "John Smith is a 30-year-old software engineer",
    structured_output_model=PersonInfo
)

print(f"Name: {result.structured_output.name}")      # "John Smith"
print(f"Age: {result.structured_output.age}")        # 30
print(f"Job: {result.structured_output.occupation}") # "software engineer"
```
</Tab>
<Tab label="TypeScript">

```typescript
import { Agent } from '@strands-agents/sdk'
import { z } from 'zod'

--8<-- "examples/structured_output.ts:basic_example"
```
</Tab>
</Tabs>

## Complex Nested Schemas

Schemas can be nested to represent complex data structures:

<Tabs>
<Tab label="Python">

```python
from typing import List, Optional
from pydantic import BaseModel, Field
from strands import Agent

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: Optional[str] = None

class Contact(BaseModel):
    email: Optional[str] = None
    phone: Optional[str] = None

class Person(BaseModel):
    name: str = Field(description="Full name of the person")
    age: int = Field(description="Age in years")
    address: Address = Field(description="Home address")
    contacts: List[Contact] = Field(default_factory=list, description="Contact methods")
    skills: List[str] = Field(default_factory=list, description="Professional skills")

agent = Agent()
result = agent(
    "Extract info: Jane Doe, a systems admin, 28, lives at 123 Main St, New York, USA. Email: jane@example.com",
    structured_output_model=Person
)

print(f"Name: {result.structured_output.name}")
print(f"Age: {result.structured_output.age}")
print(f"Street: {result.structured_output.address.street}")
print(f"City: {result.structured_output.address.city}")
print(f"Email: {result.structured_output.contacts[0].email}")
```
</Tab>
<Tab label="TypeScript">

```typescript
import { Agent } from '@strands-agents/sdk'
import { z } from 'zod'

--8<-- "examples/structured_output.ts:nested_models"
```
</Tab>
</Tabs>

## How It Works

1. Define a schema using your language's schema library
2. Pass the schema to the agent when invoking it
3. Access the validated output from the result

The agent converts your schema into a tool specification that guides the language model to produce correctly formatted responses, then validates the output automatically.

## Learn More

For more details, see the [Structured Output documentation](../user-guide/concepts/agents/structured-output.md).
