---
title: "Migrate to Claude Agent SDK"
aliases: [claude-code-sdk-migration, agent-sdk-migration]
tags: [agent-sdk, migration, typescript, python, breaking-changes]
sources: [raw/Migrate to Claude Agent SDK.md]
created: 2026-04-17
updated: 2026-04-17
---

# Migrate to Claude Agent SDK

The Claude Code SDK has been **renamed** to the Claude Agent SDK. The rename reflects broader capabilities beyond coding tasks — any domain agent, business automation, etc.

## Package Name Changes

| | TypeScript/JS | Python |
|---|---|---|
| **Old** | `@anthropic-ai/claude-code` | `claude-code-sdk` |
| **New** | `@anthropic-ai/claude-agent-sdk` | `claude-agent-sdk` |
| **Import module** | `@anthropic-ai/claude-agent-sdk` | `claude_agent_sdk` |

Documentation moved from Claude Code docs → API Guide → Agent SDK section.

## Migration Steps

### TypeScript / JavaScript

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

Update all imports:

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

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

Update `package.json`:

```json
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}
```

No other code changes needed (unless you hit breaking changes below).

### Python

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

Update imports and the renamed type:

```python
# 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 (v0.1.0)

### 1. `ClaudeCodeOptions` → `ClaudeAgentOptions` (Python only)

Rename the type everywhere. No behavioral difference.

### 2. System Prompt No Longer Defaulted (v0.1.0)

SDK now uses a minimal system prompt instead of Claude Code's CLI prompt.

```typescript
// To restore old behavior:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Or set a custom system prompt:
const result = query({
  prompt: "Hello",
  options: { systemPrompt: "You are a helpful coding assistant" }
});
```

### 3. Settings Sources No Longer Loaded by Default (v0.1.0)

SDK no longer reads `CLAUDE.md`, `settings.json`, slash commands, etc. by default.

```typescript
// To restore old behavior:
const result = query({
  prompt: "Hello",
  options: { settingSources: ["user", "project", "local"] }
});

// For isolated behavior (CI/CD, multi-tenant):
const result = query({
  prompt: "Hello",
  options: { settingSources: [] }
});
```

> **Note:** Current releases have **reverted** this default for `query()` — omitting `settingSources` once again loads user/project/local settings (matching CLI behavior). Pass `settingSources: []` explicitly if your app needs isolation. Python SDK ≤ 0.1.59 treats `[]` the same as omitting — upgrade before relying on empty list isolation.

## Why the Rename?

The SDK outgrew its "coding only" origins. Current use cases:
- Business agents: legal assistants, finance advisors, customer support
- Specialized coding agents: SRE bots, security reviewers, code review agents
- Custom domain agents with full tool use and MCP integration

## Key Takeaways

- **Only rename needed for most projects** — no logic changes required, just swap package name and update imports
- **Python extra step** — rename `ClaudeCodeOptions` → `ClaudeAgentOptions`
- **v0.1.0 breaking changes** around system prompt and settings sources were partially reverted; current `query()` loads settings by default again
- **To opt into isolation** (CI/CD, multi-tenant): pass `settingSources: []` — requires Python SDK > 0.1.59
- **Docs moved** to API Guide → Agent SDK section

## Related

- [[wiki/agent-sdk/overview|Agent SDK Overview]]
- [[wiki/agent-sdk/python-api-reference|Python API Reference]]
- [[wiki/agent-sdk/typescript-api-reference|TypeScript API Reference]]
- [[wiki/agent-sdk/configure-permissions|Configure Permissions]]
- [[wiki/agent-sdk/agent-loop|How the Agent Loop Works]]

## Sources

- `raw/Migrate to Claude Agent SDK.md`