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

「AIに指示を出したら、あとは自動で考えて作業を進めてくれたら……」。そんな理想を実現するのがAIエージェントです。Anthropicが提供するClaude Agent SDKは、Claudeを頭脳としたAIエージェントをPythonやTypeScriptで構築できるフレームワーク。実際にClaude Code（Anthropic公式CLI）の内部でも使われている技術です。

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

AIエージェントとは？

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

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

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

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

Claude Agent SDKの概要

Claude Agent SDKは、Anthropicが公式に提供するエージェント開発フレームワークです。Claude Codeを動かしているのと同じエンジンをプログラムから利用できます。

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

Claudeのチャット・Cowork・コード3つのモードのうち、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

最小限のエージェント（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)
            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がファイルを読み、バグを探し、修正し、結果を報告するエージェントが動きます。

組み込みツール一覧

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

これらのツールは 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サーバーとして作成し、エージェントに接続します。エラー時は例外をスローせず isError: true を返すのがポイント。そうすることでエージェントのループが止まらず、Claudeがリトライや別のアプローチを試みます。

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

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

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

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

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

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

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

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

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

Agent SDK vs Client SDK vs Claude Code

Claudeには3つの開発者向けインターフェースがあります。それぞれ得意分野が異なるので、目的に応じて使い分けましょう。

迷ったらこう選ぶ：

• 日常の開発作業 → Claude Code CLI
• 自動化システムを構築したい → Agent SDK
• 独自のAIアプリを作りたい → Client SDK

実践的な活用シーン

コード開発の自動化

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

# バグ修正の自動化
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/max）
)

2. ツールは最小限に

使わないツールまで許可すると、コンテキストウィンドウを無駄に消費します。タスクに必要なツールだけを allowed_tools で指定しましょう。

3. エラーハンドリングはisErrorで

カスタムツールでエラーが起きたとき、例外をスローするとエージェントのループ全体が止まります。代わりに isError: true を返せば、Claudeがリカバリーを試みます。

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

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

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

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

まとめ

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

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

Claudeの基本的な使い方については、Claudeの「チャット・Cowork・コード」3つのタブ徹底比較もあわせてご覧ください。