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