Claude Agent SDKでAI開発を自動化

僕はCursorをやめて、Claude Code一本で開発している。MAXプランを契約して、まずClaude Codeにやらせてみるのが基本スタイルだ。毎日使っていると、ふと思う瞬間がある。「これ、スクリプトから動かせたらもっと便利なのに」と。

CLIは対話的で使いやすい。でもCI/CDに組み込んだり、独自のワークフローを組んだりしたいときには限界がある。

そこで登場したのがClaude Agent SDKだ。Claude Codeの中身をPythonやTypeScriptから呼び出せるライブラリで、CLIでは難しかった自動化の自由度が手に入る。

この記事では、僕がAgent SDKを触ってみた経験をもとに、基本から拡張機能までコードを交えて紹介していく。

Claude Agent SDKとは何か

Claude Agent SDKは、Claude Codeのツール群やエージェントループをプログラムから使えるようにしたライブラリだ。もともと「Claude Code SDK」という名前だった。2026年にClaude Agent SDKへリネームされている。旧名で検索している人もいるかもしれないので、覚えておいてほしい。

CLIとSDKの違い

Claude Code CLIは対話的な開発に向いている。ターミナルで質問して、ファイルを読んでもらって、編集してもらう。日常の開発ではこれで十分だと思う。

一方、SDKが活きるのはこういう場面だ。

• CI/CDパイプラインでコードレビューを自動実行したいとき
• 独自のエージェントアプリを構築したいとき
• 複数タスクをプログラムで制御して並列実行したいとき
• ツール実行の前後にカスタムロジックを挟みたいとき

SDKには、Read、Edit、Bash、Glob、Grepなどのビルトインツールがそろっている。ツール実行のループも自分で書く必要がない。Claudeが自律的にツールを選んで実行してくれる。

Client SDKとの違い

Anthropic Client SDK（API SDK）との違いも押さえておきたい。Client SDKはAPIに直接アクセスする。ツール実行ループは自分で実装が必要だ。Agent SDKはそのループごと面倒を見てくれる。「プロンプトを渡したら、あとはClaudeが動く」という体験がコードでも再現する。

Photo by Bernd Dittrich on Unsplash

10分で動かすAgent SDK入門

実際にコードを動かしてみよう。Python 3.10以上が必要だ。

インストールと準備

pip install claude-agent-sdk

APIキーを環境変数にセットする。

export ANTHROPIC_API_KEY=your-api-key

MAXプランのサブスク課金ではなく、API課金が必要になる。この点は後のセクションで詳しく触れる。

最初のエージェントを動かす

指定したファイルのバグを検出・修正するエージェントだ。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
 
async def main():
    async for message in query(
        prompt="utils.pyのバグを見つけて修正して",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)
 
asyncio.run(main())

ポイントは3つある。

• query()がエントリーポイント。非同期イテレータを返す
• allowed_toolsで使えるツールを指定する
• permission_mode="acceptEdits"でファイル編集を自動承認

これだけで、Claudeがファイルを読み、バグを見つけ、編集まで自律的にやってくれる。

query()とClaudeSDKClientの使い分け

SDKには2つのインターフェースがある。

query()は単発タスク向きだ。毎回新しいセッションが作られる。CIジョブやバッチ処理に向いている。

ClaudeSDKClientは継続的な会話向きだ。セッションを維持して複数ターンのやり取りができる。interrupt()で中断もできる。

from claude_agent_sdk import ClaudeSDKClient
 
async with ClaudeSDKClient() as client:
    await client.query("認証モジュールを読んで")
    async for msg in client.receive_response():
        print(msg)
    
    # コンテキストを維持したまま続けられる
    await client.query("呼び出し箇所を探して")
    async for msg in client.receive_response():
        print(msg)

対話的なアプリを作るならClaudeSDKClientを選ぶといい。

Hooks・Subagents・MCPで拡張する

基本がわかったところで、SDKならではの拡張機能を見ていこう。CLIではできないプログラムレベルのカスタマイズが可能になる。

Hooksでツール実行を制御する

Hooksは、エージェントのライフサイクルにカスタムコードを差し込む仕組みだ。「ファイル編集のたびにログを残す」「危険なコマンドをブロックする」といったことができる。

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
 
async def block_dangerous(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {"decision": "block", "reason": "危険なコマンド"}
    return {}
 
async for message in query(
    prompt="プロジェクトをリファクタリングして",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        permission_mode="acceptEdits",
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[block_dangerous])
            ]
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

PreToolUse以外にもPostToolUse、Stop、SubagentStartなど10種類以上のフックイベントがある。監査ログや品質ゲートなど、用途は幅広い。

Subagentsで専門エージェントに委任する

Subagentsは、特定タスクに特化したエージェントを定義して委任する仕組みだ。メインエージェントがオーケストレーターとなり、専門家に仕事を振る。

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
 
async for message in query(
    prompt="コードレビューエージェントでレビューして",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="コード品質・セキュリティレビュー担当",
                prompt="コード品質を分析して改善点を提案して",
                tools=["Read", "Glob", "Grep"],
                model="opus",
            )
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Subagentは独立したコンテキストウィンドウで動く。結果だけがメインに返される。コンテキストの節約と並列化の両方に効く。

カスタムツールとMCP連携

@toolデコレータで独自ツールも定義できる。

from claude_agent_sdk import tool, create_sdk_mcp_server
 
@tool("search_docs", "社内ドキュメントを検索", {"query": str})
async def search_docs(args):
    results = my_search_engine.search(args["query"])
    return {"content": [{"type": "text", "text": str(results)}]}
 
server = create_sdk_mcp_server(
    name="internal-tools",
    tools=[search_docs],
)

MCPサーバーとしてバンドルすれば外部サービス連携も簡単だ。Playwrightでブラウザを操作したり、DBにアクセスしたり。エージェントの守備範囲が一気に広がる。MCPはモデルに依存しないオープンプロトコルなので、ベンダーロックインを避けたい場面でも安心して使える。

知っておくべき注意点とコスト

SDKは強力だけど、導入前に知っておくべきことがある。

API課金が必要

SDKはAnthropicのAPIキーで認証する。MAXプランのサブスク課金では動かない。僕みたいに月$100のMAXプランでCLIを使い倒している人からすると、別途API課金がかかるのはちょっと痛い。。ResultMessage.total_cost_usdでリクエストごとのコストが追跡できるので、まずは小さなタスクで感覚をつかむのがいいかもしれない。

まだ進化途中の機能がある

マルチエージェント協調や自己評価は、リサーチプレビュー段階のものがある。すべてが本番で使えるわけではない。

他のフレームワークとの比較

他の選択肢も気になると思う。OpenAI Agents SDKはハンドオフパターンとガードレールが中心だ。エージェント間の受け渡しに強い。Claude Agent SDKはhooksとsubagentsが中心で、OS深いアクセスとMCP統合に強みがある。

MCPはモデル非依存のオープンプロトコルだ。ベンダーロックインを避けたいなら大きなメリットになる。音声やマルチモーダルの幅広さではOpenAI側が先行している。

コーディングエージェントならClaude Agent SDK。軽量なハンドオフチェーンならOpenAI Agents SDK。用途で選ぶのが現実的だと思う。

データ処理の考慮

SDKを通じた処理はAnthropicのクラウドを経由する。機密コードや社内データを扱うなら、Amazon BedrockやGoogle Vertex AI経由の利用も検討する価値がある。

まとめ：CLIの先にある自動化

Claude Agent SDKは、Claude Codeの力をプログラムから引き出すライブラリだ。CLIで体験していた「Claudeに任せる」感覚を、スクリプトやアプリの中でも再現できる。

始めるなら、まずquery()で小さなタスクを自動化するのがおすすめだ。そこからHooksで制御を加え、Subagentsで分業し、MCPで外部連携へ。段階的に拡張していくのがいいと思う。

SDKはまだ進化の途中にある。でも僕のように「まずClaude Codeにやらせてみよう」という考え方の人にとって、その自動化の可能性を大きく広げてくれるツールだと思う。

参考リンク

• Claude Agent SDK公式ドキュメント
• Agent SDK Python リファレンス
• Claude Agent SDK vs OpenAI Agents SDK比較（Composio）