[DOCS] Python SDK overview example incorrectly accesses session_id on SystemMessage

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Sessions" tab under "Capabilities" section - Python code example for capturing session ID

Current Documentation

The Python example shows:

# First query: capture the session ID
async for message in query(
prompt="Read the authentication module",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
):
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.session_id  # <-- ERROR

What's Wrong or Missing?

The code accesses message.session_id directly on a SystemMessage, but SystemMessage does not have a session_id attribute. The session_id is stored inside the data dictionary.

SDK Evidence:

# From claude_agent_sdk/types.py - SystemMessage class
@dataclass
class SystemMessage:
"""System message with metadata."""

subtype: str
data: dict[str, Any]  # session_id is inside here, not a direct attribute


# In contrast, ResultMessage DOES have session_id directly:
@dataclass
class ResultMessage:
"""Result message with cost and usage information."""

subtype: str
duration_ms: int
duration_api_ms: int
is_error: bool
num_turns: int
session_id: str  # Direct attribute
# ...

Note: The sessions.md documentation correctly shows the proper access pattern:

# From sessions.md - CORRECT pattern
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')  # Access via data dict

Suggested Improvement

Update the Python example to use the correct access pattern:

# First query: capture the session ID
async for message in query(
prompt="Read the authentication module",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
):
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')  # Correct: access via data dict

This matches the pattern shown in sessions.md and aligns with the SDK's actual class structure.

Impact

High - Prevents users from using a feature

Additional Context

Verification Method: Cross-referenced against Python Agent SDK source code (claude-agent-sdk-python)
SDK Files:

• types.py - SystemMessage and ResultMessage class definitions

Related: The sessions.md documentation at https://platform.claude.com/docs/en/agent-sdk/sessions correctly shows message.data.get('session_id') for init messages.