feat: add structured output support

[bogini]

Add structured output support to Python SDK.

Usage

from claude_agent_sdk import query, ClaudeAgentOptions

schema = {
    "type": "object",
    "properties": {"count": {"type": "number"}},
    "required": ["count"]
}

async for msg in query(
    prompt="Count files in src/",
    options=ClaudeAgentOptions(
        output_format={"type": "json_schema", "schema": schema}
    )
):
    if hasattr(msg, 'structured_output'):
        print(msg.structured_output)

Documentation

https://docs.claude.com/en/docs/agent-sdk/structured-outputs

Tests

• Unit tests: tests/test_integration.py::TestIntegration::test_structured_output
• E2E tests: e2e-tests/test_structured_output.py (4 tests)

[zhammer]

heyo, the docs say that the following beta header has to be set - structured-outputs-2025-11-13 - but there's nothing to set that in this PR. it looks like that was added in the not-merged #328.

should we expect this to work without that beta header being set?

[ashwin-ant]

@zhammer yes, this works in the Agent SDK without any configuration on your part.

[zhammer]

@ashwin-ant great, just confirmed on our end. i was just a bit confused by the discrepancy with docs. thank you

[ashwin-ant]

For the agent sdk there are specific docs on structured output here: https://platform.claude.com/docs/en/agent-sdk/structured-outputs

[Shwapx]

Can you use the structured output with ClaudeSDKClient or it's only for query()