SpyBara
Go Premium

agent-sdk/migration-guide.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

295 added, 0 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Migrate to Claude Agent SDK

Guide for migrating the Claude Code TypeScript and Python SDKs to the 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 API Guide → 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.2.0"
  }
}

5. Review breaking changes

Make any code changes needed to complete the migration.

For Python Projects

1. Uninstall the old package:

pip uninstall claude-code-sdk

2. Install the new package:

pip install 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. Update type names:

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

5. Review breaking changes

Make any code changes needed to complete the migration.

Breaking changes

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

Why this changed: The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.

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"
}
});

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 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
}
});

Isolation is especially important for CI/CD pipelines, deployed applications, test environments, and multi-tenant systems where local customizations should not leak in.

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:

  1. Check that all imports are updated to use @anthropic-ai/claude-agent-sdk
  2. Verify your package.json has the new package name
  3. Run npm install to ensure dependencies are updated

For Python:

  1. Check that all imports are updated to use claude_agent_sdk
  2. Verify your requirements.txt or pyproject.toml has the new package name
  3. Run pip install claude-agent-sdk to ensure the package is installed

Next Steps