---
title: "Claude Agent SDKの使い方入門【2026年最新】"
description: "Claude Agent SDKの基礎・セットアップ・実践チュートリアルを現役開発者が徹底解説。コードレビューエージェントの構築からコスト管理まで完全ガイド。"
url: "https://shiftb.dev/articles/claude-agent-sdk-guide"
publishedAt: "2026-04-08"
updatedAt: "2026-04-08"
author: "立川修平（ぶべ）"
category: "ai-development"
tags: ["Claude Agent SDK", "AIエージェント", "Claude Code", "AI駆動開発", "個人開発"]
---

# 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エージェントを作っていきましょう。

## 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エージェントの違いの比較図](https://shiftb.dev/images/articles/claude-agent-sdk-guide-comparison.png)

### 個人開発者が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_reason`が`end_turn`になるまで自動的に繰り返されます。開発者は「何をしてほしいか」を伝えるだけで、**「どうやるか」はClaudeが自分で考えてくれる**のです。

![Claude Agent SDKのエージェントループアーキテクチャ](https://shiftb.dev/images/articles/claude-agent-sdk-guide-architecture.png)

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

### 前提条件と必要なもの

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

| 必要なもの | Python版 | TypeScript版 |
| --- | --- | --- |
| ランタイム | Python 3.10以上 | Node.js 18以上 |
| パッケージマネージャー | pip / uv | npm / 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エージェントを作ってみよう

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

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

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

| パラメータ | 型 | 説明 | 必須 |
| --- | --- | --- | --- |
| `prompt` | str | Claudeに実行してほしいタスクの指示 | はい |
| `options.allowedTools` | list | 使用を許可するツールのリスト | いいえ |
| `options.permissionMode` | str | 権限モード（後述） | いいえ |
| `options.model` | str | 使用するモデル（claude-sonnet-4-6など） | いいえ |
| `options.maxTurns` | int | 最大ターン数（無限ループ防止） | いいえ |
| `options.systemPrompt` | str | エージェントのカスタムシステムプロンプト | いいえ |

### メッセージタイプの理解

`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 | テキスト検索 | 低 | コード内キーワード検索 |
| WebSearch | Web検索 | 低 | 最新情報の取得 |
| WebFetch | Webページ取得 | 低 | ドキュメント参照 |

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

エージェントに何を許可するかは、**セキュリティと利便性のバランス**で決めます。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サーバーの作り方ガイド](https://shiftb.dev/articles/mcp-server-guide)で詳しく解説しています。

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

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

### 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ツールを追加）
- **レビュールールのカスタマイズ**：チームのコーディング規約に合わせたプロンプトに変更

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

### サブエージェントとは

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

たとえば、「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側が処理してくれる点です。自分で実装するのは「何をしてほしいか」のプロンプトと、結果の処理だけです。プログラミングの基礎に不安がある方は、まず[個人開発の始め方ロードマップ](https://shiftb.dev/articles/how-to-start-indie-dev)から始めてみてください。

### 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を使いこなすことで、個人開発の生産性を飛躍的に向上させることができます。

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