はじめに
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 にも対応
Claude Agent SDK のアーキテクチャ
エージェントループの構造
Claude Agent SDK のコアは、4 ステップの エージェントループ です。
- コンテキスト収集(Gather) — ファイル読み取り、Web 検索、Grep などで情報を収集
- アクション実行(Act) — ファイル編集、コマンド実行、API 呼び出しなどを実行
- 検証(Verify) — 実行結果を評価し、エラーや不整合を検出
- 反復(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() 関数です。プロンプトを渡すだけで、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 がリリースされており、活発に開発が進んでいます。



