Claude Agent SDK への移行
Claude Code TypeScript および Python SDK を Claude Agent SDK に移行するためのガイド
概要
Claude Code SDK は Claude Agent SDK に名前が変更され、ドキュメントが再編成されました。この変更は、コーディングタスクだけでなく、AI エージェント構築のための SDK のより広い機能を反映しています。
変更内容
| 項目 | 旧版 | 新版 |
|---|---|---|
| パッケージ名（TS/JS） | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Python パッケージ | claude-code-sdk |
claude-agent-sdk |
| ドキュメント場所 | Claude Code ドキュメント | API ガイド → Agent SDK セクション |
移行手順
TypeScript/JavaScript プロジェクト向け
1. 古いパッケージをアンインストールします：
npm uninstall @anthropic-ai/claude-code
2. 新しいパッケージをインストールします：
npm install @anthropic-ai/claude-agent-sdk
3. インポートを更新します：
@anthropic-ai/claude-code からのすべてのインポートを @anthropic-ai/claude-agent-sdk に変更します：
// 変更前
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
// 変更後
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
4. package.json の依存関係を更新します：
package.json にパッケージがリストされている場合は、更新します：
変更前：
{
"dependencies": {
"@anthropic-ai/claude-code": "^0.0.42"
}
}
変更後：
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
5. 破壊的変更 を確認します
移行を完了するために必要なコード変更を行います。
Python プロジェクト向け
1. 古いパッケージをアンインストールします：
pip uninstall claude-code-sdk
2. 新しいパッケージをインストールします：
pip install claude-agent-sdk
3. インポートを更新します：
claude_code_sdk からのすべてのインポートを claude_agent_sdk に変更します：
# 変更前
from claude_code_sdk import query, ClaudeCodeOptions
# 変更後
from claude_agent_sdk import query, ClaudeAgentOptions
4. 型名を更新します：
ClaudeCodeOptions を ClaudeAgentOptions に変更します：
# 変更前
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")
# 変更後
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")
5. 破壊的変更 を確認します
移行を完了するために必要なコード変更を行います。
破壊的変更
Python：ClaudeCodeOptions が ClaudeAgentOptions に名前変更
変更内容： Python SDK の型 ClaudeCodeOptions が ClaudeAgentOptions に名前変更されました。
移行：
# 変更前（claude-code-sdk）
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# 変更後（claude-agent-sdk）
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
変更理由： 型名は「Claude Agent SDK」ブランディングと一致し、SDK の命名規則全体で一貫性を提供します。
システムプロンプトがデフォルトではなくなりました
変更内容： SDK はデフォルトで Claude Code のシステムプロンプトを使用しなくなりました。
移行：
import { query } from "@anthropic-ai/claude-agent-sdk";
// 変更前（v0.0.x）- デフォルトで Claude Code のシステムプロンプトを使用
const before = query({ prompt: "Hello" });
// 変更後（v0.1.0）- デフォルトで最小限のシステムプロンプトを使用
// 古い動作を取得するには、Claude Code のプリセットを明示的にリクエストします：
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// またはカスタムシステムプロンプトを使用します：
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# 変更前（v0.0.x）- デフォルトで Claude Code のシステムプロンプトを使用
async for message in query(prompt="Hello"):
print(message)
# 変更後（v0.1.0）- デフォルトで最小限のシステムプロンプトを使用
# 古い動作を取得するには、Claude Code のプリセットを明示的にリクエストします：
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # プリセットを使用
),
):
print(message)
# またはカスタムシステムプロンプトを使用します：
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)
変更理由： SDK アプリケーションのより良い制御と分離を提供します。Claude Code の CLI 中心の指示を継承することなく、カスタム動作を持つエージェントを構築できるようになりました。
設定ソースのデフォルト
このデフォルトは v0.1.0 で一度変更されてから元に戻されたため、移行アクションは必要ありません。
現在の動作： query() で settingSources を省略すると、ユーザー、プロジェクト、ローカルファイルシステムの設定が読み込まれ、CLI と一致します。これには ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md ファイル、およびカスタムコマンドが含まれます。
ファイルシステム設定から分離して実行するには、空の配列を渡します：
import { query } from "@anthropic-ai/claude-agent-sdk";
const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // ファイルシステム設定は読み込まれません
}
});
// または特定のソースのみを読み込みます：
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // プロジェクト設定のみ
}
});
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # ファイルシステム設定は読み込まれません
):
print(message)
# または特定のソースのみを読み込みます：
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # プロジェクト設定のみ
),
):
print(message)
分離は、ローカルのカスタマイズがリークしてはいけない CI/CD パイプライン、デプロイされたアプリケーション、テスト環境、マルチテナントシステムで特に重要です。
名前変更の理由
Claude Code SDK はもともとコーディングタスク用に設計されていましたが、あらゆるタイプの AI エージェント構築のための強力なフレームワークに進化しました。新しい名前「Claude Agent SDK」はその機能をより良く反映しています：
- ビジネスエージェントの構築（法務アシスタント、ファイナンスアドバイザー、カスタマーサポート）
- 特化したコーディングエージェントの作成（SRE ボット、セキュリティレビュアー、コードレビューエージェント）
- ツール使用、MCP 統合など、あらゆるドメイン向けのカスタムエージェント開発
ヘルプを得る
移行中に問題が発生した場合：
TypeScript/JavaScript の場合：
- すべてのインポートが
@anthropic-ai/claude-agent-sdkを使用するように更新されていることを確認します - package.json に新しいパッケージ名があることを確認します
npm installを実行して、依存関係が更新されていることを確認します
Python の場合：
- すべてのインポートが
claude_agent_sdkを使用するように更新されていることを確認します - requirements.txt または pyproject.toml に新しいパッケージ名があることを確認します
pip install claude-agent-sdkを実行して、パッケージがインストールされていることを確認します
次のステップ
- Agent SDK Overview を探索して、利用可能な機能について学びます
- TypeScript SDK Reference をチェックして、詳細な API ドキュメントを確認します
- Python SDK Reference を確認して、Python 固有のドキュメントを確認します
- Custom Tools と MCP Integration について学びます