sdk/migration-guide.md +330 −0 created
1# Migrate to Claude Agent SDK
2
3Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK
4
5---
6
7## Overview
8
9The Claude Code SDK has been renamed to the **Claude Agent SDK** and its documentation has been reorganized. This change reflects the SDK's broader capabilities for building AI agents beyond just coding tasks.
10
11## What's Changed
12
13| Aspect | Old | New |
14| :----------------------- | :-------------------------- | :------------------------------- |
15| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |
16| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |
17| **Documentation Location** | Claude Code docs | API Guide → Agent SDK section |
18
19<Note>
20**Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/docs/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features.
21</Note>
22
23## Migration Steps
24
25### For TypeScript/JavaScript Projects
26
27**1. Uninstall the old package:**
28
29```bash
30npm uninstall @anthropic-ai/claude-code
31```
32
33**2. Install the new package:**
34
35```bash
36npm install @anthropic-ai/claude-agent-sdk
37```
38
39**3. Update your imports:**
40
41Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`:
42
43```typescript
44// Before
45import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
46
47// After
48import {
49 query,
50 tool,
51 createSdkMcpServer,
52} from "@anthropic-ai/claude-agent-sdk";
53```
54
55**4. Update package.json dependencies:**
56
57If you have the package listed in your `package.json`, update it:
58
59```json
60// Before
61{
62 "dependencies": {
63 "@anthropic-ai/claude-code": "^1.0.0"
64 }
65}
66
67// After
68{
69 "dependencies": {
70 "@anthropic-ai/claude-agent-sdk": "^0.1.0"
71 }
72}
73```
74
75That's it! No other code changes are required.
76
77### For Python Projects
78
79**1. Uninstall the old package:**
80
81```bash
82pip uninstall claude-code-sdk
83```
84
85**2. Install the new package:**
86
87```bash
88pip install claude-agent-sdk
89```
90
91**3. Update your imports:**
92
93Change all imports from `claude_code_sdk` to `claude_agent_sdk`:
94
95```python
96# Before
97from claude_code_sdk import query, ClaudeCodeOptions
98
99# After
100from claude_agent_sdk import query, ClaudeAgentOptions
101```
102
103**4. Update type names:**
104
105Change `ClaudeCodeOptions` to `ClaudeAgentOptions`:
106
107```python
108# Before
109from claude_agent_sdk import query, ClaudeCodeOptions
110
111options = ClaudeCodeOptions(
112 model="claude-sonnet-4-5"
113)
114
115# After
116from claude_agent_sdk import query, ClaudeAgentOptions
117
118options = ClaudeAgentOptions(
119 model="claude-sonnet-4-5"
120)
121```
122
123**5. Review [breaking changes](#breaking-changes)**
124
125Make any code changes needed to complete the migration.
126
127## Breaking changes
128
129<Warning>
130To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK. Review this section carefully before migrating.
131</Warning>
132
133### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions
134
135**What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`.
136
137**Migration:**
138
139```python
140# BEFORE (v0.0.x)
141from claude_agent_sdk import query, ClaudeCodeOptions
142
143options = ClaudeCodeOptions(
144 model="claude-sonnet-4-5",
145 permission_mode="acceptEdits"
146)
147
148# AFTER (v0.1.0)
149from claude_agent_sdk import query, ClaudeAgentOptions
150
151options = ClaudeAgentOptions(
152 model="claude-sonnet-4-5",
153 permission_mode="acceptEdits"
154)
155```
156
157**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.
158
159### System prompt no longer default
160
161**What changed:** The SDK no longer uses Claude Code's system prompt by default.
162
163**Migration:**
164
165<CodeGroup>
166
167```typescript TypeScript
168// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
169const result = query({ prompt: "Hello" });
170
171// AFTER (v0.1.0) - Uses empty system prompt by default
172// To get the old behavior, explicitly request Claude Code's preset:
173const result = query({
174 prompt: "Hello",
175 options: {
176 systemPrompt: { type: "preset", preset: "claude_code" }
177 }
178});
179
180// Or use a custom system prompt:
181const result = query({
182 prompt: "Hello",
183 options: {
184 systemPrompt: "You are a helpful coding assistant"
185 }
186});
187```
188
189```python Python
190# BEFORE (v0.0.x) - Used Claude Code's system prompt by default
191async for message in query(prompt="Hello"):
192 print(message)
193
194# AFTER (v0.1.0) - Uses empty system prompt by default
195# To get the old behavior, explicitly request Claude Code's preset:
196from claude_agent_sdk import query, ClaudeAgentOptions
197
198async for message in query(
199 prompt="Hello",
200 options=ClaudeAgentOptions(
201 system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset
202 )
203):
204 print(message)
205
206# Or use a custom system prompt:
207async for message in query(
208 prompt="Hello",
209 options=ClaudeAgentOptions(
210 system_prompt="You are a helpful coding assistant"
211 )
212):
213 print(message)
214```
215
216</CodeGroup>
217
218**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions.
219
220### Settings Sources No Longer Loaded by Default
221
222**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.
223
224**Migration:**
225
226<CodeGroup>
227
228```typescript TypeScript
229// BEFORE (v0.0.x) - Loaded all settings automatically
230const result = query({ prompt: "Hello" });
231// Would read from:
232// - ~/.claude/settings.json (user)
233// - .claude/settings.json (project)
234// - .claude/settings.local.json (local)
235// - CLAUDE.md files
236// - Custom slash commands
237
238// AFTER (v0.1.0) - No settings loaded by default
239// To get the old behavior:
240const result = query({
241 prompt: "Hello",
242 options: {
243 settingSources: ["user", "project", "local"]
244 }
245});
246
247// Or load only specific sources:
248const result = query({
249 prompt: "Hello",
250 options: {
251 settingSources: ["project"] // Only project settings
252 }
253});
254```
255
256```python Python
257# BEFORE (v0.0.x) - Loaded all settings automatically
258async for message in query(prompt="Hello"):
259 print(message)
260# Would read from:
261# - ~/.claude/settings.json (user)
262# - .claude/settings.json (project)
263# - .claude/settings.local.json (local)
264# - CLAUDE.md files
265# - Custom slash commands
266
267# AFTER (v0.1.0) - No settings loaded by default
268# To get the old behavior:
269from claude_agent_sdk import query, ClaudeAgentOptions
270
271async for message in query(
272 prompt="Hello",
273 options=ClaudeAgentOptions(
274 setting_sources=["user", "project", "local"]
275 )
276):
277 print(message)
278
279# Or load only specific sources:
280async for message in query(
281 prompt="Hello",
282 options=ClaudeAgentOptions(
283 setting_sources=["project"] # Only project settings
284 )
285):
286 print(message)
287```
288
289</CodeGroup>
290
291**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:
292- **CI/CD environments** - Consistent behavior without local customizations
293- **Deployed applications** - No dependency on filesystem settings
294- **Testing** - Isolated test environments
295- **Multi-tenant systems** - Prevent settings leakage between users
296
297<Note>
298**Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options.
299</Note>
300
301## Why the Rename?
302
303The Claude Code SDK was originally designed for coding tasks, but it has evolved into a powerful framework for building all types of AI agents. The new name "Claude Agent SDK" better reflects its capabilities:
304
305- Building business agents (legal assistants, finance advisors, customer support)
306- Creating specialized coding agents (SRE bots, security reviewers, code review agents)
307- Developing custom agents for any domain with tool use, MCP integration, and more
308
309## Getting Help
310
311If you encounter any issues during migration:
312
313**For TypeScript/JavaScript:**
314
3151. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk`
3162. Verify your package.json has the new package name
3173. Run `npm install` to ensure dependencies are updated
318
319**For Python:**
320
3211. Check that all imports are updated to use `claude_agent_sdk`
3222. Verify your requirements.txt or pyproject.toml has the new package name
3233. Run `pip install claude-agent-sdk` to ensure the package is installed
324
325## Next Steps
326
327- Explore the [Agent SDK Overview](/docs/en/agent-sdk/overview) to learn about available features
328- Check out the [TypeScript SDK Reference](/docs/en/agent-sdk/typescript) for detailed API documentation
329- Review the [Python SDK Reference](/docs/en/agent-sdk/python) for Python-specific documentation
330- Learn about [Custom Tools](/docs/en/agent-sdk/custom-tools) and [MCP Integration](/docs/en/agent-sdk/mcp)