[DOCS] Migration Guide "BEFORE" code imports from wrong package name

Resolved 💬 2 comments Opened Jan 24, 2026 by coygeek Closed Feb 27, 2026

Documentation Type

Unclear/confusing documentation

Documentation Location

https://docs.anthropic.com/en/docs/agent-sdk/migration-guide

Section/Topic

Section: "Python: ClaudeCodeOptions renamed to ClaudeAgentOptions" (under Breaking changes)

Current Documentation

The "BEFORE (v0.0.x)" code snippets show:

# BEFORE (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

This appears twice in the migration guide:

  1. In "Update type names" (step 4)
  2. In "ClaudeCodeOptions renamed to ClaudeAgentOptions" (breaking changes section)

What's Wrong or Missing?

The "BEFORE" code is supposed to illustrate how code looked in the old version (v0.0.x), but it imports from the new package name (claude_agent_sdk) instead of the old package name (claude_code_sdk).

This directly contradicts step 3 in the same guide, which correctly shows:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

Users following this guide would be confused because:

  1. The "BEFORE" code doesn't match what their old code actually looks like
  2. It implies the old SDK already used the new package name

Suggested Improvement

Change the import in both "BEFORE" snippets to use the old package name:

# BEFORE (v0.0.x)
from claude_code_sdk import query, ClaudeCodeOptions

This correctly shows what users' code looked like before migration, making the contrast with the "AFTER" snippet clear.

Impact

High - Prevents users from using a feature

Additional Context

  • Impact: Medium - Makes migration instructions internally contradictory
  • The fix is consistent with the correct example already shown in step 3 of the Python migration steps

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗