Claude Code SDK から Agent SDK へ｜移行の手順と注意点

公開 2026-11-09更新 2026-11-09著者永上裕之仕事の自動化

この記事の要点

以前「Claude Code SDK」という名前で作った仕組みが、手元に残っていないでしょうか。この SDK は現在 Claude Agent SDK という名前に変わっています。Agent SDK の全体像は Claude Agent SDK とはで解説しました。

この記事では、公式ドキュメント「Migrate to Claude Agent SDK」（2026年11月9日確認）にもとづいて、古い SDK から新しい SDK へ移る手順と、動きが変わる点 を整理します。

結論：名前を替えて、2つの既定値を確かめる

移行の作業そのものは「名前の入れ替え」が中心 です。そのうえで、動きが変わる既定値を確かめます。

項目	古い名前	新しい名前
TypeScript・JavaScript のパッケージ	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
Python のパッケージ	claude-code-sdk	claude-agent-sdk
Python の読み込み名	claude_code_sdk	claude_agent_sdk
Python の設定の型	ClaudeCodeOptions	ClaudeAgentOptions
説明書きの場所	Claude Code の説明書きの中	専用の Agent SDK の章

名前が変わった理由について、公式は 「コーディング以外の AI エージェントも作れる、という広がりを表すため」 としています。

いちばん影響が大きいのは、Claude Code のシステムプロンプト（AI への基本の指示）が、既定では使われなくなったこと です。新しい SDK は、最小限の指示だけで動きます。

そのため、名前だけ替えて動かすと、以前と答え方や道具の使い方が変わる ことがあります。対処は2通りです。

やりたいこと	書き方
以前と同じ動きにする	システムプロンプトに preset の claude_code を指定する
自分の業務向けの指示にする	システムプロンプトに自分の文を書く

業務専用のエージェントなら、自分の文を書くほうが動きを読みやすくなります。 決まった形で答えを受け取りたい場合は Agent SDK の構造化出力も合わせて使えます。

設定ファイルの読み込みは、今は CLI と同じ既定に戻っています。 公式によると、版 0.1.0 で一度「何も読まない」既定に変わったあと、元に戻されました。そのため、この点で書き換えは要りません。

今の既定では、読み込み元（settingSources）を指定しないと、ユーザー・プロジェクト・ローカルの設定ファイル、CLAUDE.md、自作のコマンドが読まれます。

ただし、本番や自動処理では、手元の設定が混ざらないようにするのが安全 です。読み込み元を空のリストにすると、設定ファイルを読まずに動きます。公式も、CI・本番のアプリ・テスト環境・利用者が複数いるサービスでは、この切り離しが特に大事だと書いています。

1つ注意があります。Python の古い版（0.1.59 以前）では、空のリストが「指定なし」と同じ扱い でした。空のリストで切り離すなら、先に SDK を新しい版に上げておきます。

本番に出すまでの構成の考え方は Claude Agent SDK の本番運用、外部の道具の付け直しは Agent SDK で MCP をつなぐで解説しています。

なお、OpenAI の Agents SDK から移る場合について、公式は別に移行の手引き（クックブック）を用意しています。

永上裕之

ユニコスクール株式会社代表取締役。AIエージェント専門のスクール＆コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。