# 2860 Agent Sdk Migration Guide 04cce82e > Overview - Skill: `tools-only/2860-agent-sdk-migration-guide-04cce82e` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/2860-agent-sdk-migration-guide-04cce82e` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2860-agent-sdk-migration-guide-04cce82e/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/2860-agent-sdk-migration-guide-04cce82e --- ## 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 just coding tasks. ## 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 | API Guide → Agent SDK section | **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features. ## Migration Steps ### For TypeScript/JavaScript Projects **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 dependencies:** If you have the package listed in your `package.json`, update it: // Before { "dependencies": { "@anthropic-ai/claude-code": "^1.0.0" } } // After { "dependencies": { "@anthropic-ai/claude-agent-sdk": "^0.1.0" } } That's it! No other code changes are required. ### For Python Projects **1. Uninstall the old package:** pip uninstall claude-code-sdk **2. Install the new package:** pip install 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. Update type names:** Change `ClaudeCodeOptions` to `ClaudeAgentOptions`: # Before from claude_agent_sdk import query, ClaudeCodeOptions options = ClaudeCodeOptions( model="claude-sonnet-4-5" ) # After from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions( model="claude-sonnet-4-5" ) **5. Review [breaking changes](https://platform.claude.com/docs/en/agent-sdk/migration-guide#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. Review this section carefully before migrating. ### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions **What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`. **Migration:** # BEFORE (v0.0.x) from claude_agent_sdk import query, ClaudeCodeOptions options = ClaudeCodeOptions( model="claude-sonnet-4-5", permission_mode="acceptEdits" ) # AFTER (v0.1.0) from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions( model="claude-sonnet-4-5", permission_mode="acceptEdits" ) **Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions. ### System prompt no longer default **What changed:** The SDK no longer uses Claude Code's system prompt by default. **Migration:** // BEFORE (v0.0.x) - Used Claude Code's system prompt by default const result = query({ prompt: "Hello" }); // AFTER (v0.1.0) - Uses empty system prompt by default // To get the old behavior, explicitly request Claude Code's preset: const result = query({ prompt: "Hello", options: { systemPrompt: { type: "preset", preset: "claude_code" } } }); // Or use a custom system prompt: const result = query({ prompt: "Hello", options: { systemPrompt: "You are a helpful coding assistant" } }); **Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions. ### Settings Sources No Longer Loaded by Default **What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default. **Migration:** // BEFORE (v0.0.x) - Loaded all settings automatically const result = query({ prompt: "Hello" }); // Would read from: // - ~/.claude/settings.json (user) // - .claude/settings.json (project) // - .claude/settings.local.json (local) // - CLAUDE.md files // - Custom slash commands // AFTER (v0.1.0) - No settings loaded by default // To get the old behavior: const result = query({ prompt: "Hello", options: { settingSources: ["user", "project", "local"] } }); // Or load only specific sources: const result = query({ prompt: "Hello", options: { settingSources: ["project"] // Only project settings } }); **Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for: - **CI/CD environments** - Consistent behavior without local customizations - **Deployed applications** - No dependency on filesystem settings - **Testing** - Isolated test environments - **Multi-tenant systems** - Prevent settings leakage between users **Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options. ## Why the Rename? The Claude Code SDK was originally designed for coding tasks, but it has evolved into a powerful framework for building all types of AI agents. The new name "Claude Agent SDK" better reflects its capabilities: - Building business agents (legal assistants, finance advisors, customer support) - Creating specialized coding agents (SRE bots, security reviewers, code review agents) - Developing custom agents for any domain with tool use, MCP integration, and more ## Getting Help If you encounter any issues during migration: **For TypeScript/JavaScript:** 1. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk` 2. Verify your package.json has the new package name 3. Run `npm install` to ensure dependencies are updated **For Python:** 1. Check that all imports are updated to use `claude_agent_sdk` 2. Verify your requirements.txt or pyproject.toml has the new package name 3. Run `pip install claude-agent-sdk` to ensure the package is installed ## Next Steps - Explore the [Agent SDK Overview](https://platform.claude.com/docs/en/agent-sdk/overview) to learn about available features - Check out the [TypeScript SDK Reference](https://platform.claude.com/docs/en/agent-sdk/typescript) for detailed API documentation - Review the [Python SDK Reference](https://platform.claude.com/docs/en/agent-sdk/python) for Python-specific documentation - Learn about [Custom Tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools) and [MCP Integration](https://platform.claude.com/docs/en/agent-sdk/mcp)