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

Last verified: June 13, 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.

Aspect

Old

New

Package (TS/JS)

@anthropic-ai/claude-code

@anthropic-ai/claude-agent-sdk

Package (Python)

claude-code-sdk

claude-agent-sdk

Python import

claude_code_sdk

claude_agent_sdk

Python options type

ClaudeCodeOptions

ClaudeAgentOptions

Docs location

Claude Code docs

API Guide → Agent SDK

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.

Registry

Package

Latest version

npm

@anthropic-ai/claude-agent-sdk

0.3.177

PyPI

claude-agent-sdk

0.2.101

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.

Goal

systemPrompt value

Restore Claude Code’s prompt

{ type: "preset", preset: "claude_code" }

Use your own instructions

a plain string

Minimal prompt (new default)

omit the option

// 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.

Source

Loads from

"user"

~/.claude/ — user CLAUDE.md, rules, skills, settings

"project"

<cwd>/.claude/ — project CLAUDE.md, rules, skills, hooks, settings.json

"local"

CLAUDE.local.md and .claude/settings.local.json

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.

Step

Action

1

Uninstall old package, install @anthropic-ai/claude-agent-sdk / claude-agent-sdk

2

Update all imports to the new module / package name

3

Python only: rename ClaudeCodeOptions → ClaudeAgentOptions

4

If you relied on Claude Code’s prompt, set systemPrompt to the claude_code preset

5

Decide on settingSources: omit for CLI parity, or [] to isolate

Do I have to change settingSources when I migrate?

No. Anthropic states no migration action is needed for setting sources. The v0.1.0 change to “load nothing by default” was reverted; omitting settingSources again loads user, project, and local settings, matching the CLI.

What is the new default system prompt?

A minimal system prompt. Before v0.1.0 the SDK inherited Claude Code’s full system prompt by default. To restore it, pass systemPrompt as { type: "preset", preset: "claude_code" } (TypeScript) or system_prompt={"type": "preset", "preset": "claude_code"} (Python).

Did the exported function names change in TypeScript?

No. query, tool, and createSdkMcpServer are unchanged. Only the import path moves from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk.

Which version introduced the breaking changes?

Claude Agent SDK v0.1.0, introduced “to improve isolation and explicit configuration,” per the official guide. The latest published versions as of June 13, 2026 are 0.3.177 on npm and 0.2.101 on PyPI.

Does settingSources: [] fully isolate my agent?

Not by itself. Managed policy settings, the global ~/.claude.json config, auto-memory, and claude.ai MCP connectors are read regardless. For multi-tenant isolation, also run each tenant in its own filesystem and set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.