Claude Agent SDKとは？AIエージェント開発の基礎から実践まで徹底解説

「AIに指示を出したら、あとは自動で考えて作業を進めてくれたら……」。そんな理想を実現するのがAIエージェントです。Anthropicが提供するClaude Agent SDKは、Claudeを頭脳としたAIエージェントをPythonやTypeScriptで構築できるライブラリ。Claude Code（Anthropic公式のコーディングエージェント）を動かしているツール・エージェントループ・コンテキスト管理を、そのまま自分のプログラムから使えます。

この記事では、Claude Agent SDKの基本概念から実装方法、活用シーンまでを体系的に解説します。

AIエージェントとは？

AIエージェントは、従来の「質問→回答」型のAIとは異なります。自律的にタスクを分解し、ツールを使い、結果を判断して次のアクションを決定するのが特徴です。

たとえば「auth.pyのバグを直して」と頼むと、エージェントは以下のように動きます。

1. ファイルを読んでコードを理解する
2. 関連ファイルを検索して全体像を把握する
3. バグの原因を特定する
4. コードを修正する
5. テストを実行して動作確認する
6. 結果を報告する

人間が途中で介入しなくても、これら一連の作業を自分で判断して進めます。これがエージェントの力です。

Claude Agent SDKの概要

Claude Agent SDKは、Anthropicが公式に提供するエージェント開発用のライブラリです。公式ドキュメントはこれを「Claude Codeのバイナリを動かすライブラリ」と説明しています。つまり、SDKがClaude Code本体を呼び出して動かすという向きです。PythonとTypeScriptのSDKにはそのバイナリが同梱されているので、多くの環境ではClaude Codeを別に入れる必要はありません。

主な特徴は以下の通りです。

Claude のコード（Claude Code）で動いているエージェントを、画面の外にある自分のアプリやスクリプトに組み込むためのものがこのAgent SDKです。

エージェントループの仕組み

Agent SDKの核となるのがエージェントループです。これは「Claudeが考え、ツールを使い、結果を確認し、また考える」というサイクルを自動で回す仕組みです。

具体的な流れは以下の通りです。

1. プロンプト受信：ユーザーの指示をClaudeに渡す
2. Claudeが判断：指示を分析し、必要なアクションを決定
3. ツール実行：Bash、Edit、Readなどのツールを呼び出して作業
4. 結果処理：ツールの実行結果をClaudeにフィードバック
5. ループ継続 or 完了：まだ作業が必要ならステップ2に戻り、完了したらテキスト応答を返す

重要なポイントは、ツール呼び出しがなくなったら完了ということ。Claudeが「もうツールを使う必要はない」と判断したら、最終的なテキスト応答が返ってきます。

始め方：インストールと基本コード

インストール

PythonまたはTypeScriptで利用できます。

# Python
pip install claude-agent-sdk

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

必要な環境は Node.js 18 以上、または Python 3.10 以上です（公式クイックスタート）。

認証：APIキーを使う（claude.aiのログインは使えない）

SDKは環境変数 ANTHROPIC_API_KEY に設定したAPIキーで動きます。Amazon Bedrock・Google Cloud（Google が運営する版）・Microsoft Foundry経由で使う場合は、それぞれ CLAUDE_CODE_USE_BEDROCK=1・CLAUDE_CODE_USE_VERTEX=1・CLAUDE_CODE_USE_FOUNDRY=1 を設定し、各クラウドの認証情報を用意します。SDKは .env ファイルを自動では読み込まないので、実行するシェルで設定しておきます。Google Cloud で Claude を使う手順と料金は「Vertex AIでClaudeを使う方法」にまとめています。

気をつけたいのは、claude.aiのログイン（Pro・Maxなどの契約）の扱いです。公式ドキュメントは、事前の承認がない限り、第三者の開発者が自分の製品（Agent SDKで作ったエージェントを含む）でclaude.aiのログインや利用枠を提供することを認めていません。SDKで作るアプリは、APIキーによる認証で動かします。

最小限のエージェント（Python）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="src/auth.pyのバグを見つけて修正して",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"コスト: ${message.total_cost_usd:.4f}")

asyncio.run(main())

最小限のエージェント（TypeScript）

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

for await (const message of query({
  prompt: "src/auth.pyのバグを見つけて修正して",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

たったこれだけで、Claudeがファイルを読み、バグを探し、修正し、結果を報告するエージェントが動きます。ただし allowed_tools は「使ってよいツールの一覧」ではなく、確認なしで自動承認するツールの一覧です。上の例では Bash を入れているので、Claudeが選んだシェルコマンドが確認なしで実行されます（どの設定でも自動承認されない一部の削除操作などを除く）。なお、この例は permission_mode を指定していないので、モードは設定ファイルの permissions.defaultMode、無ければ組み込みの既定値で決まり、v2.1.285 以降はサードパーティのプロバイダー（Bedrock・Google Cloud・Microsoft Foundry）経由やテレメトリーをオフにした環境など、機能フラグを取得しないセッションでその既定値が auto になっていました（公式）。ただし v2.1.302（2026年10月16日）で変わり、権限モードを指定しない Agent SDK と claude -p のセッションは、サードパーティのプロバイダー経由などでも default で始まるようになりました。auto で動かすには明示が必要です（CLI では --permission-mode auto。更新履歴、2026年10月18日に確認）。auto モードは Bash のような広い許可ルールを外すので、上の動きを前提にするなら permission_mode="default"（TS: permissionMode: "default"）を明示します（公式）。試すときは、壊れても困らない作業用のディレクトリで動かしましょう。ツールの絞り方は次の節で説明します。

組み込みツール一覧

Agent SDKには、コードを書かなくてもすぐに使えるツールが多数用意されています。

組み込みツールは、自分でツール処理のコードを書かなくても使えます。注意したいのは、「どのツールをClaudeに見せるか」と「どのツールを確認なしで通すか」が別の設定だという点です。公式ドキュメントの説明を表にまとめます。

たとえば allowed_tools=["Read"] と permission_mode="bypassPermissions" を一緒に指定すると、並べていない Bash・Write・Edit も含めてすべて承認されます（公式ドキュメントが警告している組み合わせです）。使わせたくないツールは tools か disallowed_tools で外します。決めたツールだけで動かしたいなら、allowed_tools と permission_mode="dontAsk"（確認が要る呼び出しはすべて拒否）を組み合わせます。

もう1つ、Glob と Grep は macOS・Linux・WSL では既定のツールに入っていません（Windowsでは入っています）。そのときClaudeは Bash 経由の find・grep で検索します。tools や allowed_tools でどちらかの名前を挙げると使えるようになります（公式：ツール一覧）。

カスタムツールの作り方

組み込みツールだけでは足りない場合、独自のツールを作成できます。たとえば天気APIと連携するツールを作ってみましょう。

Python版

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "指定した都市の現在の天気を取得する",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # 実際にはAPIを呼び出す
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"{city}の天気: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript版

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "指定した都市の現在の天気を取得する",
  { city: z.string().describe("都市名") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `${args.city}の天気: ${data}` }]
    };
  }
);

カスタムツールはMCPサーバーとして作成し、mcp_servers（TS: mcpServers）でエージェントに渡します。ツールの正式な名前は mcp__サーバー名__ツール名 になるので、確認なしで使わせるならその名前を allowed_tools に入れます。

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

ツールの中で例外が起きても、エージェントのループは止まりません。SDKのMCPサーバーが例外を受け止め、例外のメッセージをそのままエラー結果としてClaudeに渡します。自分で例外を捕まえて "is_error": True（TypeScriptでは isError: true）を返すと、「どのリクエストが失敗したか」「代わりに何を試せばよいか」など、Claudeが読むメッセージを自分で書けます。どちらの場合もClaudeは、再試行する・別のツールを試す・失敗を説明するといった対応ができます（公式：カスタムツール）。

サブエージェントで並列処理

大きなタスクは、サブエージェントに分割して並列実行すると効率的です。メインエージェントのコンテキスト（記憶）を汚さずに、専門的なタスクを別のエージェントに任せられます。

サブエージェントが有効なケース

• 大量のテスト実行：テスト結果のログが膨大でもメインのコンテキストに影響しない
• 並列調査：複数のモジュールを同時に調べて結果だけ受け取る
• 専門作業の分離：「コードレビュー」と「テスト実行」を別々のエージェントに任せる

Claude Codeでのカスタムサブエージェント

Claude Code（CLI）では .claude/agents/ にMarkdownファイルを置くだけでカスタムサブエージェントを定義できます。

# .claude/agents/reviewer.md
---
name: code-reviewer
description: コードレビュー専門のエージェント
tools: Read, Glob, Grep
model: sonnet
---

あなたはシニアコードレビュアーです。
コード品質、セキュリティ、ベストプラクティスの
観点でレビューしてください。

ツールアクセスを制限（上の例ではRead系のみ）することで、レビュアーが誤ってコードを修正してしまうリスクを防げます。

権限・フック・セッション

本番で動かすときに効いてくるのがこの3つです。どれも公式ドキュメントが「SDKで使えるClaude Codeの機能」として挙げています。

権限：呼び出しごとに決まった順で判定される

Claudeがツールを呼ぶと、SDKは フック → 拒否ルール → 確認ルール → 権限モード → 許可ルール → can_use_tool コールバック の順に判定します。拒否ルール（disallowed_tools など）に一致した呼び出しは、bypassPermissions でも止まります。ただし、プラグインとして入れた mod（関数で書くフック）は Agent SDK のセッションでも動き（公式）、tool.check に答える mod は、管理設定のある端末や Team・Enterprise プランでのサインイン時を除けば、拒否ルールに一致した呼び出しも承認できます（公式）。mod は信頼できる作者のものだけを入れましょう。詳しくは「Claude Code の mods とは」を参照してください。権限モードは permission_mode で選びます（2026年9月時点の公式ドキュメント）。

フック：決まったタイミングで自分のコードを走らせる

フックは、ツールの実行前（PreToolUse）・実行後（PostToolUse）・停止時（Stop）などのイベントで呼ばれるコールバックです。権限の判定より先に走るので、「どのモードでも必ず止めたい操作」はここで拒否できます。次の例は .env ファイルへの書き込みを拒否します（公式ドキュメントの例を短くしたもの）。

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

セッション：続きから再開する・分岐する

SDKは会話の履歴（プロンプト・ツール呼び出し・結果・応答）をセッションとして自動でディスクに保存します。結果メッセージの session_id を控えておき、次の query() で resume に渡すと、読んだファイルやそれまでの判断を踏まえたまま続けられます。直近のセッションでよければ continue_conversation=True（TS: continue: true）、元のセッションを残したまま別の方針を試すなら fork_session=True（TS: forkSession: true）を使います。保存されるのは会話だけで、ファイルの変更は巻き戻りません（公式：セッション）。

このほか、プロジェクトの .claude/ と ~/.claude/ にあるスキル・コマンド・メモリは、Claude Codeと同じように自動で読み込まれます。スキル・エージェント・フック・MCPサーバーをまとめたプラグインも、ローカルのパスを指定して読み込めます。

Agent SDK vs Client SDK vs Claude Code

Claudeで開発するときの選択肢として、公式の比較表はAgent SDK・Claude Code CLI・Client SDK・Managed Agentsの4つを挙げています。ここではまず、自分の手元やサーバーで動かす3つを比べます。

迷ったらこう選ぶ：

• 日常の開発作業 → Claude Code CLI
• 自動化システムを構築したい → Agent SDK
• 独自のAIアプリを作りたい → Client SDK
• ループやサンドボックスの運用ごと任せたい → Managed Agents（Anthropicがホストするエージェント。Anthropic管理のクラウドか自前のインフラのサンドボックスで動き、各言語のSDK・ant CLI・REST APIから使う）

実践的な活用シーン

コード開発の自動化

最も一般的な使い方です。「この機能を実装して」と指示すると、エージェントがファイル構成を調べ、コードを書き、テストまで実行します。

# バグ修正の自動化
async for msg in query(
    prompt="認証モジュールのテストが失敗している。原因を調べて修正して",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # コスト上限$2
    ),
):
    pass

CI/CDパイプラインへの組み込み

GitHub Actionsなどと連携して、PRが作成されるたびに自動でコードレビューしたり、テスト失敗時に自動修正を試みるワークフローを構築できます。

データ分析・調査

「過去1ヶ月のログからエラーパターンを分析して」といった、複数のステップが必要な調査作業もエージェントに任せられます。WebSearchツールと組み合わせれば、最新情報も取り込めます。

ベストプラクティス

1. コスト制御を忘れずに

エージェントはループするため、予想以上にトークンを消費することがあります。必ず max_budget_usd や max_turns を設定しましょう。

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # 5ドルで停止
    max_turns=30,           # 30ターンで停止
    effort="medium",        # 推論の深さ（low/medium/high/xhigh/max）
)

effortの xhigh は、対応していないモデルでは high として扱われます。上限に達すると、最後の結果メッセージの subtype が、max_budget_usd のときは "error_max_budget_usd"、max_turns のときは "error_max_turns" になり、result は空（None）です。止まった理由は subtype で見分けます。

ただし、この金額はSDKが同梱の価格表から計算する見積もりで、請求額そのものではありません。数えるのはその呼び出し自身の支出だけで、resume で再開したセッションの過去の分は予算に含まれません。正確な請求額は、Claude ConsoleのUsageページかUsage and Cost APIで確かめます（公式：コストと使用量の追跡）。

2. ツールは最小限に

使わないツールをClaudeに見せないようにするには、tools で使うツールだけを並べるか、disallowed_tools に名前だけを書いて外します。allowed_tools は確認を省くための設定で、ツールを絞る効果はありません。確認なしで通すツールも、タスクに必要な最小限にしておきましょう。

3. ツールのエラーは is_error で伝える

カスタムツールで例外が起きても、エージェントのループは止まりません。SDKが例外のメッセージをエラー結果としてClaudeに渡します。ただ、生の例外メッセージだけでは次の手を決めにくいことがあります。自分で捕まえて "is_error": True（TypeScriptでは isError: true）とともに「何が失敗し、代わりに何を試せるか」を書いて返すと、Claudeが立て直しやすくなります。

4. 重い処理はサブエージェントに分離

テスト実行やログ分析など、出力が大きくなる処理はサブエージェントに任せましょう。メインエージェントのコンテキストが圧迫されるのを防げます。

5. プロンプトは具体的に

「コードを改善して」ではなく「auth.pyのログイン関数にレート制限を追加して、テストも書いて」のように具体的に指示すると、効率よく動きます。

まとめ

Claude Agent SDKは、AIエージェント開発のハードルを大きく下げるフレームワークです。Claude Codeと同じエンジンを使って、自律的にタスクを実行するエージェントをPythonやTypeScriptで構築できます。

まずはClaude Codeを使って対話的にエージェントの動きを体験し、自動化の必要が出てきたらAgent SDKへ移行する——という段階的なアプローチがおすすめです。

なお、ループやサンドボックス、状態管理を自前で運用したくない場合は、Anthropicがフルマネージドで提供する選択肢としてClaude Managed Agentsがあります。

Claudeの基本的な使い方については、Claudeのチャット・Cowork・コードの違いもあわせてご覧ください。