Claude Agent SDK徹底解説：プロダクション級AIエージェントの作り方

AIアシスタントが単なる「チャット相手」に留まっている現状に物足りなさを感じていませんか？ Anthropic社が提供するClaude Agent SDKを利用すれば、AIにファイル操作、コード実行、複雑なワークフローの計画と実行といった、まるで人間のプログラマーのような自律的な能力を与えることができます。

このClaude Agent SDK (旧称 Claude Code SDK) は、Anthropicの公式Python/TypeScriptツールキットであり、Claude Agentの中核となる強力なエージェントフレームワーク能力を、皆さんのアプリケーションに統合するために設計されています。コンテキスト管理、エラー処理、豊富なツールエコシステムといった、プロダクション環境で求められる全ての要素が含まれています。

本日は、このClaude Agent SDKを使って、高度なAIエージェントを構築するための具体的な手順と、開発に必要なコードの裏側まで深く掘り下げていきましょう！

---

I. 導入編：環境構築とセットアップ

Claude Agent SDKの強力な機能を利用するために、まずは環境を準備します。

1. 前提条件とインストール

Python版のClaude Agent SDKを使用するには、以下の前提条件が必要です。

• Python 3.10+
• Node.js
• Claude Code CLI (2.0.0+): npm install -g @anthropic-ai/claude-code を使用してインストールします。

次に、SDKパッケージをインストールし、APIキーを設定します。

# Claude Agent SDK Python パッケージをインストール
pip install claude-agent-sdk

# APIキーの設定 (必須)
export ANTHROPIC_API_KEY="あなたのAPIキー"

---

II. チュートリアル：2つのコアな対話モード

Claude Agent SDKは、用途に応じてquery() 関数と ClaudeSDKClient クラスという、異なる2つの主要なインタラクション方法を提供しています。

1. モード1：単発のインタラクションとストリーミング (query())

query() 関数は、最もシンプルで高速な方法です。これは、対話ごとに新しいセッションを作成するため、過去の記憶（コンテキスト）を持ちません。ストリーミング応答を処理する非同期イテレータを返します。

コード例：基本的な非同期クエリ

import anyio
from claude_agent_sdk import query, AssistantMessage, TextBlock

async def basic_query_example():
    # query()を使用して単発の質問を送信
    # options引数で設定を渡すことも可能です
    async for message in query(prompt="2 + 2 はいくつですか？"):
        # 受信したメッセージをリアルタイムで処理
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

if __name__ == "__main__":
    anyio.run(basic_query_example)

2. モード2：継続的な対話と高度な制御 (ClaudeSDKClient)

もし、エージェントに会話のコンテキスト（記憶）を維持させたい場合や、カスタムツール、フック、中断機能といった高度な制御が必要な場合は、ClaudeSDKClientを使用します。

これは、複数回の query() 呼び出しの間も、会話の状態を維持できるのが大きな特徴です。

コード例：継続的な会話（コンテキスト維持）

import asyncio
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock

async def continuous_conversation_example():
    # 非同期コンテキストマネージャを使用し、接続を自動で管理
    async with ClaudeSDKClient() as client:
        # 1回目の質問
        await client.query("フランスの首都はどこですか？")
        # 応答処理...
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # 2回目の質問 - Claude Agent SDK は前の会話内容を覚えている
        await client.query("その都市の人口について教えてください")
        # 応答処理...
        async for message in client.receive_response():
             if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

if __name__ == "__main__":
    asyncio.run(continuous_conversation_example())

---

III. 開発詳細：Claude Agent SDKの真の力

Claude Agent SDKがプロダクションレベルのAIエージェント構築に優れているのは、細部にわたるカスタマイズと制御を可能にする機能セットがあるからです。

1. Claude Agent Options：挙動と権限の設定

ClaudeAgentOptionsは、エージェントの振る舞いを決定する核心的な設定オブジェクトです。システムプロンプトのカスタマイズ、許可するツールの指定、作業ディレクトリの設定などを行います。

コード詳細：ファイル操作ツールと権限設定

Claude Agent SDKは、ファイル操作 (Read, Write) やコマンド実行 (Bash) といった強力な組み込みツールを利用できます。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def options_example():
    options = ClaudeAgentOptions(
        # 1. エージェントの役割を設定
        system_prompt="あなたはプロのPython開発者です",
        # 2. 組み込みツール（読み書き・Bash）を許可
        allowed_tools=["Read", "Write", "Bash"],
        # 3. 権限モード: 'acceptEdits' はファイルの編集を自動で許可する
        permission_mode='acceptEdits',
        # 4. 作業ディレクトリを設定
        cwd="/home/user/project"
    )

    async for message in query(
        prompt="hello.py ファイルを作成してください",
        options=options
    ):
        # Claude Agent SDK は Write ツールを使用してファイルを自動で作成する
        print(message)

if __name__ == "__main__":
    asyncio.run(options_example())

2. カスタムツールの作成：インプロセス SDK MCP サーバー

Claude Agent SDKの最も革新的な機能の一つが、Pythonの関数を直接エージェントが呼び出せるツールとして公開するインプロセスSDK MCPサーバーです。これにより、外部プロセスを起動する必要がなくなり、IPC (プロセス間通信) のオーバーヘッドを排除し、デバッグとデプロイを劇的に簡素化できます。

コード詳細：@toolデコレータとサーバーの統合

1. ツールの定義：@toolデコレータを使用して、ツール名、説明、入力スキーマ（型安全）を定義します。
2. サーバーの作成：create_sdk_mcp_server()を使用して、定義したツール関数をMCPサーバーとしてラップします。
3. オプションへの統合：ClaudeAgentOptionsのmcp_serversにサーバー設定を渡します。

import asyncio
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
from typing import Any

# 1. カスタムツール 'calculate' を定義
@tool("calculate", "数学的な計算を実行する", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    # 実際はより安全な方法で実行すべきですが、ここでは例として eval を使用
    try:
        result = eval(args["expression"])
        return {"content": [{"type": "text", "text": f"結果：{result}"}]}
    except Exception as e:
        return {"content": [{"type": "text", "text": f"エラー：{str(e)}"}], "is_error": True}

# 2. SDK MCP サーバーをインプロセスで作成
my_server = create_sdk_mcp_server(
    name="math_utils", # サーバー名
    version="1.0.0",
    tools=[calculate] # ツール関数を渡す
)

async def custom_tool_session():
    # 3. Claude Agent Optionsを構成
    options = ClaudeAgentOptions(
        # サーバー名を 'utils' として登録
        mcp_servers={"utils": my_server},
        # 許可するツール名を指定: 形式は mcp__<server_name>__<tool_name>
        allowed_tools=["mcp__utils__calculate"]
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("100を15で割った商を教えてください")
        # Claude Agent SDK は calculate ツールを呼び出し、結果を返す
        async for message in client.receive_response():
            print(message)

if __name__ == "__main__":
    asyncio.run(custom_tool_session())

3. 安全性、監査、制御：フック（Hooks）の利用

フックは、エージェントの実行サイクル（例：ツールが使われる前、ユーザープロンプトが送信された時）の特定のポイントで呼び出される決定的なコールバック関数です。セキュリティの確保、ロギング、入力の変更などに不可欠な機能です。

コード詳細：危険なコマンドの阻止 (PreToolUseフック)

PreToolUseフックを使用して、エージェントが Bash ツールを実行する前に、危険なコマンドをブロックする例です。

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher
from typing import Any

async def block_dangerous_bash(input_data: dict[str, Any], tool_use_id: str | None, context: Any) -> dict[str, Any]:
    tool_name = input_data.get('tool_name', '')
    if tool_name == "Bash":
        command = input_data['tool_input'].get('command', '')
        # 危険なパターンを検出
        if 'rm -rf /' in command:
            print("[セキュリティ警告] 危険なBashコマンドをブロックしました！")
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    # 実行を拒否する決定
                    'permissionDecision': 'deny',
                    'permissionDecisionReason': '危険コマンドのため実行を阻止'
                }
            }
    return {}

async def hooks_example():
    options = ClaudeAgentOptions(
        allowed_tools=["Bash"],
        hooks={
            # PreToolUseイベントにフックを設定
            'PreToolUse': [
                # Bashツールにのみこのフックを適用
                HookMatcher(matcher='Bash', hooks=[block_dangerous_bash])
            ]
        }
    )

    async with ClaudeSDKClient(options=options) as client:
        # 危険なコマンドを試行
        await client.query("Bashで rm -rf / を実行してください")
        # 応答処理: Claudeはフックによって阻止された旨のシステムメッセージを受け取る
        async for message in client.receive_response():
            print(message)

if __name__ == "__main__":
    asyncio.run(hooks_example())

IV. まとめ：Claude Agent SDKを選ぶ理由

Claude Agent SDKは、単なるAPIクライアントではなく、Claude Codeの基盤技術を活用した、真に自律的なAIシステムを構築するためのフレームワークです。

• 持続的な自律性：Claude Agent SDKにより、エージェントは長時間にわたる複雑なタスク（Claude Sonnet 4.5では30時間以上）を自律的に実行できます。
• 生産環境対応：セッション管理、組み込みエラー処理、そしてコンテキストの自動圧縮機能が提供され、トークンオーバーフローの心配をせずに長期的なワークフローを構築できます。
• 柔軟な拡張性：Model Context Protocol (MCP) を利用し、特にインプロセスSDK MCPサーバーを通じて、独自のPython関数をClaude Agent SDKに低遅延でシームレスに連携できます。
• 高度な安全性：PermissionMode、allowed_tools、そしてHooks機能により、エージェントの行動を厳密に制御し、危険な操作を防ぐことが可能です。

コーディング、セキュリティレビュー、金融分析、SREなど、複雑なタスクを自律的に遂行できるAIエージェントの構築を目指すなら、Claude Agent SDKがその強力な基盤となるでしょう。ぜひ、このClaude Agent SDKを活用して、次世代のAIアプリケーション開発に挑戦してみてください！