[DOCS] Inconsistent and ambiguous instructions for `system_prompt` presets in Python SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

• platform_claude_com_docs-part1.md - Relevant Files: docs/en/agent-sdk/python.md and docs/en/agent-sdk/migration-guide.md

Section/Topic

• Python SDK Reference -> ClaudeAgentOptions -> system_prompt property.

Current Documentation

In python.md under ClaudeAgentOptions:

system_prompt: str | SystemPromptPreset | None = None. System prompt configuration. Pass a string for custom prompt, or use {"type": "preset", "preset": "claude_code"} for Claude Code's system prompt.

In migration-guide.md:

``python # AFTER (v0.1.0) - Uses minimal system prompt by default # To get the old behavior, explicitly request Claude Code's preset: from claude_agent_sdk import query, ClaudeAgentOptions async for message in query( prompt="Hello", options=ClaudeAgentOptions( system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset ) ): print(message) ``

What's Wrong or Missing?

The documentation is confusing regarding whether "claude_code" can be passed as a string alias. In many other parts of the SDK (like the model parameter), strings act as aliases (e.g., "sonnet", "haiku").

Because the system_prompt type definition accepts str, if a user passes system_prompt="claude_code", the SDK will treat the literal string "claude_code" as the system instructions. This results in the agent having no functional instructions other than that single string, causing it to fail or behave unexpectedly. The documentation states strings are for "custom prompts" but does not explicitly warn that the preset must be the dictionary object to function.

Suggested Improvement

Clarify in python.md that the string "claude_code" is not a valid alias and that the SystemPromptPreset object is required to trigger preset logic.

Suggested Text for python.md Table:

system_prompt: str | SystemPromptPreset | None. - Pass a string to set the literal text of a custom prompt. - Use the SystemPromptPreset dictionary {"type": "preset", "preset": "claude_code"} to load the Claude Code default instructions. - Note: Passing the string "claude_code" will be treated as custom text and will not load the preset.

Impact

High - Prevents users from using a feature

Additional Context

• This is a common pitfall for Python developers who expect string-based aliases for configuration (similar to how model="sonnet" works).
• The TypeScript documentation is slightly clearer due to Zod types, but the Python docstrings need this explicit distinction to prevent "empty brain" agents.