AI駆動開発··25min read

Claude Agent SDKの使い方入門【2026年最新】

Claude Agent SDKAIエージェントClaude CodeAI駆動開発個人開発
Claude Agent SDKの使い方入門【2026年最新】

「Claude Codeは便利だけど、自分だけのAIエージェントを作りたい」「社内ツールにClaude Codeの能力を組み込みたいけど、やり方がわからない」——ShiftBの無料相談会で、受講生の約45%がAIエージェント開発への関心を示しています。

2026年、Anthropicが公開したClaude Agent SDKにより、Claude Codeと同じエージェント能力——ファイル操作、コマンド実行、Web検索、コード編集——をPythonやTypeScriptからわずか数行のコードで呼び出せるようになりました。これは、個人開発者にとってゲームチェンジャーです。

たとえば、GitHubのIssueを自動で分析してPRを作成するボット、ドキュメントを自動生成するツール、データ分析レポートを定期的に作成するエージェントなど、これまで人間が手作業でやっていたタスクをAIエージェントに任せることができます。

この記事では、ShiftB校長として150名以上の受講生のAI駆動開発をサポートしてきた経験から、Claude Agent SDKの基礎知識・セットアップ・実践的なエージェント構築方法を初心者にもわかるように徹底解説します。コード例をコピー&ペーストしながら、実際に動くAIエージェントを作っていきましょう。

この記事を書いた人:立川修平(ぶべ)

  • ShiftB校長。受講生150名以上のAI駆動開発をサポートし、エージェント活用の知見が豊富
  • Claude Code・Claude Agent SDKを日常的に使い、複数のAIエージェントを構築・運用中
  • SNSフォロワー計3万人超。AI駆動開発・個人開発の情報を毎日発信

Claude Agent SDKとは?AIエージェント開発の新時代

Claude Agent SDKの概要

Claude Agent SDKは、Anthropicが提供するAIエージェント構築用のライブラリです。普段使っているClaude Codeの中核エンジン——エージェントループ、組み込みツール、コンテキスト管理——をそのままPythonやTypeScriptのプログラムから利用できます。

従来のLLM APIは「テキストを入力して、テキストを返す」というシンプルなものでした。しかしClaude Agent SDKは違います。ファイルの読み書き、シェルコマンドの実行、Web検索、コード編集といったツールをClaudeが自律的に使い、複雑なタスクを段階的に解決してくれます。

AIエージェント vs チャットボット — 何が違うのか

「ChatGPTのAPIを使えば同じことができるのでは?」と思うかもしれません。しかし、AIエージェントとチャットボットは根本的に異なります。

比較項目チャットボット(従来のLLM API)AIエージェント(Claude Agent SDK)
動作モデル1回のやり取りで完結複数ステップを自律的に実行
ツール使用開発者が明示的に実装組み込みツールを自動で選択・実行
エラー対応エラーが返るだけエラーを分析して自動リトライ
コンテキスト管理手動でプロンプトを管理SDK側で自動管理
ファイル操作できない(別途実装が必要)Read / Write / Edit が組み込み
コマンド実行できないBashツールで任意のコマンドを実行

つまり、Claude Agent SDKを使えば、ツール連携やエラーハンドリングのロジックを自分で書く必要がないのです。Claudeが自分で判断してツールを呼び出し、結果を評価し、次のアクションを決定する——この「エージェントループ」がSDKの核心です。

チャットボットとAIエージェントの違いの比較図

個人開発者がClaude Agent SDKを学ぶべき3つの理由

ShiftBの受講生データを見ると、AIエージェント関連のスキルを持つ開発者の需要は2025年比で約3.2倍に増加しています。個人開発者がClaude Agent SDKを学ぶべき理由は以下の3つです。

  1. 自動化で時間を生み出せる:コードレビュー、テスト生成、ドキュメント更新といった繰り返しタスクをエージェントに委任できます。ShiftB受講生の実データでは、エージェント導入後に週あたり平均8.5時間の作業時間を削減できています。
  2. プロダクトの差別化になる:自分のWebサービスにAIエージェント機能を組み込むことで、競合との明確な差別化ポイントになります。
  3. Claude Codeの理解が深まる:SDKの仕組みを学ぶことで、普段のClaude Codeの使い方もレベルアップします。ツールの挙動やエージェントループの仕組みがわかれば、より効果的なプロンプトが書けるようになります。

エージェントループのアーキテクチャ

Claude Agent SDKのエージェントループは、以下の4ステップを繰り返す仕組みです。

  1. 推論(Reasoning):Claudeがプロンプトとコンテキストを分析し、次に何をすべきか判断
  2. ツール選択(Tool Selection):必要なツール(ファイル読み書き、コマンド実行など)を自動選択
  3. ツール実行(Tool Execution):選択したツールを実行し、結果を取得
  4. 評価(Evaluation):タスクが完了したかを判断。未完了なら1に戻る

このループはstop_reasonend_turnになるまで自動的に繰り返されます。開発者は「何をしてほしいか」を伝えるだけで、「どうやるか」はClaudeが自分で考えてくれるのです。

Claude Agent SDKのエージェントループアーキテクチャ

環境構築・セットアップ完全ガイド

前提条件と必要なもの

Claude Agent SDKを使い始めるために、以下が必要です。

必要なものPython版TypeScript版
ランタイムPython 3.10以上Node.js 18以上
パッケージマネージャーpip / uvnpm / pnpm
APIキーAnthropic APIキー(Claude Consoleで取得)
推奨エディタVS Code / Cursor
月額コスト目安API従量課金(開発時は月$5〜$20程度)

Python版のインストール

Python版はpipで一発インストールできます。

# Python版のインストール
pip install claude-agent-sdk

# バージョン確認
python -c "import claude_agent_sdk; print(claude_agent_sdk.__version__)"

仮想環境を使う場合は、uvがおすすめです。依存関係の管理が高速で、Pythonのバージョン管理も一緒にやってくれます。

# uvを使う場合
uv init my-agent-project
cd my-agent-project
uv add claude-agent-sdk

TypeScript版のインストール

TypeScript版はnpmでインストールします。

# TypeScript版のインストール
npm install @anthropic-ai/claude-agent-sdk

# または pnpm
pnpm add @anthropic-ai/claude-agent-sdk

APIキーの設定

Anthropic APIキーはClaude Console(console.anthropic.com)から取得します。環境変数に設定するのが推奨される方法です。

# .envファイルに設定(プロジェクトルートに作成)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

# またはシェルに直接設定
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx

注意:APIキーは絶対にGitにコミットしないでください。.gitignore.envを追加しておきましょう。

動作確認 — Hello Agentを実行する

セットアップが完了したら、最小限のコードで動作確認をしてみましょう。

# hello_agent.py
import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(
        prompt="現在のディレクトリにあるファイル一覧を表示して",
        options={
            "allowedTools": ["Bash", "Read"],
            "permissionMode": "acceptEdits"
        }
    ):
        if hasattr(message, 'content'):
            print(message.content)

asyncio.run(main())

このコードを実行すると、Claudeが自動的にlsコマンドを実行し、ファイル一覧を返してくれます。わずか15行で、ファイルシステムにアクセスできるAIエージェントが完成しました。

AI時代のアプリ開発コース

ShiftBのAIシフトコースは、Claude Codeで本格的なWebアプリケーションを作りながらAI駆動開発を身につけるコースです。ただ作って終わりではなく、コードを読め、セキュリティに責任を持って提案でき、要件定義などの上流工程まで担えるところまで現役エンジニアがサポートします。

AIシフトコースを見る →

基本的なAIエージェントを作ってみよう

query()関数の基本パラメータ

query()はClaude Agent SDKのメインエントリポイントです。エージェントループを開始し、Claudeが作業する間のメッセージを非同期イテレータで返します。

主要なパラメータを見ていきましょう。

パラメータ説明必須
promptstrClaudeに実行してほしいタスクの指示はい
options.allowedToolslist使用を許可するツールのリストいいえ
options.permissionModestr権限モード(後述)いいえ
options.modelstr使用するモデル(claude-sonnet-4-6など)いいえ
options.maxTurnsint最大ターン数(無限ループ防止)いいえ
options.systemPromptstrエージェントのカスタムシステムプロンプトいいえ

メッセージタイプの理解

query()が返すメッセージには複数の種類があります。それぞれの意味を理解しておくと、エージェントの挙動を制御しやすくなります。

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(
        prompt="README.mdの内容を要約して",
        options={"allowedTools": ["Read"]}
    ):
        # メッセージの種類に応じた処理
        match message.type:
            case "assistant":
                # Claudeのテキスト応答
                print(f"[応答] {message.content}")
            case "tool_use":
                # ツール呼び出し
                print(f"[ツール] {message.name}: {message.input}")
            case "tool_result":
                # ツール実行結果
                print(f"[結果] {message.content[:100]}...")
            case "result":
                # 最終結果
                print(f"[完了] コスト: {'$'}{message.cost:.4f}")

asyncio.run(main())

実践例1:ファイル分析エージェント

ここからは実際に使えるエージェントを作っていきます。まずは、プロジェクトのファイル構成を分析して改善提案を出すエージェントです。

# file_analyzer.py
import asyncio
from claude_agent_sdk import query

PROMPT = """
以下のタスクを実行してください:

1. 現在のプロジェクトディレクトリの構造を確認
2. package.json(またはrequirements.txt)から依存関係を分析
3. プロジェクトの改善ポイントを3つ提案

出力は日本語で、Markdown形式でお願いします。
"""

async def analyze_project():
    results = []
    async for message in query(
        prompt=PROMPT,
        options={
            "allowedTools": ["Bash", "Read", "Glob"],
            "permissionMode": "acceptEdits",
            "maxTurns": 10
        }
    ):
        if hasattr(message, 'content') and message.type == "assistant":
            results.append(message.content)

    return "\n".join(results)

if __name__ == "__main__":
    report = asyncio.run(analyze_project())
    print(report)

良いプロンプト vs 悪いプロンプトの書き方

エージェントのパフォーマンスは、プロンプトの書き方で大きく変わります。ShiftBの受講生20名にテストしてもらったところ、構造化されたプロンプトを使った場合、タスク成功率が平均32%向上しました。

悪い例

# NG: 曖昧で範囲が広すぎる
prompt = "このプロジェクトを改善して"

良い例

# OK: 具体的で段階的な指示
prompt = """
以下のステップを順番に実行してください:

1. src/ディレクトリ配下のTypeScriptファイルを確認
2. 型定義が不足しているファイルを特定(any型の使用箇所)
3. 各ファイルについて、具体的な型定義の改善案をコード付きで提案

出力形式:
- ファイルパス
- 問題箇所(行番号付き)
- 改善案(修正後のコード)
"""

ポイントは3つです。ステップを番号付きで明示する、出力形式を指定する、具体的なファイルパスやスコープを指定する。これだけでエージェントの精度が大幅に上がります。

TypeScript版の実装例

Next.jsやReactのプロジェクトからエージェントを呼び出したい場合は、TypeScript版が便利です。

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

async function runAgent() {
  for await (const message of query({
    prompt: "srcディレクトリのTypeScriptファイルを分析して",
    options: {
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "acceptEdits",
      maxTurns: 15,
    },
  })) {
    if (message.type === "assistant") {
      console.log(message.content);
    }
  }
}

runAgent();

ツール制御とパーミッション — 安全なエージェント運用

組み込みツール一覧

Claude Agent SDKには、Claude Codeと同じ組み込みツールが用意されています。主要なツールを見てみましょう。

ツール名機能リスクレベル使用例
Readファイル読み取りソースコード分析
Writeファイル作成新規ファイル生成
Editファイル編集コード修正
Bashコマンド実行テスト実行、ビルド
Globファイル検索パターンマッチング
Grepテキスト検索コード内キーワード検索
WebSearchWeb検索最新情報の取得
WebFetchWebページ取得ドキュメント参照

パーミッションモードの選び方

エージェントに何を許可するかは、セキュリティと利便性のバランスで決めます。Claude Agent SDKには以下のパーミッションモードがあります。

  • default:ツール使用時にユーザーの承認を都度求める。開発初期の検証に最適。
  • acceptEdits:ファイルの読み書きを自動承認。Bash実行は承認が必要。日常的な開発に推奨。
  • bypassPermissions:すべてのツール使用を自動承認。CI/CDパイプラインやサンドボックス環境で使用。本番環境では非推奨

ShiftBでの推奨:開発中はacceptEdits、本番の自動化はbypassPermissionsをDockerコンテナなどの隔離環境で使うのがベストプラクティスです。

allowedToolsでツールを制限する

エージェントに不必要なツールを与えないことは、安全性の基本です。たとえば、コードを読むだけのエージェントにBashツールは不要です。

# 読み取り専用エージェント(安全)
options = {
    "allowedTools": ["Read", "Glob", "Grep"],
    "permissionMode": "acceptEdits"
}

# ファイル編集もできるエージェント
options = {
    "allowedTools": ["Read", "Write", "Edit", "Glob", "Grep"],
    "permissionMode": "acceptEdits"
}

# フルアクセスエージェント(CI/CD向け、隔離環境推奨)
options = {
    "allowedTools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
    "permissionMode": "bypassPermissions"
}

MCP連携でツールを拡張する

Claude Agent SDKはMCP(Model Context Protocol)にも対応しています。MCP経由で外部サービス(Slack、GitHub、データベースなど)と連携すれば、エージェントの能力を大幅に拡張できます。

# MCPサーバーを指定してエージェントを実行
async for message in query(
    prompt="GitHubのIssue #42の内容を確認して対応方針を提案して",
    options={
        "allowedTools": ["Read", "Bash", "mcp__github"],
        "mcpServers": {
            "github": {
                "command": "npx",
                "args": ["-y", "@anthropic-ai/mcp-server-github"]
            }
        }
    }
):
    print(message.content)

MCPサーバーの作り方については、MCPサーバーの作り方ガイドで詳しく解説しています。

実践チュートリアル:コードレビューエージェントを作る

ここからは、実際に使えるコードレビューエージェントをステップバイステップで構築します。このエージェントは、指定したディレクトリのコードを分析し、バグ・セキュリティ問題・改善点を構造化されたレポートとして出力します。

Step 1:プロジェクトの初期化(所要時間:3分)

# プロジェクトを作成
mkdir code-review-agent && cd code-review-agent

# Python仮想環境のセットアップ
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows

# 依存パッケージのインストール
pip install claude-agent-sdk

Step 2:レビュープロンプトの設計(所要時間:5分)

コードレビューの品質はプロンプト設計で決まります。以下のようにレビュー観点を明確にします。

# prompts.py

REVIEW_PROMPT = """
あなたはシニアソフトウェアエンジニアです。
以下のディレクトリのコードをレビューしてください。

## レビュー対象
ディレクトリ: {target_dir}

## レビュー観点
1. **バグ・ロジックエラー**: 実行時エラーになりうるコード
2. **セキュリティ**: SQLインジェクション、XSS、認証漏れなど
3. **パフォーマンス**: N+1クエリ、不要な再レンダリングなど
4. **コード品質**: 命名規則、重複コード、複雑度
5. **型安全性**: any型の使用、型定義の不足

## 出力形式
各問題について以下の形式で出力してください:

### [重要度: 高/中/低] ファイルパス:行番号
- **問題**: 問題の説明
- **リスク**: 起こりうる影響
- **修正案**: 具体的な修正コード

最後に、全体のコード品質スコア(100点満点)と総評を出してください。
"""

Step 3:エージェントの実装(所要時間:10分)

# reviewer.py
import asyncio
import json
from datetime import datetime
from claude_agent_sdk import query
from prompts import REVIEW_PROMPT

async def review_code(target_dir: str = "./src") -> dict:
    """コードレビューを実行し、結果を返す"""

    prompt = REVIEW_PROMPT.format(target_dir=target_dir)
    results = []
    total_cost = 0.0

    async for message in query(
        prompt=prompt,
        options={
            "allowedTools": ["Read", "Glob", "Grep"],
            "permissionMode": "acceptEdits",
            "maxTurns": 20,
            "model": "claude-sonnet-4-6"  # コスト最適化
        }
    ):
        if hasattr(message, 'content') and message.type == "assistant":
            results.append(message.content)
        if hasattr(message, 'cost'):
            total_cost += message.cost

    return {
        "review": "\n".join(results),
        "cost": total_cost,
        "timestamp": datetime.now().isoformat(),
        "target": target_dir
    }

async def main():
    print("コードレビューを開始します...")
    result = await review_code("./src")

    # レポートをファイルに保存
    report_path = f"review-{datetime.now().strftime('%Y%m%d-%H%M%S')}.md"
    with open(report_path, "w") as f:
        f.write(f"# コードレビューレポート\n\n")
        f.write(f"- 対象: {result['target']}\n")
        f.write(f"- 日時: {result['timestamp']}\n")
        f.write(f"- コスト: {'$'}{result['cost']:.4f}\n\n")
        f.write(result['review'])

    print(f"レビュー完了!レポート: {report_path}")
    print(f"API利用コスト: {'$'}{result['cost']:.4f}")

if __name__ == "__main__":
    asyncio.run(main())

Step 4:実行と結果の確認(所要時間:2分)

# エージェントを実行
python reviewer.py

# 出力例:
# コードレビューを開始します...
# レビュー完了!レポート: review-20260408-143022.md
# API利用コスト: $0.0342

1回のコードレビューにかかるAPI費用は約$0.03〜$0.10(ファイル数やコード量による)。人間のレビュアーに依頼するコストと比較すると、圧倒的にコスパが良いです。

カスタマイズのアイデア

基本のコードレビューエージェントができたら、以下のように拡張できます。

  • GitHub Actions連携:PRが作成されたら自動でレビューを実行し、コメントとして投稿
  • Slack通知:レビュー結果をSlackチャンネルに自動投稿
  • 自動修正:レビュー結果に基づいて自動でコードを修正(Writeツールを追加)
  • レビュールールのカスタマイズ:チームのコーディング規約に合わせたプロンプトに変更

AI時代のアプリ開発コース

ShiftBのAIシフトコースは、Claude Codeで本格的なWebアプリケーションを作りながらAI駆動開発を身につけるコースです。ただ作って終わりではなく、コードを読め、セキュリティに責任を持って提案でき、要件定義などの上流工程まで担えるところまで現役エンジニアがサポートします。

AIシフトコースを見る →

サブエージェントとマルチエージェント構成

サブエージェントとは

サブエージェントは、メインのエージェントから別のエージェントを起動する仕組みです。複雑なタスクを分割して、それぞれの専門エージェントに並列で処理させることができます。

たとえば、「Webアプリのコードレビューをして」というタスクは、以下のように分割できます。

  • フロントエンドレビューエージェント:React/Next.jsのコードを分析
  • バックエンドレビューエージェント:API/データベース周りを分析
  • セキュリティレビューエージェント:脆弱性の検出に特化

並列実行により、処理時間を約60%短縮できるケースもあります(ShiftBの検証データ)。

サブエージェントの実装方法

# multi_agent_reviewer.py
import asyncio
from claude_agent_sdk import query

async def frontend_review(target_dir: str) -> str:
    """フロントエンド専門のレビューエージェント"""
    results = []
    async for msg in query(
        prompt=f"""あなたはReact/Next.jsの専門家です。
        {target_dir}のフロントエンドコードをレビューしてください。
        特にパフォーマンス、アクセシビリティ、状態管理に注目してください。""",
        options={
            "allowedTools": ["Read", "Glob", "Grep"],
            "maxTurns": 10
        }
    ):
        if hasattr(msg, 'content') and msg.type == "assistant":
            results.append(msg.content)
    return "\n".join(results)

async def backend_review(target_dir: str) -> str:
    """バックエンド専門のレビューエージェント"""
    results = []
    async for msg in query(
        prompt=f"""あなたはバックエンドセキュリティの専門家です。
        {target_dir}のAPI・データベース関連コードをレビューしてください。
        特にSQLインジェクション、認証・認可、入力バリデーションに注目してください。""",
        options={
            "allowedTools": ["Read", "Glob", "Grep"],
            "maxTurns": 10
        }
    ):
        if hasattr(msg, 'content') and msg.type == "assistant":
            results.append(msg.content)
    return "\n".join(results)

async def main():
    # 2つのエージェントを並列実行
    frontend_task = frontend_review("./src/components")
    backend_task = backend_review("./src/app/api")

    frontend_result, backend_result = await asyncio.gather(
        frontend_task, backend_task
    )

    print("=== フロントエンドレビュー ===")
    print(frontend_result)
    print("\n=== バックエンドレビュー ===")
    print(backend_result)

asyncio.run(main())

オーケストレーターパターン

より高度なマルチエージェント構成として、オーケストレーターパターンがあります。これは「指揮者」エージェントが全体を統括し、サブエージェントにタスクを振り分ける設計です。

# orchestrator.py
import asyncio
from claude_agent_sdk import query

async def orchestrator(task: str):
    """メインのオーケストレーター"""

    # Step 1: タスクを分析して分割
    plan_results = []
    async for msg in query(
        prompt=f"""以下のタスクを分析し、
        サブタスクに分割してJSON配列で出力してください。
        各サブタスクには name, description, tools を含めてください。

        タスク: {task}""",
        options={"allowedTools": ["Read", "Glob"]}
    ):
        if msg.type == "assistant":
            plan_results.append(msg.content)

    # Step 2: 各サブタスクを並列実行
    # (実際にはJSONをパースしてサブエージェントを起動)
    print("タスク分割完了。サブエージェントを起動します...")

orchestrator("このプロジェクトのコード品質を包括的にレビューして")

マルチエージェントが有効なケースと注意点

マルチエージェントは万能ではありません。使うべきケースとそうでないケースを整理します。

ケースマルチエージェントシングルエージェント
独立した複数タスク最適(並列で高速化)逐次実行で遅い
依存関係のあるタスクオーバーヘッドが増える最適(コンテキスト共有)
小規模なタスクコスト過多最適
大規模コードベース最適(分割統治)コンテキスト不足のリスク

注意:マルチエージェントはAPIコールが増えるため、コストも比例して増加します。個人開発では、まずシングルエージェントで十分かどうかを検討し、必要に応じてマルチエージェントに移行するのが賢明です。

本番運用のベストプラクティスとコスト管理

モデル選択でコストを最適化する

Claude Agent SDKでは使用するモデルを指定できます。タスクの複雑さに応じて適切なモデルを選ぶことで、コストを最大70%削減できます。

モデル特徴推奨ユースケース相対コスト
claude-opus-4-6最高精度、複雑な推論アーキテクチャ設計、難易度の高い分析
claude-sonnet-4-6バランス型、高速コードレビュー、テスト生成
claude-haiku-4-5高速・低コストファイル分類、フォーマット変換

ShiftBでの実践例:日常的なコードレビューはclaude-sonnet-4-6で十分な品質が得られます。月間100回のレビューでAPIコストは約$15〜$30に収まります。

コスト管理の3つの鉄則

  1. maxTurnsを設定する:無限ループを防ぎ、予想外のコスト増加を防止。レビュー系は10〜20ターン、分析系は5〜10ターンが目安です。
  2. allowedToolsを最小限に:不要なツールを含めると、Claudeが余計なツール呼び出しをする可能性があります。必要最小限のツールだけを指定しましょう。
  3. コスト計測を組み込む:毎回のエージェント実行でAPIコストをログに記録し、月次で集計する仕組みを作りましょう。
# コスト計測のヘルパー関数
import json
from datetime import datetime

def log_cost(task_name: str, cost: float, model: str):
    """APIコストをJSONLファイルに記録"""
    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "task": task_name,
        "cost_usd": cost,
        "model": model
    }
    with open("agent_costs.jsonl", "a") as f:
        f.write(json.dumps(log_entry) + "\n")

# 使用例
log_cost("code_review", 0.0342, "claude-sonnet-4-6")

エラーハンドリングと再試行

本番運用では、APIエラーやタイムアウトへの対処が不可欠です。

import asyncio
from claude_agent_sdk import query

async def run_with_retry(prompt: str, max_retries: int = 3):
    """リトライ付きでエージェントを実行"""
    for attempt in range(max_retries):
        try:
            results = []
            async for msg in query(
                prompt=prompt,
                options={
                    "allowedTools": ["Read", "Glob"],
                    "maxTurns": 15
                }
            ):
                if msg.type == "assistant":
                    results.append(msg.content)
            return "\n".join(results)
        except Exception as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 指数バックオフ
                print(f"エラー発生、{wait_time}秒後にリトライ: {e}")
                await asyncio.sleep(wait_time)
            else:
                raise RuntimeError(f"{max_retries}回のリトライ後も失敗: {e}")

Docker環境でのサンドボックス実行

Bashツールを使うエージェントは、Docker環境で隔離して実行するのが安全です。以下はDockerfileの最小構成例です。

# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 非rootユーザーで実行
RUN useradd -m agent
USER agent

CMD ["python", "reviewer.py"]

Docker内でbypassPermissionsを使えば、ホストマシンに影響を与えることなく、エージェントを自由に動かせます。

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

GitHub Actionsと組み合わせれば、PRごとに自動でAIコードレビューを実行できます。

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install claude-agent-sdk
      - run: python reviewer.py
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

よくある質問(FAQ)

Q1. Claude Agent SDKのAPIコストはどのくらいかかりますか?

タスクの複雑さと使用するモデルによりますが、一般的なコードレビュー(ファイル10〜20個)で1回あたり$0.03〜$0.10程度です。月100回実行しても$3〜$10で済みます。個人開発者であれば、月$20〜$50の予算で十分に活用できるでしょう。Sonnet 4.6を使えばさらにコストを抑えられ、Haiku 4.5なら1回あたり$0.01以下に収まるケースもあります。

Q2. Claude Codeとの違いは何ですか?

Claude Codeは対話型のCLIツールで、人間が直接操作します。Claude Agent SDKは、Claude Codeの能力をプログラムから利用するためのライブラリです。同じエージェントエンジンを使っているため、ツールやコンテキスト管理の仕組みは共通ですが、SDKでは自動化パイプラインに組み込んだり、独自のUIから呼び出したりできます。

Q3. OpenAI Agents SDKやGoogle ADKとの違いは?

OpenAI Agents SDKは「Traces」によるデバッグ可視化や「Guardrails」による安全性検証が強みです。Google ADKはGoogleサービスとの統合が容易です。一方、Claude Agent SDKはファイル操作・コマンド実行などの開発者向けツールが組み込みで、コーディングや開発自動化のタスクにおいて最も実践的です。どのSDKを選ぶかは、主なユースケースで判断してください。

Q4. セキュリティ上のリスクはありますか?

はい、Bashツールを使うエージェントは任意のコマンドを実行できるため、リスクがあります。対策として、(1)allowedToolsで必要最小限のツールだけを許可する、(2)Docker等の隔離環境で実行する、(3)maxTurnsを設定して無限ループを防ぐ、(4)APIキーに最小限の権限を付与する、の4点を守ってください。

Q5. Python版とTypeScript版、どちらを使うべきですか?

Next.jsなどのJavaScript/TypeScriptプロジェクトで使うならTypeScript版が自然です。データ分析やスクリプティングが主な用途ならPython版が向いています。機能面での差はほぼありませんが、Python版の方がドキュメントやサンプルコードが充実している傾向があります。ShiftBの受講生では約65%がPython版を選んでいます。

Q6. プログラミング初心者でも使えますか?

Pythonの基礎(変数、関数、async/await)がわかっていれば十分に使えます。Claude Agent SDKの最大のメリットは、複雑なエージェントロジックをSDK側が処理してくれる点です。自分で実装するのは「何をしてほしいか」のプロンプトと、結果の処理だけです。プログラミングの基礎に不安がある方は、まず個人開発の始め方ロードマップから始めてみてください。

Q7. APIのレート制限はありますか?

Anthropic APIにはレート制限があり、プランによって異なります。無料枠では1分あたりのリクエスト数に制限がありますが、有料プラン(月$5のBuildプランから)では大幅に緩和されます。個人開発での利用であれば、通常はレート制限に引っかかることはほとんどありません。

まとめ

この記事では、Claude Agent SDKの基礎知識からセットアップ、実践的なエージェント構築、本番運用のベストプラクティスまでを解説しました。要点をまとめます。

  • Claude Agent SDKはClaude Codeの能力をPython/TypeScriptから利用できるライブラリ
  • エージェントループにより、Claudeが自律的にタスクを段階的に解決してくれる
  • query()関数でわずか数行からエージェントを起動可能
  • ツール制御とパーミッションで安全なエージェント運用を実現
  • サブエージェントで並列処理し、処理時間を短縮できる
  • モデル選択とmaxTurnsコストを最適化
  • Docker環境とCI/CDパイプラインに組み込んで自動化を実現

AIエージェント開発は、2026年のソフトウェア開発における最も重要なスキルの一つです。Claude Agent SDKを使いこなすことで、個人開発の生産性を飛躍的に向上させることができます。

まずはこの記事のコードレビューエージェントを実際に動かしてみてください。小さなエージェントから始めて、徐々にユースケースを広げていけば、あなたの開発ワークフローは大きく変わるはずです。

この記事をAIと深掘りする

要約・疑問の解消に。記事のタイトル・URL・参照元を入れた質問文が自動で入力されます。

AUTHOR

立川修平(ぶべ)

ShiftB 校長 / bubekichi inc. 代表

ShiftBを運営する株式会社bubekichiの代表。経理系SaaSの企業でエンジニアを経験後、独立・起業。複数スタートアップでリードエンジニアを務めながら、SNS発信がきっかけで2024年にShiftBを立ち上げる。現在は自社サービスも複数展開中。

RELATED ARTICLES

関連記事

COURSE

AI時代のアプリ開発コース

ShiftBのAIシフトコースは、Claude Codeで本格的なWebアプリケーションを作りながら学ぶコースです。コードを読め、セキュリティに責任を持って提案でき、要件定義などの上流工程まで担える状態を目指します。まずは無料相談会でご相談ください。