Claude Agent SDK Migration: Package Renames and Breaking Changes (2026)

The Claude Code SDK has been renamed to the Claude Agent SDK. Migrating is three mechanical edits plus two behavioral changes you have to opt back into: rename the package, rename the imports, rename ClaudeCodeOptions to ClaudeAgentOptions, then decide whether you want the old Claude Code system prompt and filesystem settings back. The breaking changes landed in v0.1.0. Everything below is taken from Anthropic’s official Agent SDK migration guide and the live package registries, verified June 13, 2026.

The renames at a glance

Two packages and one Python type changed names. The documentation also moved out of the Claude Code docs into the API Guide’s Agent SDK section.

Current published versions

These are the latest versions on the public registries as fetched on June 13, 2026. The migration guide itself uses ^0.0.42 as the example old TypeScript version and ^0.2.0 as the example new one; pin to whatever is current when you install.

TypeScript migration

Swap the package, then update every import. The exported names (query, tool, createSdkMcpServer) are unchanged — only the module specifier moves.

npm uninstall @anthropic-ai/claude-code
npm install @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";

Update package.json as well, replacing the dependency key from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk.

Python migration

Swap the package, update the import path, and rename the options type. The import name changes from underscore-claude_code_sdk to underscore-claude_agent_sdk.

pip uninstall claude-code-sdk
pip install claude-agent-sdk

# 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")

The rename is the only change to the type — its fields and constructor signature are otherwise the same. Per Anthropic, the new name matches the “Claude Agent SDK” branding.

Breaking change: the system prompt is no longer default

This is the change most likely to silently alter your agent’s behavior. In v0.0.x, the SDK used Claude Code’s system prompt by default. As of v0.1.0, query() uses a minimal system prompt instead. To get the old behavior, explicitly request the claude_code preset.

// TypeScript — restore the old default
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Or a custom system prompt:
const custom = query({
  prompt: "Hello",
  options: { systemPrompt: "You are a helpful coding assistant" }
});

# Python — restore the old default
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

# Or a custom system prompt:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
    print(message)

settingSources: changed, then reverted

This one is widely mis-reported, so read it carefully. v0.1.0 briefly defaulted to loading no filesystem settings — and that default was reverted in subsequent releases. Anthropic’s current guidance is that no migration action is needed for setting sources.

Current behavior: omitting settingSources on query() loads user, project, and local filesystem settings, matching the CLI — equivalent to ["user", "project", "local"]. That includes ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md files, and custom commands. The accepted values are below.

To run isolated from filesystem settings, pass an empty array. This matters for CI/CD, deployed apps, test environments, and multi-tenant systems where local customizations should not leak in.

// TypeScript — no filesystem settings
const isolated = query({
  prompt: "Hello",
  options: { settingSources: [] }
});

// Only project settings
const projectOnly = query({
  prompt: "Hello",
  options: { settingSources: ["project"] }
});

# Python — no filesystem settings
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(setting_sources=[]),
):
    print(message)

Two caveats Anthropic documents explicitly. First, Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option — upgrade before relying on setting_sources=[]. Second, some inputs are read regardless of settingSources: managed policy settings, the global ~/.claude.json config, auto-memory, and claude.ai MCP connectors. For true multi-tenant isolation, the docs recommend running each tenant in its own filesystem and setting settingSources: [] plus CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

The full checklist

Work top to bottom; the first three are required, the last two are behavioral decisions.