Migrating to the Agent SDK

The library that used to be called the Claude Code SDK is now the Claude Agent SDK. The rename reflects what people actually build with it: plenty of agents built on it never touch code. If you have a project on the old packages, the move is mostly a find-and-replace, plus one behaviour change you need to decide on.

What changed at a glance

The exported functions keep their names. query, tool and createSdkMcpServer all exist in the new package.

TypeScript and JavaScript projects

1. Remove the old package and add the new one:

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

   Copy

2. Update every import. A quick way to find them:

   grep -rl "@anthropic-ai/claude-code" src/
   

   Copy

   Then change the module specifier:

   // old
   import { query, tool } from "@anthropic-ai/claude-code";
   // new
   import { query, tool } from "@anthropic-ai/claude-agent-sdk";
   

   Copy

3. Check package.json. If the old dependency is still listed, replace it and move the version range on too, for example from "^0.0.42" to "^0.3.0". An old range will happily resolve to the last release of the renamed package.

4. Work through the breaking changes below.

Python projects

1. Swap the packages:

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

   Copy

   If pip says WARNING: Skipping claude-code-sdk as it is not installed., the old package was never in this environment. Carry on.

2. Replace claude-code-sdk with claude-agent-sdk in requirements.txt, pyproject.toml or wherever you pin dependencies.

3. Update imports and the options class name:

   # old
   from claude_code_sdk import query, ClaudeCodeOptions
   # new
   from claude_agent_sdk import query, ClaudeAgentOptions
   

   Copy

4. Work through the breaking changes below.

Breaking changes

Version 0.1.0 of the Agent SDK introduced changes aimed at making agents more isolated and their configuration explicit.

ClaudeCodeOptions is now ClaudeAgentOptions (Python)

Same fields, new name. Anywhere you construct options, rename the class:

from claude_agent_sdk import ClaudeAgentOptions

opts = ClaudeAgentOptions(
    model="sonnet",
    permission_mode="acceptEdits",
    max_turns=20,
)

The Claude Code system prompt is no longer the default

Under the old SDK, every query ran with Claude Code's own system prompt: tool guidance, coding conventions, safety instructions and so on. The Agent SDK starts from a minimal prompt instead, so an agent that suddenly feels less "Claude Code like" after the upgrade is usually missing this.

You have two choices.

Restore the old behaviour by asking for the preset:

const run = query({
  prompt: "Summarise the open pull requests",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
  },
});

options = ClaudeAgentOptions(
    system_prompt={"type": "preset", "preset": "claude_code"},
)

Or write your own prompt as a plain string, which is often the better fit for agents that are not coding assistants:

options = ClaudeAgentOptions(
    system_prompt="You triage inbound support emails for a UK accounting firm. Be brief.",
)

You can also keep the preset and add to it with an append field. Modifying system prompts compares all the approaches.

Filesystem settings: no action needed

For a short while in v0.1.0, the SDK stopped loading filesystem settings by default. That was reverted. Today, if you leave settingSources (Python: setting_sources) unset, the SDK loads user, project and local settings just as the CLI does: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md files and custom commands.

To run with none of that, pass an empty list:

options: { settingSources: [] }

ClaudeAgentOptions(setting_sources=[])

I do this for anything deployed: CI jobs, hosted services, test suites and multi-tenant systems. You do not want a developer's personal ~/.claude settings quietly changing what a production agent can do.

Warning: In Python SDK 0.1.59 and earlier, setting_sources=[] behaved the same as leaving the option out, so it still loaded everything. Upgrade before relying on it. Some inputs are read even with an empty list; Claude Code features in the SDK lists them.

Coming from the OpenAI Agents SDK

If you are migrating from a different framework rather than from the old package, the ideas map across fairly directly: agents become query() calls with options, function tools become custom tools, handoffs become subagents, and guardrails become hooks or permission rules. Anthropic publishes a cookbook recipe that walks through one example end to end.

A migration checklist

• Old package uninstalled, new package installed and pinned
• All imports updated (grep for the old names returns nothing)
• ClaudeCodeOptions renamed in Python
• Decision made on system prompt: preset, custom string or preset with append
• settingSources set explicitly for deployed agents
• Tests run against a real query to confirm behaviour has not shifted

Related

• Agent SDK overview
• Modifying system prompts
• Claude Code features in the SDK
• TypeScript SDK reference
• Python SDK reference