[DOCS] Missing beta header requirements in Agent SDK Structured Outputs documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Quick start" examples and "Output format configuration" sections.

Current Documentation

The SDK documentation provides code examples for Python and TypeScript using the output_format option. For example:

options = ClaudeAgentOptions(
    output_format={
        "type": "json_schema",
        "schema": schema
    }
)

It does not mention or include any requirement for a beta header.

What's Wrong or Missing?

The main Claude API documentation for Structured Outputs (https://platform.claude.com/docs/en/build-with-claude/structured-outputs) explicitly states:

"To use the feature, set the beta header structured-outputs-2025-11-13."

However, the Agent SDK documentation fails to mention this. Furthermore, the internal transport implementation (specifically subprocess_cli.py in the Python SDK) does not automatically inject this header when output_format is detected. Consequently, users following the SDK documentation will likely find that their structured output requests are either ignored or return standard text because the underlying Messages API request is missing the required beta flag.

Suggested Improvement

The documentation should be updated to include the betas parameter in the ClaudeAgentOptions for all Structured Output examples.

Suggested Python Example:

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"], # This line is currently missing from docs
    output_format={
        "type": "json_schema",
        "schema": schema
    }
)

Suggested TypeScript Example:

const response = await query({
  prompt: "...",
  options: {
    model: "claude-sonnet-4-5",
    betas: ["structured-outputs-2025-11-13"], // This line is currently missing from docs
    outputFormat: {
      type: 'json_schema',
      schema: schema
    }
  }
});

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation showing the header requirement: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
• In the Python SDK src/claude_agent_sdk/_internal/transport/subprocess_cli.py, the --betas flag is implemented but not automatically populated for this feature, making the explicit documentation even more critical.