Upgrade to Claude Agent SDK: A Quick Migration Guide from Claude Code

Heads up, builders! You may have noticed that Anthropic has rebranded the Claude Code SDK to the new Claude Agent SDK.

This is more than just a new name. As the official announcement explains, this change reflects a strategic focus on making it easier than ever to build, debug, and deploy powerful AI agents.

If you've been following our deep dive into building agentic applications, you'll be happy to know that the migration is incredibly straightforward. All the core concepts and powerful features like conversation management, MCP integration, and response streaming are still there.

Here’s the TL;DR on how to upgrade your project.

1. Update Your Dependencies

First, uninstall the old package and install the new one.

1npm uninstall @anthropic-ai/claude-code
2npm install @anthropic-ai/agent-sdk

2. Update Your Imports

Next, just find and replace the import statements in your TypeScript files.

Before:

1import { query, type SDKMessage } from '@anthropic-ai/claude-code';

After:

1import { query, type SDKMessage } from '@anthropic-ai/agent-sdk';

3. Handle the Breaking Change in query Options

This is the most important part of the migration. The new SDK introduces a breaking change in how you provide a system prompt. The appendSystemPrompt option has been replaced with a more structured systemPrompt object.

Here’s how to adapt your query calls:

Before (claude-code-sdk):

1const response = query({
2  prompt: prompt,
3  options: {
4    appendSystemPrompt: systemPrompt, // This is now deprecated
5    mcpServers: mcpServers,
6    // ...other options
7  }
8});

After (claude-agent-sdk):

1const response = query({
2  prompt: prompt,
3  options: {
4    systemPrompt: systemPrompt, // Use the new systemPrompt option
5    mcpServers: mcpServers,
6    // ...other options
7  }
8});

In some cases, you might also want to specify the systemPrompt as a preset, like so:

1const response = query({
2  prompt: slashCommand,
3  options: {
4    systemPrompt: { type: 'preset', preset: 'claude_code' },
5    // ...other options
6  }
7});

And that's it! With these changes, your existing code, including all your slash commands and MCP configurations, will work exactly as before.

The move to the Claude Agent SDK is a clear signal of the agent-first future of AI. By making this small update, you're keeping your projects aligned with the latest and greatest from Anthropic.

For a complete guide to the architecture and patterns for building with the SDK, be sure to check out our original, in-depth tutorial.

Happy building!