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