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

Status Fixed / completed

Maintainer reply None cached

Activity 4 comments · opened Jan 18, 2026 · closed Jan 21, 2026

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.

View original on GitHub ↗

4 Comments

github-actions[bot] · 9 months ago

Found 1 possible duplicate issue:

https://github.com/anthropics/claude-code/issues/18536

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

JeremyJonas · 8 months ago

Adding betas: ["structured-outputs-2025-11-13"] did not solve it for me, and get Type '"structured-outputs-2025-11-13"' is not assignable to type '"context-1m-2025-08-07"' warning. Result still does not contain structured output field with this.

Root cause for me was $schema field mismatch due to zod defaulting to "draft-2020-12" while claude requires "draft-07". Either removing $schema or use draft-07 gets claude to detect and correctly return structured output.

https://github.com/anthropics/claude-agent-sdk-typescript/issues/105#issuecomment-3766149153

coygeek · 8 months ago

Thank you for the updates to the documentation. I have reviewed the latest versions of the Agent SDK guides and cross-referenced them with the requirements for the Structured Outputs beta.

What’s FIXED

The primary inaccuracies and omissions identified in the original report have been addressed:

Explicit Beta Warning: A "Note" box has been added to the top of the Structured outputs guide at https://platform.claude.com/docs/en/agent-sdk/structured-outputs. It now explicitly states that the feature is in public beta and requires the structured-outputs-2025-11-13 beta header.
Python SDK Examples: All Python code blocks in the "Quick start" and "Type-safe schemas" sections of the aforementioned URL now include the betas=["structured-outputs-2025-11-13"] parameter. This applies to both the .create() and the new .parse() methods.
TypeScript SDK Examples: The TypeScript snippets at https://platform.claude.com/docs/en/agent-sdk/structured-outputs have been updated to include betas: ["structured-outputs-2025-11-13"] within the message creation configuration.
cURL Accuracy: The raw cURL examples now include the anthropic-beta header correctly, ensuring users who are testing the underlying protocol are not blocked by missing flags.

What’s UNRESOLVED

While the implementation guides are now accurate, there are minor gaps in the technical reference pages:

Parameter Context: In the Agent SDK reference - Python (https://platform.claude.com/docs/en/agent-sdk/python) and Agent SDK reference - TypeScript (https://platform.claude.com/docs/en/agent-sdk/typescript), the output_format / outputFormat parameters are listed in the ClaudeAgentOptions table, but they do not link back to the beta requirement. While the main guide is corrected, adding a small footnote or "Beta" tag in the reference tables would help prevent users from misconfiguring the options object when using the reference as a standalone resource.

Conclusion

The major blockers that prevented users from successfully implementing structured outputs via the Agent SDK have been resolved. The documentation now correctly reflects the manual requirement to pass the beta header, mitigating the high-impact issue where requests were previously being ignored or returning standard text.

Because the core functional examples are now technically accurate and the required syntax is clearly documented, I am closing this issue.

Final documentation for this feature can be found at: https://platform.claude.com/docs/en/agent-sdk/structured-outputs

github-actions[bot] · 8 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.