1
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Agent SDK入門 — Claude Codeのエージェント基盤をPython/TSで活用する

1
Last updated at Posted at 2026-03-22

Claude Agent SDKの概要 — エージェントループとビルトインツール群

はじめに

Anthropic が提供する Claude Agent SDK は、Claude Code を動かしているエージェントループ・ビルトインツール・コンテキスト管理をそのままライブラリとして利用できる SDK です。もともと Claude Code SDK という名称でしたが、コーディング以外のユースケース(リサーチ、カスタマーサポート、ワークフロー自動化など)にも活用が広がったことを受け、Claude Agent SDK にリネームされました。

Python( claude-agent-sdk )と TypeScript( @anthropic-ai/claude-agent-sdk )の 2 言語で提供されており、ファイル読み書き・シェルコマンド実行・Web 検索といったツールがビルトインで組み込まれています。従来の Anthropic Client SDK のようにツール実行ループを自前で実装する必要がなく、 query() を呼ぶだけで Claude が自律的にツールを使い分けてタスクを完遂します。

この記事で学べること

  • Claude Agent SDK のアーキテクチャと Agent Loop の仕組み
  • Python / TypeScript でのセットアップと基本的な使い方
  • ビルトインツール・Hooks・サブエージェント・MCP 統合の活用法
  • Client SDK との違いと使い分けの判断基準

対象読者

  • AI エージェントを本番環境に組み込みたい開発者
  • Claude Code の機能をプログラマティックに利用したい方
  • エージェントフレームワークの選定を行っている方

TL;DR

  • Claude Agent SDK は Claude Code と同じエージェント基盤をライブラリとして提供する
  • query() 関数ひとつでファイル操作・コマンド実行・Web 検索を自律的に実行
  • Hooks でエージェントの振る舞いを制御、サブエージェントで並列タスク処理が可能
  • MCP サーバー統合により Playwright・データベース・外部 API など任意のシステムに接続できる
  • Amazon Bedrock・Google Vertex AI・Microsoft Azure にも対応

エージェントループのアーキテクチャ — Gather → Act → Verify → Iterate

Claude Agent SDK のアーキテクチャ

エージェントループの構造

Claude Agent SDK のコアは、4 ステップの エージェントループ です。

  1. コンテキスト収集(Gather) — ファイル読み取り、Web 検索、Grep などで情報を収集
  2. アクション実行(Act) — ファイル編集、コマンド実行、API 呼び出しなどを実行
  3. 検証(Verify) — 実行結果を評価し、エラーや不整合を検出
  4. 反復(Iterate) — 必要に応じて修正を繰り返し、タスクを完遂

このループは Claude Code の内部と同一の仕組みであり、SDK を通じて同じ品質のエージェント動作をプログラマティックに利用できます。

Client SDK との違い

Anthropic Client SDK( anthropic パッケージ)では、ツール呼び出しのたびに開発者がレスポンスを解析し、ツールを実行し、結果を API に返すという ツールループを自前で実装 する必要があります。

Claude Agent SDK では、このループ全体が SDK 内部で自動的に処理されます。

# Client SDK: ツールループを自分で実装
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude が自律的にツールを使い分ける
async for message in query(prompt="auth.py のバグを修正して"):
    print(message)

セットアップ

Python

前提条件: Python 3.10 以上

pip install claude-agent-sdk

TypeScript

npm install @anthropic-ai/claude-agent-sdk

認証設定

API キーを環境変数に設定します。Anthropic Console から取得できます。

export ANTHROPIC_API_KEY=your-api-key

サードパーティクラウドプロバイダーでの認証にも対応しています。

プロバイダー 環境変数
Amazon Bedrock CLAUDE_CODE_USE_BEDROCK=1 + AWS 認証情報
Google Vertex AI CLAUDE_CODE_USE_VERTEX=1 + GCP 認証情報
Microsoft Azure CLAUDE_CODE_USE_FOUNDRY=1 + Azure 認証情報

query()関数の実行フロー — プロンプトからツール選択・実行・結果ストリーミングまで

基本的な使い方

query() 関数でワンショット実行

もっともシンプルな使い方は query() 関数です。プロンプトを渡すだけで、Claude がビルトインツールを使い分けてタスクを処理します。

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="このディレクトリのファイル一覧を取得して",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "このディレクトリのファイル一覧を取得して",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

ビルトインツール一覧

SDK にはファイル操作からWeb 検索まで、9 種類のビルトインツールが組み込まれています。

ツール 機能
Read ファイル読み取り
Write ファイル新規作成
Edit 既存ファイルの部分編集
Bash ターミナルコマンド実行
Glob パターンによるファイル検索
Grep 正規表現によるファイル内容検索
WebSearch Web 検索
WebFetch Web ページ取得・解析
AskUserQuestion ユーザーへの質問(選択肢付き)

allowed_tools で使用するツールを明示的に指定することで、エージェントの動作範囲を制御できます。たとえば読み取り専用エージェントを作成する場合は ["Read", "Glob", "Grep"] のみを許可します。

ClaudeSDKClient で対話型セッション

query() はワンショット実行に向いていますが、 ClaudeSDKClient を使えばカスタムツールや Hooks を含む双方向の対話型セッションを構築できます。

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="あなたはコードレビューの専門家です",
    allowed_tools=["Read", "Glob", "Grep"],
    cwd="/path/to/project"
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("このプロジェクトのセキュリティ上の問題点を指摘して")
    async for msg in client.receive_response():
        print(msg)

Hooks — エージェントの振る舞いを制御する

Hooks は、エージェントループの特定のタイミングで実行されるコールバック関数です。ツール実行の前後で検証・ログ記録・ブロックなどの処理を挟み込めます。

利用可能なフックイベント

イベント タイミング
PreToolUse ツール実行前
PostToolUse ツール実行後
Stop エージェント停止時
SessionStart セッション開始時
SessionEnd セッション終了時
UserPromptSubmit ユーザープロンプト送信時

実装例: ファイル変更の監査ログ

以下の例では、ファイルが編集されるたびに監査ログに記録します。

from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher


async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}


async def main():
    async for message in query(
        prompt="utils.py のリファクタリングを行って",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

実装例: 危険なコマンドのブロック

PreToolUse フックでツール実行を事前にブロックすることも可能です。

async def block_dangerous_commands(input_data, tool_use_id, context):
    if input_data["tool_name"] != "Bash":
        return {}
    command = input_data["tool_input"].get("command", "")
    dangerous = ["rm -rf", "DROP TABLE", "format"]
    if any(d in command for d in dangerous):
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"危険なコマンドを検出: {command}"
            }
        }
    return {}

サブエージェントとカスタムツールの関係図

サブエージェント — 専門家チームを構築する

Agent ツールを使えば、メインエージェントから専門的なサブエージェントを起動し、タスクを委譲できます。各サブエージェントは独立したコンテキストウィンドウで動作するため、メインのコンテキストを圧迫しません。

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="code-reviewer エージェントでこのコードベースをレビューして",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="コード品質とセキュリティのレビュー専門家",
                    prompt="コードの品質を分析し、改善点を提案してください。",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

サブエージェントからのメッセージには parent_tool_use_id フィールドが含まれるため、どのサブエージェントからの出力かをプログラム的にトラッキングできます。

MCP 統合 — 外部システムとの接続

Model Context Protocol(MCP)を通じて、エージェントを外部のデータベース・ブラウザ・API などに接続できます。以下は Playwright MCP サーバーを使ったブラウザ自動操作の例です。

async for message in query(
    prompt="example.com を開いて、ページの内容を教えて",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {
                "command": "npx",
                "args": ["@playwright/mcp@latest"]
            }
        }
    ),
):
    if hasattr(message, "result"):
        print(message.result)

カスタムツール(インプロセス MCP サーバー)

Python 関数をカスタムツールとして定義し、サブプロセスなしでインプロセス実行することも可能です。IPC オーバーヘッドがないため、高頻度で呼び出すツールに向いています。

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("get_stock_price", "指定銘柄の株価を取得", {"ticker": str})
async def get_stock_price(args):
    ticker = args["ticker"]
    # 株価 API を呼び出す実装
    price = await fetch_price(ticker)
    return {
        "content": [
            {"type": "text", "text": f"{ticker}: ${price}"}
        ]
    }

server = create_sdk_mcp_server(
    name="finance-tools",
    version="1.0.0",
    tools=[get_stock_price]
)

options = ClaudeAgentOptions(
    mcp_servers={"finance": server},
    allowed_tools=["mcp__finance__get_stock_price"]
)

インプロセスサーバーと外部サブプロセスサーバーを混在させることも可能です。

セッション管理 — コンテキストの永続化

セッション ID を使って、複数のクエリにまたがるコンテキストを維持できます。最初のクエリで読み取ったファイルや分析結果を、後続のクエリで参照可能です。

session_id = None

# 最初のクエリ: セッション ID を取得
async for message in query(
    prompt="認証モジュールを読み込んで",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# セッションを再開: 前回のコンテキストを引き継ぐ
async for message in query(
    prompt="このモジュールを呼び出している箇所をすべて見つけて",
    options=ClaudeAgentOptions(resume=session_id),
):
    if hasattr(message, "result"):
        print(message.result)

ClaudeAgentOptions の主要設定

オプション 型 説明
system_prompt str カスタムシステムプロンプト
max_turns int 最大ターン数
allowed_tools list 自動承認するツール
disallowed_tools list ブロックするツール
permission_mode str 権限モード( acceptEdits 等)
cwd str / Path 作業ディレクトリ
mcp_servers dict MCP サーバー設定
hooks dict フックハンドラー
setting_sources list ["project"] で CLAUDE.md 等を読み込み

Claude Code CLI との使い分け

ユースケース 推奨
対話的な開発作業 CLI
CI/CD パイプライン統合 SDK
カスタムアプリケーション組み込み SDK
単発タスクの実行 CLI
本番ワークフロー自動化 SDK

多くのチームでは、日常の開発に CLI を使い、本番自動化に SDK を使うという併用パターンが推奨されています。CLI で検証したワークフローをそのまま SDK に移植できるため、プロトタイプから本番への移行がスムーズです。

エラーハンドリング

SDK は用途に応じた例外クラスを提供しています。

from claude_agent_sdk import (
    ClaudeSDKError,       # 基底エラー
    CLINotFoundError,     # Claude Code CLI 未インストール
    CLIConnectionError,   # 接続エラー
    ProcessError,         # プロセス失敗
    CLIJSONDecodeError    # JSON パースエラー
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("Claude Code CLI をインストールしてください")
except ProcessError as e:
    print(f"プロセス失敗(終了コード: {e.exit_code})")

まとめ

Claude Agent SDK は、Claude Code の内部で使われているエージェントインフラをそのまま開発者に公開したものです。ビルトインツールにより初期実装のコスト不要でエージェントを動かせる点、Hooks とサブエージェントによるきめ細かな制御が可能な点、そして MCP 統合による外部システムとの柔軟な接続が主な特徴です。

  • ワンショット実行には query() 関数、対話型には ClaudeSDKClient を使い分ける
  • allowed_tools でツール範囲を制限し、Hooks で監査・ブロックを実装する
  • サブエージェントで専門的なタスクを並列処理し、コンテキストを効率的に管理する
  • Amazon Bedrock / Google Vertex AI / Microsoft Azure にも対応しており、既存のクラウド環境に統合可能

2026 年 3 月時点で Python SDK は v0.1.48、TypeScript SDK は v0.2.71 がリリースされており、活発に開発が進んでいます。

参考リンク

1
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?