feat: add structured outputs support with Pydantic integration

README.md

@@ -76,6 +76,58 @@ options = ClaudeAgentOptions(
 )
 ```
 
+### Structured Outputs
+
+> **⚠️ NOT YET FUNCTIONAL**: This feature requires CLI support (see [anthropics/claude-code#9058](https://github.com/anthropics/claude-code/issues/9058)). The API and utilities are ready, but structured outputs won't work until the CLI implements schema passing.
+
+Structured outputs allow you to get responses from Claude in a specific JSON schema format, ensuring type-safe and predictable responses.
+
+#### Using Raw JSON Schema
+
+```python
+from claude_agent_sdk import query
+
+# Define your expected output schema
+schema = {
+    "type": "object",
+    "properties": {
+        "name": {"type": "string"},
+        "email": {"type": "string"},
+        "plan_interest": {"type": "string"},
+        "demo_requested": {"type": "boolean"}
+    },
+    "required": ["name", "email", "plan_interest", "demo_requested"]
+}
+
+async for message in query(
+    prompt="Extract info: John Smith ([email protected]) wants Enterprise plan demo",
+    output_format=schema
+):
+    print(message)
+```
+
+#### Using Pydantic Models (Recommended)
+
+```python
+from pydantic import BaseModel, Field
+from claude_agent_sdk import query
+
+class EmailExtraction(BaseModel):
+    """Structured data from an email."""
+    name: str = Field(description="Full name")
+    email: str = Field(description="Email address")
+    plan_interest: str = Field(description="Plan they're interested in")
+    demo_requested: bool = Field(description="Whether they requested a demo")
+
+async for message in query(
+    prompt="Extract info: Sarah ([email protected]) wants Professional plan demo",
+    output_format=EmailExtraction  # Pass the Pydantic model class
+):
+    print(message)
+```
+
+For more examples, see [examples/structured_outputs.py](examples/structured_outputs.py).
+
 ## ClaudeSDKClient
 
 `ClaudeSDKClient` supports bidirectional, interactive conversations with Claude
@@ -271,6 +323,8 @@ See [examples/quick_start.py](examples/quick_start.py) for a complete working ex
 
 See [examples/streaming_mode.py](examples/streaming_mode.py) for comprehensive examples involving `ClaudeSDKClient`. You can even run interactive examples in IPython from [examples/streaming_mode_ipython.py](examples/streaming_mode_ipython.py).
 
+See [examples/structured_outputs.py](examples/structured_outputs.py) for structured outputs examples using both Pydantic models and raw JSON schemas.
+
 ## Migrating from Claude Code SDK
 
 If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the [CHANGELOG.md](CHANGELOG.md#010) for details on breaking changes and new features, including: