145 lines
4.2 KiB
Markdown
145 lines
4.2 KiB
Markdown
---
|
|
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`
|