Migrate to Claude Agent SDK

The Claude Code SDK has been renamed to the Claude Agent SDK. The rename reflects broader capabilities beyond coding tasks — any domain agent, business automation, etc.

Package Name Changes

	TypeScript/JS	Python
Old	`@anthropic-ai/claude-code`	`claude-code-sdk`
New	`@anthropic-ai/claude-agent-sdk`	`claude-agent-sdk`
Import module	`@anthropic-ai/claude-agent-sdk`	`claude_agent_sdk`

Documentation moved from Claude Code docs → API Guide → Agent SDK section.

Migration Steps

TypeScript / JavaScript

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

Update all imports:

// Before
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// After
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

Update package.json:

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

No other code changes needed (unless you hit breaking changes below).

Python

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

Update imports and the renamed type:

# Before
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")

# After
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")

Breaking Changes (v0.1.0)

1. `ClaudeCodeOptions` → `ClaudeAgentOptions` (Python only)

Rename the type everywhere. No behavioral difference.

2. System Prompt No Longer Defaulted (v0.1.0)

SDK now uses a minimal system prompt instead of Claude Code's CLI prompt.

// To restore old behavior:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

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

3. Settings Sources No Longer Loaded by Default (v0.1.0)

SDK no longer reads CLAUDE.md, settings.json, slash commands, etc. by default.

// To restore old behavior:
const result = query({
  prompt: "Hello",
  options: { settingSources: ["user", "project", "local"] }
});

// For isolated behavior (CI/CD, multi-tenant):
const result = query({
  prompt: "Hello",
  options: { settingSources: [] }
});

Note: Current releases have reverted this default for query() — omitting settingSources once again loads user/project/local settings (matching CLI behavior). Pass settingSources: [] explicitly if your app needs isolation. Python SDK ≤ 0.1.59 treats [] the same as omitting — upgrade before relying on empty list isolation.

Why the Rename?

The SDK outgrew its "coding only" origins. Current use cases:

Business agents: legal assistants, finance advisors, customer support
Specialized coding agents: SRE bots, security reviewers, code review agents
Custom domain agents with full tool use and MCP integration

Key Takeaways

Only rename needed for most projects — no logic changes required, just swap package name and update imports
Python extra step — rename ClaudeCodeOptions → ClaudeAgentOptions
v0.1.0 breaking changes around system prompt and settings sources were partially reverted; current query() loads settings by default again
To opt into isolation (CI/CD, multi-tenant): pass settingSources: [] — requires Python SDK > 0.1.59
Docs moved to API Guide → Agent SDK section

Sources

raw/Migrate to Claude Agent SDK.md

4.2 KiB Raw Blame History