Migrate to Claude Agent SDK

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	Claude Code docs → dedicated Agent SDK section

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": "^0.0.42"
  }
}

After:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.3.0"
  }
}

5. Review breaking changes Make any code changes needed to complete the migration.

For Python Projects

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())

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 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 an empty array:

import { query } from "@anthropic-ai/claude-agent-sdk";

const isolatedResult = query({
  prompt: "Hello",
  options: {
    settingSources: [] // No filesystem settings loaded
  }
});

// Or load only specific sources:
const projectOnlyResult = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // Only project settings
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(setting_sources=[]),  # No filesystem settings loaded
    ):
        print(message)

    # Or load only specific sources:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only project settings
        ),
    ):
        print(message)


asyncio.run(main())

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

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Overview

What’s Changed

Migration Steps

For TypeScript/JavaScript Projects

For Python Projects

Breaking changes

Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

System prompt no longer default

Settings sources default

Next Steps

​Overview

​What’s Changed

​Migration Steps

​For TypeScript/JavaScript Projects

​For Python Projects

​Breaking changes

​Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

​System prompt no longer default

​Settings sources default

​Next Steps

Overview

What’s Changed

Migration Steps

For TypeScript/JavaScript Projects

For Python Projects

Breaking changes

Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

System prompt no longer default

Settings sources default

Next Steps