Claude Agent SDK Migration Playbook: From Claude Code SDK

The Claude Agent SDK is the same SDK you have been using as the Claude Code SDK, with a new name and a small set of breaking changes that landed in v0.1.0. Anthropic announced the rename on September 29, 2025, reflecting that the SDK has grown well beyond coding tasks — teams are building legal assistants, finance advisors, SRE bots, and security reviewers on top of the same primitives.

The mechanical migration is a package rename on npm and PyPI plus an imports sweep. The substantive migration is the v0.1.0 behavior change: the SDK no longer uses Claude Code's system prompt by default. If your agent relied on Claude Code's preset instructions for tool-use behavior or file-system search, you need to either explicitly opt back into the preset or write a custom system prompt before merging.

This playbook covers what changed, the TypeScript and Python migration steps, the system-prompt default change in detail, the settings-sources behavior that briefly flipped and then reverted, and the audit-then-cut pattern we ship for client repos. Everything below is grounded in the official Claude Agent SDK migration guide.

The Claude Code SDK was originally designed to power the Claude Code CLI — file-system access, semantic search, subagents, tool use, bash execution, code generation, MCP integration, context compaction. Those primitives turned out to be general-purpose. The SDK now ships production agents for business workflows (legal assistants, finance advisors, customer support) and specialized coding agents (SRE bots, security reviewers, code review agents) alongside the original coding use case.

The rename is the cleanest signal of that shift. Three concrete changes follow from it:

• Package names. npm: @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk. PyPI: claude-code-sdk → claude-agent-sdk. The old packages remain installable for older versions but the new development happens on the new packages.
• Documentation. The SDK docs moved from the Claude Code section into a dedicated Agent SDK guide. The Claude Code docs now focus on the CLI tool and its automation features; the SDK docs cover the library API.
• System prompt default. The SDK no longer ships with the Claude Code system prompt active by default. v0.1.0 switched to a minimal default — explicit preset opt-in or custom prompt required. This is the only behavioral breaking change.

The mechanical migration is identical for TypeScript and Python in shape: uninstall the old package, install the new package, update every import. The only Python-specific extra step is the ClaudeCodeOptions → ClaudeAgentOptions rename inside the migrated imports.

TypeScript / JavaScript steps, from the official guide:

1. npm uninstall @anthropic-ai/claude-code
2. npm install @anthropic-ai/claude-agent-sdk
3. Update every import …from "@anthropic-ai/claude-code" to import …from "@anthropic-ai/claude-agent-sdk". The exported names (query, tool, createSdkMcpServer, and the rest) stayed the same — only the source module changed.
4. Update package.json dependency entry. If your project version-pins the old package, bump the pinned version (the new package follows independent semver — current is ^0.3.x on npm).

Python steps:

1. pip uninstall claude-code-sdk
2. pip install claude-agent-sdk
3. Update imports — from claude_code_sdk import … → from claude_agent_sdk import …. Note the module name uses underscores (PEP 8), not hyphens.
4. Rename ClaudeCodeOptions to ClaudeAgentOptions at every construction site. Fields and semantics are unchanged — this is a pure type rename.

The exports are otherwise stable across the rename. A team that mostly uses query() with a string prompt will finish the mechanical migration in under ten minutes; a team that constructs ClaudeCodeOptions objects in a dozen locations will spend more time on the type rename than on the package swap.

One operational note: if your repo is a workspace (Turborepo, pnpm workspaces, Nx, Lerna), the package rename has to be applied at every workspace package that depends on the SDK, not just the root. A lazy migration that only updates the application package and leaves a shared utilities package on the old name compiles cleanly but ends up with both packages installed in node_modules — you carry two copies of the SDK indefinitely until the workspace lockfile is regenerated. Run a full npm dedupe / pnpm dedupe after the rename to confirm.

This is the migration step that decides whether the upgrade is a silent regression or a clean cutover. In Claude Code SDK v0.0.x, calling query()without specifying a system prompt used Claude Code's built-in preset — the same instructions that shape behavior inside the Claude Code CLI: file-system search defaults, code-edit framing, tool-use heuristics, output conventions. In Claude Agent SDK v0.1.0, the default became a minimal system prompt instead.

Per the official migration guide, the rationale is "better control and isolation for SDK applications" — building a legal assistant or finance advisor on top of an SDK that quietly injects coding-assistant instructions was the wrong default. Teams that built coding agents on the SDK relied on the old default and now need an explicit opt-in.

The migration choice is a one-line addition at every query() call. Pick one of three patterns based on what your agent actually does:

The Pattern A opt-in is the safest first move for any team that did not previously specify a system prompt. It restores the exact v0.0.x behavior at the cost of three extra lines per call-site. From there, you can iteratively move call-sites to Pattern B as you write domain-appropriate prompts, or to Pattern C as you discover that individual call-sites work fine on the minimal default.

Where this bites: an agent that worked well in v0.0.x because of a tool-use heuristic baked into the Claude Code preset will appear to regress on tool-call accuracy after the rename. The model is the same, the temperature is the same, the tools are the same — only the system prompt is different. The fix is mechanical (Pattern A), but the diagnosis is not obvious if the only thing you remember changing is the package name.

The fourth axis is mostly documentary — a behavior change that shipped in v0.1.0 and was reverted in subsequent releases. The current behavior matches the Claude Code CLI: omitting settingSources on the query() options loads user, project, and local filesystem settings. That includes files like ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, CLAUDE.md files, and custom commands.

For isolated execution — CI/CD pipelines, deployed applications, test environments, multi-tenant systems where filesystem state should not leak in — pass settingSources: [] explicitly:

Two operational notes worth flagging before you assume the empty array does what you think it does:

• Python SDK 0.1.59 and earlier treated setting_sources=[] the same as omitting the option — both fell back to the permissive default. Upgrade past 0.1.59 before relying on empty-list-as-isolated.
• Not everything is gated by settingSources. Some inputs are read even when settingSources is []. The Claude Code Features doc lists the inputs that bypass the isolation flag — check it before assuming a hermetic CI build.

For most teams this axis is no-action — the default behavior is what you want, the empty-array isolation is what you want for CI, and nothing else changes. The reason it appears in the migration guide at all is that the briefly-shipped flip in v0.1.0 generated confusion that the docs are still cleaning up.

Unlike a four-axis SDK overhaul, the Claude Code → Claude Agent SDK migration is small enough to ship in a single PR for most teams. The phasing exists less to manage blast radius and more to enforce that the behavioral audit actually happens — the failure mode is the audit being skipped, not a particular axis going wrong.

Four phases, in order:

• Phase 1 — Rename. Uninstall the old package, install the new package, sweep imports, bump package.json/pyproject.toml. For Python, rename ClaudeCodeOptions → ClaudeAgentOptions. For workspaces, apply the rename at every package that depends on the SDK and run dedupe. Total time: ten minutes to half an hour.
• Phase 2 — Audit. Run your eval suite against the renamed code without changing the system prompt or settings sources. Compare results to the v0.0.x baseline. If passing, ship. If regressing, identify the regression class (tool-call accuracy, code-edit shape, file-search behavior) and opt back into the Claude Code preset (Pattern A above) for the affected call-sites.
• Phase 3 — Ship. Single PR: package rename + any Pattern A opt-ins needed to hold v0.0.x baseline. Merge, deploy, watch traces for 24 hours. The 24-hour window catches edge cases the eval suite missed.
• Phase 4 — Tune.Once the rename is stable, move individual call-sites from Pattern A toward Pattern B or C as workflow-appropriate. Custom prompts produce more predictable behavior than Claude Code's coding-assistant preset for non-coding agents — but only if you take the time to write them. This phase is iterative and never strictly "done".

For teams that prefer outside execution on the migration itself — including the audit, the Pattern A opt-ins, and the iterative prompt tuning — our AI transformation engagements run this end-to-end with a published rollback procedure for the first 24 hours after deploy. The same approach applies to model migrations on the API surface — we keep an active playbook for the Claude Opus 4.6 to 4.7 migration, which sits one layer above the SDK migration covered here.

None of the failure modes below is exotic; each is preventable with the audit-then-cut pattern above. Naming them up front saves a Friday evening.

1. Skipping the behavioral audit. Team renames the package, the imports compile, the unit tests pass, ship. Three days later traces show tool-call accuracy regressing on the same prompts that worked in v0.0.x. Diagnosis: the Claude Code system prompt was load-bearing and the minimal default is changing behavior. Fix: opt back into the preset (Pattern A) for the affected call-sites. Prevention: run the eval suite before merging, not after deploying.
2. Workspace dependency drift. Monorepo team renames the package at the root and the application package but forgets a shared utilities package that also depends on the SDK. Both packages get installed in node_modules; the app loads the new one, the utilities load the old one, and the two versions disagree on a small API detail. Fix: apply the rename at every workspace package and run pnpm dedupe / npm dedupe after.
3. Python options rename missed. Python team renames the package and imports cleanly but leaves ClaudeCodeOptions(…) construction sites unchanged. The module no longer exports ClaudeCodeOptions so import-time fails — but the team only catches it when the specific code path is exercised, sometimes hours after the deploy. Fix: grep for ClaudeCodeOptions as a separate sweep, renaming all of them at once.
4. Empty-list isolation false confidence. Team passes settingSources: []in CI on Python SDK 0.1.59 and assumes a hermetic build. The empty list was treated as identical to omitting until 0.1.60, so the build actually loads user/project/local settings — including a developer's local overrides that leaked into the CI image. Fix: upgrade past 0.1.59 before relying on empty-list isolation, and verify against the Claude Code Features doc for inputs that bypass settingSources regardless.

The unifying theme is that the rename is mechanical and the behavior change is silent. The mechanical work creates a false sense of progress — the imports compile, the tests pass — that masks the behavioral audit that is the actual migration. The audit-then-cut phasing exists to surface the silent change before it ships, not to manage blast radius on the package swap itself.

If the migration unlocks a deeper refactor — moving call-sites from the Claude Code preset to custom domain-specific prompts, or building specialized subagents on top of the cleaned-up SDK surface — the Claude Code custom subagent walkthrough picks up where this playbook leaves off.