Claude Code SDK からの Claude Agent SDK への移行でAI Agentのポータビリティを高める

企業テック

こんにちは。バクラク勤怠のソフトウェアエンジニアの @upamune です。
この記事は LayerX AI Agentブログリレー の 23日目 の記事です。

前回のClaude Code SDK ではじめる 定額 AI Agent 開発入門では、Claude Code SDK を使ってシンプルなタスク管理Agentを構築しました。
今回は、そのAgentをClaude Agent SDKに移行しながら、何が変わったのか・どう対応すればいいのか・何が嬉しいのかを具体的に解説します。

1. 前回のおさらい：Claude Code SDK でタスク管理Agent

前回の記事では、Claude Code SDKを使ってタスク管理Agentを作りました。以下のような機能を実装しました：

  • タスクの追加
  • タスクの一覧表示
  • タスクのステータス変更

Claude Pro/Maxプラン（最安$20/月）で定額利用できる点が魅力で、Custom ToolsとHooksを使ってシンプルなAgentを作ることができました。

しかし、Claude Code SDKはその後 Claude Agent SDK になりました。今回は、前回のタスク管理Agentをどのように書き直すべきかを見ていきます。

2. Claude Agent SDK への進化

2.1 なぜ改名されたのか

Claude Code SDKは 2025年9月に Claude Agent SDK へと名称変更されました。

AnthropicがClaude Codeを社内で使う中で、コーディング以外のタスクにも有効であることが分かってきました。つまり、Claude Codeを動かしている仕組みは、あらゆる種類のAgentを作成できるということです。

Anthropicの公式ブログでも、この進化について詳しく解説されています。

2.2 何が変わったのか

変わったのは名称だけではないので、ざっくり見てみましょう。

項目 Claude Code SDK Claude Agent SDK
パッケージ名(Python) claude-code-sdk claude-agent-sdk
パッケージ名(TypeScript) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
オプションクラス(Python) ClaudeCodeOptions ClaudeAgentOptions
デフォルトの振る舞い Claude Codeのシステムプロンプトがデフォルト 空のシステムプロンプトがデフォルト
設定ファイル 自動的に読み込まれる 明示的に指定が必要

特に重要なのは、デフォルトでClaude Codeのシステムプロンプト・設定ファイルを使わなくなった点です。これにより、コーディング以外の用途でも使いやすくなりました。

この変更によるマイグレーション方法については公式のガイドを見ればよいので、ここでは詳細に触れません。

システムプロンプトがデフォルトでClaude Code のシステムプロンプトが利用されなくなったのは、コーディングエージェント以外のエージェントを作りやすくなりました。
Claude Code のシステムプロンプトも使えるようになっています。これは preset として用意されているようで、調べてみると以下の preset がありました。コードを見ると今のところ claude_code という preset しか対応していないようでした。

query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        
        system_prompt={"type": "preset", "preset": "claude_code"}
    )
)

query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        
        system_prompt="あなたは日本人です。挨拶は日本語で返してください。"
    )
)

Claude Code の設定ファイルが自動で読み込まれなくなったのも非常に嬉しいアップデートです。 今まで setting_sources を指定できなかったので設定のスコープを簡単に変えられませんでした。特にAgent開発において、Userスコープを読みたいことは稀でしょう。Claude Code SDK だと使う必要のないMCPツールがUserスコープで設定されているため意図せずみえてしまっていて、余計なツールをAI Agent に利用されてしまうことがありましたが、これは setting_sources を絞ることにより発生しなくなりました。

CLAUDE.md、settings.json、スラッシュコマンドなどは、明示的に指定しない限り読み込まれません。

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


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

3. タスク管理Agentの移行手順

それでは、前回のタスク管理AgentをClaude Agent SDK対応版に書き直していきましょう。

3.1 パッケージのインストール

まずは古いパッケージをアンインストールして、新しいパッケージをインストールします。

# 古いパッケージをアンインストール
pip uninstall claude-code-sdk

# 新しいパッケージをインストール
pip install claude-agent-sdk

3.2 インポートの変更

from claude_code_sdk import ClaudeSDKClient, tool, create_sdk_mcp_server, ClaudeCodeOptions


from claude_agent_sdk import ClaudeSDKClient, tool, create_sdk_mcp_server, ClaudeAgentOptions

ClaudeCodeOptions が ClaudeAgentOptions に変わっただけで、他のインポートはそのままで利用できます。

3.3 Custom Toolsの実装（変更なし）

嬉しいことに、Custom Toolsの実装はまったく変更する必要がありません。前回の実装がそのまま使えます。

@tool("add_task", "新しいタスクを追加します。タスク名と優先度(高、中、低)を指定してタスクを作成できます。", {"name": str, "priority": str})
async def add_task(args: Dict[str, Any]) -> Dict[str, Any]:
    task_name = args["name"]
    priority = args.get("priority", "中")

    if priority not in TASK_PRIORITIES:
        return {
            "content": [
                {
                    "type": "text",
                    "text": f"❌ エラー: 優先度は {', '.join(TASK_PRIORITIES)} のいずれかを指定してください。",
                }
            ]
        }

    ensure_database()
    conn = get_db_connection()
    cursor = conn.cursor()

    cursor.execute(
        """INSERT INTO tasks (name, priority, status)
           VALUES (?, ?, ?)""",
        (task_name, priority, "未着手"),
    )
    task_id = cursor.lastrowid
    conn.commit()
    conn.close()

    return {
        "content": [
            {
                "type": "text",
                "text": (
                    "✅ タスクを追加しました:\n"
                    f"#️⃣ ID: {task_id}\n"
                    f"📝 {task_name}\n"
                    f"🔥 優先度: {priority}"
                ),
            }
        ]
    }

タスク一覧やステータス変更のツールも同様に変更不要です。

3.4 MCPサーバーの設定（変更なし）

同様にMCPサーバーの設定も変更不要です。

task_server = create_sdk_mcp_server(
    name="task-manager",
    version="1.0.0",
    tools=[add_task, list_tasks, change_task_status],
)

3.5 オプション設定の変更（重要）

ここが一番重要な変更点です。ClaudeCodeOptions を ClaudeAgentOptions に変更し、明示的にシステムプロンプトを設定します。

from claude_code_sdk import ClaudeCodeOptions

options = ClaudeCodeOptions(
    mcp_servers={"task_manager": task_server},
    allowed_tools=[
        "mcp__task_manager__add_task",
        "mcp__task_manager__list_tasks",
        "mcp__task_manager__change_task_status",
    ],
    hooks={"PreToolUse": [HookMatcher(hooks=[pre_tool_hook])]},
)


from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    system_prompt="""あなたはタスク管理を支援するアシスタントです。
以下のツールを使ってタスクの追加、一覧表示、ステータス変更ができます。

利用可能なツール:
- add_task: 新しいタスクを追加
- list_tasks: タスク一覧を表示
- change_task_status: タスクのステータスを変更

ユーザーの指示に従って、適切なツールを使用してタスク管理を行ってください。""",
    mcp_servers={"task_manager": task_server},
    allowed_tools=[
        "mcp__task_manager__add_task",
        "mcp__task_manager__list_tasks",
        "mcp__task_manager__change_task_status",
    ],
    hooks={"PreToolUse": [HookMatcher(hooks=[pre_tool_hook])]},
    setting_sources=[], 
)

デフォルトではシステムプロンプトが空になったので、Agentの役割とツールの説明を明示的に書く必要があります。これにより、タスク管理に特化したAgentとして振る舞うようになります。

3.6 Hooksの実装（変更なし）

Hooksの実装も変更不要です。前回と同じように、データベースファイル以外へのアクセスを制限できます。

async def pre_tool_hook(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {}) or {}

    if tool_name in {"Read", "Edit"}:
        fp = tool_input.get("file_path")
        requested = Path(fp).resolve()
        allowed = DB_FILE.resolve()
        if requested != allowed:
            return deny(f"Read/Edit は {allowed} のみ許可。要求: {fp}")

        return {}

    return deny(f"{tool_name} は許可されていません")

3.7 移行まとめ

今回の移行で変更が必要だった箇所をまとめると、以下のようになります：

変更が必要だった箇所
– パッケージ名（claude-code-sdk → claude-agent-sdk）
– インポート（ClaudeCodeOptions → ClaudeAgentOptions）
– システムプロンプトの明示的な設定
– setting_sources の明示的な指定（空配列でも可）

変更が不要だった箇所
– Custom Tools の実装（@tool デコレータ）
– MCPサーバーの設定（create_sdk_mcp_server）
– Hooks の実装（PreToolUse）

つまり、ツールやフックのロジックはそのままで、設定周りだけを調整すればOKです。

さらに、Claude Code の設定ファイルを読みに行かなくなったことで、Userスコープに設定された不要なMCPツールがAgentから見えなくなり、コードで明示的に提供したツールのみで動作するようになりました。これにより、どの環境でも同じように動作する、より汎用的でポータブルなAgentになったと言えます。

変更後のコードはこちらです。

5. まとめ

Claude Code SDKからClaude Agent SDKへの変更を前回Claude Code SDKで作成したエージェントを元に見てきました。 移行は簡単ですが、より汎用的なAgent が作りやすいアップデートになっています。

前回の記事で作成したタスク管理Agentも、ほとんど変更なしでClaude Agent SDKに移行できました。既にClaude Code SDKを使っている方は、ぜひ移行してみてください。そして、Agent Loopの考え方を使って、新しいAgentを作ってみてはいかがでしょうか。

前回作成したタスク管理AgentのコードもClaude Agent SDK対応版に更新済みです。ぜひ試してみてください。

github.com

最後に改めて、この記事はLayerX AI Agentブログリレーの23日目の記事です。毎日AI Agentに関する知見をお届けします！！LayerXテック公式Xを是非フォローして見逃さないようにお願いします！

AI Coding / AI Agent 開発に興味がある人は、ぜひお話しましょう！

jobs.layerx.co.jp

参考リンク




元の記事を確認する

ノーベル化学賞の授賞が決まった北川進教授と祝うために集まった学生たちの写真が最高「こんなふうに慕われる先生になりたい」 前の記事 日本政府、OpenAIに「著作権侵害行為」を行わないよう要請　Sora 2での“アニメ風動画”問題を受け 次の記事

関連記事