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 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
npm install @anthropic-ai/claude-agent-sdk
@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";
package.json, update it:
Before:
{
"dependencies": {
"@anthropic-ai/claude-code": "^0.0.42"
}
}
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
For Python Projects
1. Uninstall the old package:pip uninstall claude-code-sdk
pip install claude-agent-sdk
claude_code_sdk to claude_agent_sdk:
# Before
from claude_code_sdk import query, ClaudeCodeOptions
# After
from claude_agent_sdk import query, ClaudeAgentOptions
ClaudeCodeOptions to ClaudeAgentOptions:
# 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
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 typeClaudeCodeOptions 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"
}
});
Settings sources default
This default was briefly changed in v0.1.0 and then reverted, so no migration action is needed. Current behavior: OmittingsettingSources 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
}
});
SDK v0.1.0 briefly defaulted to no settings loaded; this was reverted in subsequent releases. 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 [].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:- Check that all imports are updated to use
@anthropic-ai/claude-agent-sdk - Verify your package.json has the new package name
- Run
npm installto ensure dependencies are updated
- Check that all imports are updated to use
claude_agent_sdk - Verify your requirements.txt or pyproject.toml has the new package name
- Run
pip install claude-agent-sdkto ensure the package is installed
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