agent-sdk/migration-guide diff

agent-sdk/migration-guide.md +315 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Migrate to Claude Agent SDK

7> Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK

9## Overview

11The 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.

13## What's Changed

15| Aspect | Old | New |

16| :------------------------- | :-------------------------- | :------------------------------- |

17| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Documentation Location** | Claude Code docs | API Guide → Agent SDK section |

21<Note>

22 **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features.

23</Note>

25## Migration Steps

27### For TypeScript/JavaScript Projects

29**1. Uninstall the old package:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Install the new package:**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. Update your imports:**

43Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`:

45```typescript theme={null}

46// Before

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

49// After

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

51```

53**4. Update package.json dependencies:**

55If you have the package listed in your `package.json`, update it:

57Before:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67After:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77That's it! No other code changes are required.

79### For Python Projects

81**1. Uninstall the old package:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Install the new package:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Update your imports:**

95Change all imports from `claude_code_sdk` to `claude_agent_sdk`:

97```python theme={null}

98# Before

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# After

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Update type names:**

106

107Change `ClaudeCodeOptions` to `ClaudeAgentOptions`:

108

109```python theme={null}

110# Before

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# After

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

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 (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# AFTER (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.

150

151### System prompt no longer default

152

153**What changed:** The SDK no longer uses Claude Code's system prompt by default.

154

155**Migration:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // BEFORE (v0.0.x) - Used Claude Code's system prompt by default

160 const result = query({ prompt: "Hello" });

161

162 // AFTER (v0.1.0) - Uses minimal system prompt by default

163 // To get the old behavior, explicitly request Claude Code's preset:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // Or use a custom system prompt:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # BEFORE (v0.0.x) - Used Claude Code's system prompt by default

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # AFTER (v0.1.0) - Uses minimal system prompt by default

186 # To get the old behavior, explicitly request Claude Code's preset:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset

193 ),

194 ):

195 print(message)

196

197 # Or use a custom system prompt:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**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.

207

208### Settings Sources No Longer Loaded by Default

209

210**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.

211

212**Migration:**

213

214<CodeGroup>

215 ```typescript TypeScript theme={null}

216 // BEFORE (v0.0.x) - Loaded all settings automatically

217 const result = query({ prompt: "Hello" });

218 // Would read from:

219 // - ~/.claude/settings.json (user)

220 // - .claude/settings.json (project)

221 // - .claude/settings.local.json (local)

222 // - CLAUDE.md files

223 // - Custom slash commands

224

225 // AFTER (v0.1.0) - No settings loaded by default

226 // To get the old behavior:

227 const result = query({

228 prompt: "Hello",

229 options: {

230 settingSources: ["user", "project", "local"]

231 }

232 });

233

234 // Or load only specific sources:

235 const result = query({

236 prompt: "Hello",

237 options: {

238 settingSources: ["project"] // Only project settings

239 }

240 });

241 ```

242

243 ```python Python theme={null}

244 # BEFORE (v0.0.x) - Loaded all settings automatically

245 async for message in query(prompt="Hello"):

246 print(message)

247 # Would read from:

248 # - ~/.claude/settings.json (user)

249 # - .claude/settings.json (project)

250 # - .claude/settings.local.json (local)

251 # - CLAUDE.md files

252 # - Custom slash commands

253

254 # AFTER (v0.1.0) - No settings loaded by default

255 # To get the old behavior:

256 from claude_agent_sdk import query, ClaudeAgentOptions

257

258 async for message in query(

259 prompt="Hello",

260 options=ClaudeAgentOptions(setting_sources=["user", "project", "local"]),

261 ):

262 print(message)

263

264 # Or load only specific sources:

265 async for message in query(

266 prompt="Hello",

267 options=ClaudeAgentOptions(

268 setting_sources=["project"] # Only project settings

269 ),

270 ):

271 print(message)

272 ```

273</CodeGroup>

274

275**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:

276

277* **CI/CD environments** - Consistent behavior without local customizations

278* **Deployed applications** - No dependency on filesystem settings

279* **Testing** - Isolated test environments

280* **Multi-tenant systems** - Prevent settings leakage between users

281

282<Warning>

283 Current SDK releases have reverted this default for `query()`: omitting the option once again loads user, project, and local settings, matching the CLI. Pass `settingSources: []` in TypeScript or `setting_sources=[]` in Python if your application depends on the isolated behavior described above. Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option, so upgrade before relying on `setting_sources=[]`. See [What settingSources does not control](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) for inputs that are read even when `settingSources` is `[]`.

284</Warning>

285

286## Why the Rename?

287

288The 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:

289

290* Building business agents (legal assistants, finance advisors, customer support)

291* Creating specialized coding agents (SRE bots, security reviewers, code review agents)

292* Developing custom agents for any domain with tool use, MCP integration, and more

293

294## Getting Help

295

296If you encounter any issues during migration:

297

298**For TypeScript/JavaScript:**

299

3001. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk`

3012. Verify your package.json has the new package name

3023. Run `npm install` to ensure dependencies are updated

303

304**For Python:**

305

3061. Check that all imports are updated to use `claude_agent_sdk`

3072. Verify your requirements.txt or pyproject.toml has the new package name

3083. Run `pip install claude-agent-sdk` to ensure the package is installed

309

310## Next Steps

311

312* Explore the [Agent SDK Overview](/en/agent-sdk/overview) to learn about available features

313* Check out the [TypeScript SDK Reference](/en/agent-sdk/typescript) for detailed API documentation

314* Review the [Python SDK Reference](/en/agent-sdk/python) for Python-specific documentation

315* Learn about [Custom Tools](/en/agent-sdk/custom-tools) and [MCP Integration](/en/agent-sdk/mcp)

agent-sdk/migration-guide.md Claude Code Docs, 2026-01-22 03:31 UTC → 2026-05-02 04:05 UTC