Claude Agent SDK の概要

学習のねらい

AI エージェントを開発する際、Anthropic が提供する Claude Agent SDK (claude-agent-sdk) を使うと、Claude Code を支えているエージェントループ (思考 → ツール呼び出し → 観察の繰り返し) を自分のアプリケーションにそのまま組み込めます。 本レッスンでは、SDK の2つの入り口 query() と ClaudeSDKClient、そしてエージェントの挙動を制御する ClaudeAgentOptions について学びます。

Claude Agent SDK とは

Claude Agent SDK は、Python (および TypeScript) で AI エージェントを構築するための公式ライブラリです。プロンプト設計やツール呼び出しループを自前で書く代わりに、Claude Code と同じエージェント基盤を関数呼び出し1つで利用できます。

pip install claude-agent-sdk

エージェントとのやり取りには、目的に応じて2つの入り口があります。

1. query(): 1回限りのタスクに向いた関数です。プロンプトを渡すと、結果が返るまで非同期にメッセージをストリーミングします。呼び出すたびに新しいセッションが始まります。
2. ClaudeSDKClient: 複数ターンの会話・カスタムツール・hooks を扱いたいときに使うクライアントです。セッション状態や MCP 接続をまとめて管理します。

query() で1回限りのタスクを投げる

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="あなたは親切なアシスタントです。",
        model="claude-opus-4-1",
    )
    async for message in query(prompt="日本の首都はどこですか？", options=options):
        print(message)

asyncio.run(main())

ClaudeSDKClient で会話を継続する

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk import AssistantMessage, TextBlock

async def main():
    options = ClaudeAgentOptions(system_prompt="あなたは親切なアシスタントです。")

    async with ClaudeSDKClient(options=options) as client:
        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}")

        # 直前の文脈を踏まえたフォローアップ質問
        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}")

asyncio.run(main())

ClaudeSDKClient は async with ブロックの中でセッションを保持し続けるため、2回目の client.query() 呼び出しは1回目の文脈を引き継ぎます。query() にはこの機能がありません。

ClaudeAgentOptions で挙動を制御する

主なフィールドは次の通りです。

• system_prompt: エージェントの役割設定
• model / fallback_model: 使用モデルとフォールバック先
• allowed_tools / disallowed_tools: 自動承認・禁止するツール
• permission_mode: "default" / "acceptEdits" / "plan" / "bypassPermissions" など
• mcp_servers: 接続する MCP サーバーの設定 (次のレッスン以降で扱います)
• max_turns / max_budget_usd: 暴走防止のための上限

まとめ

Claude Agent SDK は query() (単発) と ClaudeSDKClient (継続セッション) という2つの入り口を持ち、ClaudeAgentOptions で権限・モデル・予算を制御します。次のレッスンでは、この SDK にカスタムツールを外部連携させる MCP (Model Context Protocol) について学びます。

（最終検証日: 2026-07 時点の公式ドキュメントに基づく。SDK は更新が速いため、コピペ前に 公式ドキュメント で最新のAPIを確認してください）

---