Text of code.claude.com › docs › en › agent-sdk › migration-guide as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Migrate to Claude Agent SDK - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Overview The Claude Code SDK has been renamed to the Claude Agent SDK and its documentation has been reorganized. This change reflects the SDK’s broader capabilities for building AI agents beyond coding tasks.

Migrating from the OpenAI Agents SDK instead? The OpenAI Agents SDK migration recipe maps each primitive onto the Claude Agent SDK through a single worked example. What’s Changed Aspect Old New Package Name (TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk Python Package claude-code-sdk claude-agent-sdk Documentation Location Claude Code docs Claude Code docs → dedicated Agent SDK section Migration Steps Migrate a TypeScript or JavaScript project 1.

Uninstall the old package: npm uninstall @anthropic-ai/claude-code 2. Install the new package: npm install @anthropic-ai/claude-agent-sdk 3. Update your imports: Change all imports from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk : // Before import { query , tool , createSdkMcpServer } from "@anthropic-ai/claude-code" ; // After import { query , tool , createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk" ; 4.

Update package.json: If @anthropic-ai/claude-code is still listed in your package.json , replace it with @anthropic-ai/claude-agent-sdk and update the version range as well, for example from "^0.0.42" to "^0.3.0" . 5. Review breaking changes Make any code changes needed to complete the migration. Migrate a Python project 1. Uninstall the old package: pip uninstall -y claude-code-sdk If the old package isn’t installed, pip prints WARNING: Skipping claude-code-sdk as it is not installed.

That’s expected and you can continue to the next step. 2. Install the new package: pip install claude-agent-sdk If claude-code-sdk is listed in your requirements.txt or pyproject.toml , replace it with claude-agent-sdk . 3. Update your imports: Change all imports from claude_code_sdk to claude_agent_sdk : # Before from claude_code_sdk import query, ClaudeCodeOptions # After from claude_agent_sdk import query, ClaudeAgentOptions 4.

Review breaking changes Make any code changes needed to complete the migration. Breaking changes To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK. Python: ClaudeCodeOptions renamed to ClaudeAgentOptions What changed: The Python SDK type ClaudeCodeOptions has been renamed to ClaudeAgentOptions . Migration: # BEFORE (claude-code-sdk) from claude_code_sdk import query, ClaudeCodeOptions options = ClaudeCodeOptions( model = "claude-opus-4-7" , permission_mode = "acceptEdits" ) # AFTER (claude-agent-sdk) from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions( model = "claude-opus-4-7" , permission_mode = "acceptEdits" ) System prompt no longer default What changed: The SDK no longer uses Claude Code’s system prompt by default.

Migration: import { query } from "@anthropic-ai/claude-agent-sdk" ; // BEFORE (v0.0.x) - Used Claude Code's system prompt by default const before = query ({ prompt: "Hello" }); // AFTER (v0.1.0) - Uses minimal system prompt by default // To get the old behavior, explicitly request Claude Code's preset: const presetResult = query ({ prompt: "Hello" , options: { systemPrompt: { type: "preset" , preset: "claude_code" } } }); // Or use a custom system prompt: const customResult = query ({ prompt: "Hello" , options: { systemPrompt: "You are a helpful coding assistant" } }); from claude_agent_sdk import query, ClaudeAgentOptions import asyncio async def main (): # BEFORE (v0.0.x) - Used Claude Code's system prompt by default async for message in query( prompt = "Hello" ): print (message) # AFTER (v0.1.0) - Uses minimal system prompt by default # To get the old behavior, explicitly request Claude Code's preset: async for message in query( prompt = "Hello" , options = ClaudeAgentOptions( system_prompt = { "type" : "preset" , "preset" : "claude_code" } # Use the preset ), ): print (message) # Or use a custom system prompt: async for message in query( prompt = "Hello" , options = ClaudeAgentOptions( system_prompt = "You are a helpful coding assistant" ), ): print (message) asyncio.run(main()) Settings sources default This default was briefly changed in v0.1.0 to load no filesystem settings and then reverted, so no migration action is needed.

Current behavior: Omitting settingSources on query() loads user, project, and local filesystem settings, matching the CLI. This includes ~/.claude/settings.json , .claude/settings.json , .claude/settings.local.json , CLAUDE.md files, and custom commands. To run isolated from filesystem settings, pass settingSources: [] , or setting_sources=[] in Python. See Control filesystem settings with settingSources for what each source loads.

Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on setting_sources=[] . See What settingSources does not control for inputs that are read even when settingSources is [] . Next Steps Explore the Agent SDK Overview to learn about available features Check out the TypeScript SDK Reference for detailed API documentation Review the Python SDK Reference for Python-specific documentation Learn about Custom Tools and MCP Integration Was this page helpful?