[DOCS] Missing `effort` parameter in `ClaudeAgentOptions` (Python SDK)

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/python - https://platform.claude.com/docs/en/build-with-claude/effort

Section/Topic

The ClaudeAgentOptions parameter list within the Python Agent SDK reference.

Current Documentation

The Effort guide (https://platform.claude.com/docs/en/build-with-claude/effort) states:

"Claude Opus 4.5 is the only model that supports the effort parameter... include the beta header effort-2025-11-24."

However, the Agent SDK reference - Python (https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions) lists all available fields for the ClaudeAgentOptions dataclass but does not mention effort or an output_config parameter.

What's Wrong or Missing?

The effort parameter is a core feature for the new Claude Opus 4.5 model, allowing users to trade off between response thoroughness and token efficiency. While the feature is documented in the "Build with Claude" section, it is completely omitted from the Python SDK's ClaudeAgentOptions definition.

Reviewing the provided source code confirms this omission:

• src/claude_agent_sdk/types.py: The ClaudeAgentOptions dataclass lacks an effort or output_config field.
• src/claude_agent_sdk/_internal/transport/subprocess_cli.py: The _build_command method contains no logic to map an effort parameter to a CLI flag (e.g., --effort).

Suggested Improvement

1. Update the Python SDK Reference: Add effort to the ClaudeAgentOptions table.
2. Add Type Definitions: Update the documentation to show the parameter in the dataclass:

   @dataclass
   class ClaudeAgentOptions:
       # ... existing fields ...
       effort: Literal["low", "medium", "high"] | None = None

3. Update Parameters Table:

   Property	Type	Default	Description
   effort	Literal["low", "medium", "high"] | None	None	Control how many tokens Claude uses when responding. Requires Claude Opus 4.5 and the effort-2025-11-24 beta header.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: https://platform.claude.com/docs/en/build-with-claude/effort
• Discrepancy: The "Effort" guide shows a code example using output_config={"effort": "medium"}, but the Python SDK ClaudeAgentOptions does not support this structure, and the SDK reference lists neither effort nor output_config.
• Note: The TypeScript SDK reference (https://platform.claude.com/docs/en/agent-sdk/typescript) also appears to lack this parameter in its Options type definition.

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Add effort parameter support for Opus 4.5 in Claude Code #12376
2. [DOCS] ClaudeAgentOptions code block missing implemented fields in Python SDK reference #19418
3. [FEATURE] How to set thinking effort with Opus 4.5? #12403

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

[coygeek]

Following up on the audit of the Claude Agent SDK documentation regarding the missing effort parameter support.

1. What’s FIXED

• General Feature Documentation: A dedicated guide for the Effort parameter has been created at https://platform.claude.com/docs/en/build-with-claude/effort. This page correctly identifies that the feature is exclusive to Claude Opus 4.5 and requires the effort-2025-11-24 beta header.
• Model Capabilities Visibility: The "What's new in Claude 4.5" page at https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-5 now explicitly lists the "Effort parameter" as a key improvement for the Opus 4.5 model.
• Token Management Context: The documentation now clarifies how the effort parameter interacts with max_tokens and extended thinking, providing better context for users on the https://platform.claude.com/docs/en/build-with-claude/effort page.

2. What’s UNRESOLVED

The primary issue reported—the total omission of the effort parameter from the Agent SDK specific reference—remains completely unaddressed:

• Python SDK Reference Gap: In the ClaudeAgentOptions documentation at https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions, the dataclass definition and the parameters table still do not include the effort field. While other new fields like max_thinking_tokens and output_format have been added, effort is missing.
• TypeScript SDK Reference Gap: Similarly, at https://platform.claude.com/docs/en/agent-sdk/typescript#options, the Options interface and documentation table fail to list effort as a valid configuration property.
• Lack of Implementation Examples for Agents: The examples provided on the general "Effort" page only show usage for the Anthropic Client SDK (using client.beta.messages.create). There is no guidance or example for how to pass the effort parameter when using the query() function or the ClaudeSDKClient within the Agent SDK.
• Beta Header Ambiguity: It is not documented how an Agent SDK user should provide the mandatory effort-2025-11-24 beta header. It is unclear if users should add this to the betas list in ClaudeAgentOptions or if it is handled internally.

3. Conclusion

I am keeping this issue open.

While the general "Build with Claude" documentation has been updated to include the Effort feature, the Agent SDK reference pages for both Python and TypeScript are technically incomplete. This omission effectively prevents developers from using a core Opus 4.5 feature within the Agent SDK framework. To satisfy this request, the effort property must be added to the parameter tables and dataclass/interface definitions at https://platform.claude.com/docs/en/agent-sdk/python and https://platform.claude.com/docs/en/agent-sdk/typescript.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

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.