The SDK moved, the name stayed

The rename touches the package name, the import path, and (in Python) one class name. Map your old line to the new one and most of your code keeps working.

Current versions at the time of writing: @anthropic-ai/claude-agent-sdk is on 0.3.x, claude-agent-sdk on PyPI is on 0.2.x. The frozen old packages sit at claude-code-sdk 0.0.25 (Python) and @anthropic-ai/claude-code is now the CLI at 2.1.x.

The SDK moved out of @anthropic-ai/claude-code, but that package name stayed alive as the CLI tool, so the install succeeds and the import fails. That mismatch is the single biggest source of confusion in this migration, so it is worth being precise about who owns which name now.

So npm install @anthropic-ai/claude-code does not fail. It installs the CLI. Then your import { query } from "@anthropic-ai/claude-code" fails because that package no longer exports SDK symbols. The error message points at the import, but the real problem is the package you installed.

The rename itself reflects scope. The SDK started as a coding helper and grew into a general framework for building agents — support bots, review agents, finance assistants — so "Agent SDK" describes it better than "Code SDK."

Each error string below maps to one root cause: you are pointing at an old name. Find your exact message, apply the fix.

Most of these collapse to the same move: point the install and the import at the new package name. The last two are not import-rename problems at all — one is an interpreter mismatch, the other is a behavioral default — and they are the ones that survive after the build is green.

Uninstall the old package, install the new one, and rewrite the import string. The symbol names (query, tool, createSdkMcpServer) did not change, so the import is the only edit in most files.

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

Update every import

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

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

If you pinned the dependency, update the key too

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

Uninstall claude-code-sdk, install claude-agent-sdk, then change the import module and the options class name. The constructor arguments are identical, so model, permission_mode, and friends carry over unchanged.

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

Rewrite the import and the class

# Before
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# After
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

python -c "import sys; print(sys.version)"
python -c "import claude_agent_sdk; print(claude_agent_sdk.__file__)"

The default system prompt is gone in v0.1.0 and later, so your agent behaves differently even after the imports compile. This is the one change that fixes your build but silently alters behavior, so it bites people a week after the migration looks done.

Older SDK versions injected Claude Code's CLI-focused system prompt automatically. From v0.1.0 the SDK ships a minimal default. To restore the old behavior, opt into the preset:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Restore the old Claude Code behavior:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

# Restore the old Claude Code behavior:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

Or pass a plain string (systemPrompt: "You are a helpful coding assistant" in TS, system_prompt="..." in Python) to define your own. For deployed agents this is the better default, since you usually don't want CLI-flavored instructions leaking into a support bot.

If your agent leans on tool definitions, the prompt change can shift how tools get selected.

Apply the rename fix when your error is a missing module, a missing export, or a renamed class. Skip ahead to a different fix when the symptom is one of these.

The Claude Agent SDK is the right tool when you want Anthropic's native agent harness. When you want to A/B across providers without rewriting client code, the SDK is the wrong layer — an OpenAI-compatible gateway is the right one.

An OpenAI-compatible gateway exposes one base URL and one key for many models, so you can drive the same tool-use loop against Claude, GPT, Gemini, or whichever model you choose, and swap models with a single string change instead of re-plumbing SDKs:

from openai import OpenAI

# point at any OpenAI-compatible gateway of your choosing
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://your-gateway.example/v1")
resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.8",   # swap this string to change models
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

This does not replace the Agent SDK — it sits alongside it. Use the native harness when you want Anthropic's built-in agent features, MCP support, and the claude_code preset. Use a gateway when provider portability is the goal. The two are not in competition; they answer different questions, and your safety and config controls stay in place regardless of which one you route through.

The honest options, in order of when each is the right call.

Most teams should land on the first or second. The frozen package is a stopgap, not a destination — a dependency that no longer receives fixes is a liability the moment it sits in a production path.

The fix above is one line. The lesson is that the old name still installs something, and that's a design failure you can design around.

You can read this break two ways. The narrow way: update the package name, update the import, move on. The useful way: a dependency whose old name still resolves to a working install — just to the wrong thing — is a class of failure that will cost you a full afternoon the first time you hit it blind.

We see this in nearly every AI stack we audit: a team pins a package by name, the vendor splits or renames, and the install keeps succeeding against a name that no longer means what they think it means. The Claude Code → Agent SDK rename is a clean, documented instance of it. The next one may not ship a migration guide.

When the old name still installs something, the rename isn't done until your behavior is — not your build.