本記事で扱うCookbookの中でも特に重要なClaude Agent SDKについて、基本から解説した記事を用意しています。Agent SDKに馴染みのない方は、まずそちらを読んでからこの記事に戻ると理解がスムーズです。
Claude APIの使い方を学ぶなら、Anthropic公式のClaude Cookbooksが最良の教材です。全65本のJupyter Notebookで構成されたこのリポジトリには、RAG、ツール利用、マルチモーダル、エージェント構築など、実務で使える実践パターンが網羅されています。
なお、CookbookのすべてのノートブックはAnthropic APIキーが必要ですが、claude_agent_sdk/ディレクトリのノートブックは内部的にClaude Code CLIを経由するため、Pro/Maxサブスクリプションでも動作します。
この記事では、全12ディレクトリ・65ノートブックの内容を1本ずつ解説します。
リポジトリの全体構成
claude-cookbooks/
├── capabilities/ # RAG・分類・要約・Text-to-SQL・埋め込み (5本)
├── tool_use/ # ツール利用パターン (12本)
├── misc/ # プロンプトキャッシュ・バッチ処理・JSONモードなど (14本)
├── multimodal/ # 画像認識・PDF処理 (6本)
├── claude_agent_sdk/ # Agent SDK によるエージェント構築 (3本)
├── patterns/agents/ # エージェントワークフローパターン (3本)
├── extended_thinking/ # 拡張思考 (2本)
├── skills/ # Claude Skills の活用 (3本)
├── third_party/ # 外部サービス連携 (13本)
├── finetuning/ # ファインチューニング (1本)
├── coding/ # フロントエンドデザイン (1本)
├── observability/ # コスト・使用量API (1本)
└── tool_evaluation/ # ツール評価フレームワーク (1本)
すべてのNotebookは上から下まで実行可能で、コピー&ペーストですぐに試せます。
セットアップ
uv sync --all-extras # 依存関係インストール
cp .env.example .env # APIキー設定
1. capabilities/ — Claude の中核機能を活かす5つのガイド
1-1. Classification（分類）
保険サポートチケットを10カテゴリに分類するシステムを、段階的に精度向上させるガイドです。
段階ごとの精度推移が印象的です。
| 手法 | 精度 |
|---|---|
| ベースライン（ランダム） | 約10% |
| シンプルな分類プロンプト | 約70% |
| RAG（類似事例5件検索） | 94% |
| RAG + Chain-of-Thought | 97% |
# XMLタグでカテゴリ定義を構造化
# 出力を<category>タグでprefillし、stop_sequenceで制御
response = client.messages.create(
model="claude-sonnet-4-6",
temperature=0.0,
messages=[{"role": "user", "content": prompt},
{"role": "assistant", "content": "<category>"}],
stop_sequences=["</category>"]
)
VoyageAI埋め込みで類似チケットを検索し、few-shotの例として与える手法は、ラベル付きデータが少ない現場で即実践できます。Promptfooによる体系的な評価も含まれています。
1-2. Retrieval Augmented Generation（RAG）
Claude公式ドキュメントをナレッジベースとしたRAGシステムを3段階で最適化し、end-to-end精度を71%から81%に引き上げます。
| レベル | 手法 | E2E精度 | MRR |
|---|---|---|---|
| 1 | 基本RAG（見出し分割 + コサイン類似度） | 71% | 0.74 |
| 2 | サマリーインデキシング | 78% | — |
| 3 | サマリーインデキシング + リランキング | 81% | 0.87 |
レベル2では各チャンクのサマリーを生成し、見出し + 本文 + サマリーを結合して埋め込むことで検索精度を改善します。レベル3ではClaudeにリランキングをさせ、MRRが0.74から0.87に向上します。
評価フレームワークも充実しており、Precision / Recall / F1 / MRRの4指標を測定します。LLM-as-Judgeパターンで正解判定を自動化しているのも参考になります。
1-3. Summarization（要約）
法的文書（サブリース契約）の要約を題材に、6段階の手法を実演します。
- 基本的な箇条書き要約
- Multi-shot学習（3つの模範例を提示）
- ガイド付き要約（抽出すべきセクションを指定）
- ドメイン固有のガイダンス
- チャンキング + メタ要約（トークン上限超えの長文対応）
- サマリーインデックスRAG（複数文書の横断検索）
ポイントは、XMLタグで出力構造を指定し、<parties involved>や<term and rent>など個別セクションをregexで抽出する手法です。Promptfooで要約品質を自動テストする仕組みも紹介されています。
1-4. Text-to-SQL
自然言語からSQLを生成するシステムを、段階的に洗練させます。
| 手法 | Haiku | Sonnet |
|---|---|---|
| 基本 | 83.3% | — |
| Few-Shot | — | 94.4% |
| CoT + Few-Shot | — | 100% |
| RAG + CoT + Few-Shot | — | 100% |
大規模スキーマにはRAGでスキーマメタデータを検索し、関連テーブルだけをプロンプトに含めます。生成SQLの実行エラーをフィードバックして再生成する自己改善ループも実装されています。
1-5. Contextual Embeddings（文脈付き埋め込み）
チャンクを文書から切り出すと文脈が失われる問題に対し、Claudeで各チャンクに2〜3文の文脈説明を生成してから埋め込む手法です。
| 手法 | Pass@5 | Pass@10 | Pass@20 |
|---|---|---|---|
| ベースラインRAG | 80.92% | 87.15% | 90.06% |
| 文脈付き埋め込み | 88.12% | 92.34% | 94.29% |
| + BM25ハイブリッド検索 | 88.86% | 92.31% | 95.23% |
| + Cohereリランキング | 92.15% | 95.26% | 97.45% |
プロンプトキャッシュ（cache_control: {"type": "ephemeral"}）を使うことで、文脈生成コストを69%削減（$9.20 → $2.85）しているのが実用的です。
2. tool_use/ — ツール利用の12パターン
2-1. calculator_tool（計算ツール）
ツール利用の最小構成です。ツール定義 → API呼び出し → stop_reason == "tool_use" 検出 → ツール実行 → 結果返却の基本ループを学べます。
2-2. customer_service_agent（カスタマーサービスエージェント）
get_customer_info、get_order_details、cancel_orderの3ツールを使った対話型チャットボットです。複数のツールを逐次呼び出すwhile loopパターンが実装されています。
2-3. extracting_structured_json（構造化JSON抽出）
ツール利用を「構造化出力の強制」に転用するテクニックです。記事要約、固有表現認識、感情分析、分類の4パターンを実演します。ツールのスキーマがそのまま出力スキーマになる発想が巧みです。
2-4. tool_choice（ツール選択制御）
tool_choiceパラメータの3モードを解説します。
-
auto— モデルが自由に判断 -
tool（特定ツール強制） — 構造化出力を確実に取得したい場合 -
any（いずれかのツール強制） — チャットボットで必ずツールを使わせたい場合
2-5. parallel_tools（並列ツール呼び出し）
Claudeが複数ツールを同時に呼び出せない場合の回避策として、batch_toolというメタツールを定義し、1回の呼び出しで複数ツールの結果を取得するパターンです。
2-6. tool_use_with_pydantic（Pydantic連携）
Pydanticモデルでツールの入力バリデーションを行う手法です。EmailStrによるメールアドレス検証、Field(ge=1, le=5)による範囲制約など、型安全なツール定義が書けます。
2-7. vision_with_tools（ビジョン + ツール）
画像入力とツール利用を組み合わせ、栄養表示ラベルからカロリー・脂質・タンパク質などの構造化データを抽出します。
2-8. tool_search_with_embeddings（埋め込みベースのツール検索）
数千のツールを持つアプリケーション向けです。ツール定義を埋め込みベクトル化し、ユーザーのクエリに最も関連するツールだけを動的にロードします。全ツールを一度に渡す場合と比べ、コンテキスト使用量を90%以上削減できます。
2-9. tool_search_alternate_approaches（埋め込み不要のツール検索）
埋め込みを使わない軽量な方法です。システムプロンプトにツール名一覧を記載し、describe_toolメタツールで必要なツールの定義をオンデマンドに取得します。defer_loading=Trueでプロンプトキャッシュの無効化を防ぎます。
2-10. programmatic_tool_calling_ptc（プログラマティックツール呼び出し）
Claudeがツールを直接呼ぶ代わりにコードを書いてツールを呼び出すことで、レイテンシとトークン消費を大幅に削減します。100件以上の経費レコードを処理するベンチマークで、トークン使用量が85.6%削減（110,473 → 15,919トークン）されます。
2-11. memory_cookbook（メモリ＆コンテキスト管理）
セッションを跨いで学習するエージェントの構築法です。view、create、str_replace、insert、delete、renameの6コマンドを持つメモリツールを実装し、コードレビューアシスタントがレビューパターンを学習していくデモが含まれます。
2-12. automatic-context-compaction（自動コンテキスト圧縮）
長時間稼働するエージェントのコンテキスト管理です。compaction_controlパラメータで自動圧縮を有効にし、サポートチケット8件の処理で58.6%のトークン削減（204,416 → 82,171トークン）を達成します。
3. misc/ — 14の実用テクニック
3-1. prompt_caching（プロンプトキャッシュ）
キャッシュにより2倍以上の高速化とコスト最大90%削減を実現する手法です。
- 自動キャッシュ: トップレベルに
cache_control={"type": "ephemeral"}を1つ指定 - 明示的ブレークポイント: コンテンツブロックごとに最大4箇所まで指定
- キャッシュ書き込みは基本価格の1.25倍、キャッシュ読み取りは0.1倍
最小キャッシュ可能長はSonnetで1,024トークン、Opus/Haiku 4.5で4,096トークンです。TTLは5分（1時間オプションあり）。
3-2. speculative_prompt_caching（投機的プロンプトキャッシュ）
ユーザーがクエリを入力している間にキャッシュをウォームアップする手法です。max_tokens=1の投機的リクエストを送ってキャッシュを作成し、本番リクエスト時のTTFT（Time-to-First-Token）を90.7%改善（20.87s → 1.94s）します。
3-3. session_memory_compaction（セッションメモリ圧縮）
長い会話のコンテキストをバックグラウンドスレッドで要約する手法です。従来のリアクティブな圧縮（ユーザーが待たされる）に対し、threading.Threadでプロアクティブにメモリ更新を行い、ユーザー体験を損なわずにコンテキストを管理します。
3-4. batch_processing（バッチ処理）
Message Batches APIで大量リクエストを非同期処理し、コストを50%削減します。異なるタイプのリクエスト（テキスト、画像、マルチターン）を1バッチにまとめて送れます。
3-5. building_evals（評価構築）
評価システムの3つのアプローチを解説します。
- コードベース評価 — 文字列完全一致・正規表現
- 人間による評価 — ルーブリック付き手動採点
- モデルベース評価 — Claudeが
<thinking>タグで推論し、<correctness>で採点
3-6. generate_test_cases（テストデータ生成）
プロンプトテンプレートから合成テストケースを自動生成します。テンプレート内の{{変数}}をregexで抽出し、Claudeに多様な入力値を生成させます。
3-7. building_moderation_filter（モデレーションフィルター）
カスタマイズ可能なコンテンツモデレーションシステムの構築法です。カテゴリ定義 → Chain-of-Thought推論 → BLOCK/ALLOW判定のパイプラインに、few-shot例を追加して精度を向上させます。
3-8. how_to_enable_json_mode（JSONモード）
アシスタント応答を{でprefillし、XMLタグで複数JSONオブジェクトをラップして確実にパースする手法です。
messages = [
{"role": "user", "content": "JSONで出力してください: ..."},
{"role": "assistant", "content": "Here is the JSON requested:\n{"}
]
3-9. how_to_make_sql_queries（SQL生成）
データベーススキーマをCREATE TABLE形式で提示し、自然言語からSQLを生成する基本パターンです。
3-10. metaprompt（メタプロンプト）
「プロンプトを生成するプロンプト」です。タスクの説明を入力するとClaudeが最適化されたプロンプトテンプレートを生成し、白紙からの出発（blank page problem）を解消します。
3-11. pdf_upload_summarization（PDF処理）
PDFをbase64エンコードしてAPIに送信し、要約や分析を行う手法です。ドキュメントブロック（type: "document"）を使います。
3-12. read_web_pages_with_haiku（Webページ要約）
requestsでWebページを取得し、Haikuで低コストに要約するシンプルなパイプラインです。
3-13. sampling_past_max_tokens（max_tokens超えの出力）
stop_reason == "max_tokens"を検出し、途中までの出力をassistantメッセージとしてprefillして継続生成させることで、max_tokensを超える長文出力を実現します。
3-14. using_citations（引用）
ドキュメントブロックのcitations: {"enabled": True}を有効にすると、Claudeが回答に自動で引用を付与します。テキスト文書は文字位置（char_location）、PDFはページ番号（page_location）で引用箇所を特定できます。
4. multimodal/ — 画像・PDF処理の6パターン
4-1. getting_started_with_vision（ビジョン入門）
ローカルファイルとURLの2方法で画像をAPIに渡す基本パターンです。base64エンコードとメッセージ構造の基礎を学べます。
4-2. best_practices_for_vision（ビジョンのベストプラクティス）
画像分析の精度を上げる4つのテクニックを実演します。
- ロール割り当て + Chain-of-Thought（「あなたは完璧な視力を持つ...」）
- ビジュアルプロンプティング（画像に矢印・丸印を直接描画）
- Few-shot学習（速度計の読み取り例を提示）
- 複数画像の同時処理（長いレシートを分割して処理）
4-3. crop_tool（クロップツール）
Claudeがツール呼び出しで画像の任意の領域をクロップし、「ズームイン」して詳細分析するエージェンティックパターンです。正規化座標（0〜1）でバウンディングボックスを指定し、PILで切り出した画像をbase64で返します。
チャートの凡例を読んだり、文書の小さな文字を解析したりするときに有効です。
4-4. how_to_transcribe_text（文書転写）
ClaudeのOCR能力を活かした文書処理です。手書き文字の認識、コードのスクリーンショットからの抽出、車両事故報告書の処理、組織図からJSONへの変換など、5つの実例を紹介します。
4-5. reading_charts_graphs_powerpoints（チャート・グラフ・スライド）
PDFを直接APIに送信してチャートやグラフの値を読み取る手法です。スライドデッキの各ページをナレーション形式で文字起こしし、RAGやベクトル検索に対応するテキストデータに変換します。
4-6. using_sub_agents（サブエージェント）
低コストのHaikuで複数のPDFから並列にデータ抽出し、高性能なOpusで統合分析するパターンです。
Opus（プロンプト生成）→ Haiku×4（並列抽出）→ Opus（統合分析 + 可視化コード生成）
Appleの四半期決算書4本からの売上推移分析を実演しています。ThreadPoolExecutorによる並列処理で効率的に動作します。
5. claude_agent_sdk/ — Agent SDKで本格エージェント構築
Agent SDKの基本概念（アーキテクチャ、認証、query() vs ClaudeSDKClientの違いなど）は、別記事「Claude Agent SDKとは何か — 初心者向け完全ガイド」で詳しく解説しています。Agent SDKは内部的にClaude Code CLIをサブプロセスとして起動するため、APIキーだけでなくPro/Maxサブスクリプションでも利用できます。
5-1. The One-Liner Research Agent
1行でリサーチエージェントを作る最小構成です。
-
query()— ステートレスな一発質問 -
ClaudeSDKClient— ステートフルな対話（メモリあり） -
allowed_tools=["WebSearch"]でWeb検索を有効化 - Readツールで画像・文書のマルチモーダル分析
5-2. The Chief of Staff Agent
企業向けマルチエージェントシステムの全機能を網羅します。
- CLAUDE.md — プロジェクトコンテキストの永続化
- Bashツール — Pythonスクリプトの実行（財務モデリングなど）
- Output Styles — エグゼクティブ向け/技術者向けの出力切替
- Plan Mode — 計画立案 → レビュー → 承認 → 実行のワークフロー
- Slash Commands — ユーザーフレンドリーなコマンド体系
- Hooks — ツール実行前後の自動アクション（監査ログなど）
- Subagents — Taskツールで専門エージェント（財務アナリスト、リクルーターなど）に委譲
5-3. The Observability Agent
MCPサーバー経由でGitHubやCI/CDと連携するエージェントです。
- Git MCPサーバー: 13のGit操作ツール
- GitHub MCPサーバー: 100以上のGitHub APIツール（Docker経由）
- facebook/reactリポジトリのCI/CD障害分析を実演
6. patterns/agents/ — 3つのワークフローパターン
6-1. Basic Workflows
3つの基本パターンを実装します。
プロンプトチェーン — 逐次処理。データ抽出 → フォーマット → ソート → テーブル作成。
パラレル化 — ThreadPoolExecutorで同一プロンプトを複数入力に並列実行。ステークホルダー影響分析（顧客・従業員・投資家・サプライヤー）の事例。
ルーティング — LLMが入力を分類し、適切なハンドラに振り分け。サポートチケットを請求・技術・アカウント・製品チームにルーティング。
6-2. Orchestrator-Workers
オーケストレーターLLMがタスクを動的にサブタスクに分解し、ワーカーLLMに委譲するパターンです。事前定義のパラレル化とは異なり、入力に応じて最適なアプローチを実行時に決定します。
6-3. Evaluator-Optimizer
「生成 → 評価 → フィードバック → 再生成」のループです。評価者がPASS / NEEDS_IMPROVEMENT / FAILを判定し、合格するまで改善を繰り返します。O(1)のgetMin()を持つスタック実装が題材です。
7. extended_thinking/ — 拡張思考
7-1. Extended Thinking
Claudeの内部推論プロセスを可視化する拡張思考機能のガイドです。
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8000,
thinking={
"type": "enabled",
"budget_tokens": 2000 # 最小1,024トークン
},
messages=[...]
)
パズル、論理問題、数学的分析での推論過程が確認できます。安全フラグが立った場合は暗号化されたredacted thinkingブロックが返されます。
7-2. Extended Thinking with Tool Use
拡張思考とツール利用の組み合わせです。Claudeがどのツールをなぜ選んだかの推論過程が見えるようになります。thinkingブロックの暗号署名を保持してtool_resultを返す必要がある点が要注意です。
8. skills/ — Claude Skillsの活用
8-1. Skills Introduction
Excel / PowerPoint / PDFを生成するAnthropic管理スキルの入門です。client.beta.messages.create()でcontainerパラメータを使い、コード実行環境内でファイルを生成します。スキルのメタデータだけが初期ロードされ、実際に使うときだけ全命令がロードされるため、トークン効率が約90%改善します。
8-2. Skills for Financial Applications
実践的な金融ワークフローです。P&L付き多シートExcel、投資委員会向けPowerPoint、ポートフォリオ分析レポートなどを自動生成します。Excel → PowerPoint → PDFの連鎖パイプラインも実装されています。
8-3. Building Custom Skills
独自スキルの開発・デプロイ・管理方法です。SKILL.md（必須）とサポートファイルで構成し、create_skill()/list_custom_skills()/delete_skill()で管理します。財務比率分析、ブランドガイドライン適用、DCF評価モデルの3つのカスタムスキルを構築します。
9. third_party/ — 外部サービス連携13本
LlamaIndex（6本）
| ノートブック | 内容 |
|---|---|
| Basic_RAG_With_LlamaIndex | 基本的なRAGパイプライン構築 |
| Multi_Document_Agents | ドキュメントごとのReActエージェント + トップレベルルーティング |
| ReAct_Agent | Thought → Action → Observationのエージェントループ |
| Router_Query_Engine | サマリーインデックス vs ベクターインデックスの自動切替 |
| SubQuestion_Query_Engine | 複合クエリを原子的なサブ質問に分解 |
| Multi_Modal | AnthropicMultiModal LLMによる画像分析 |
Pinecone（2本）
- rag_using_pinecone — VoyageAI埋め込み + Pineconeサーバーレスインデックスで基本RAG
- claude_3_rag_agent — LangChain v1のエージェントフレームワークとの統合
MongoDB（1本）
VoyageAI埋め込み（1536次元）+ MongoDB Atlasベクトル検索で500件以上のテックニュース記事を扱うRAGシステムです。
Deepgram（1本）
音声ファイルの文字起こし + Claudeによるインタビュー質問生成のパイプラインです。
ElevenLabs（1本）
ElevenLabsのSTT/TTSとClaudeのストリーミング応答を組み合わせた低レイテンシ音声アシスタントです。文単位のTTS合成とWebSocketストリーミングで体感速度を最適化しています。
WolframAlpha（1本）
Wolfram Alpha LLM APIをツールとしてClaudeに接続し、数値計算や科学的クエリを処理します。
Wikipedia（1本）
Claudeが反復的にWikipedia検索を行い、十分な情報が集まるまで探索を続けるリサーチパターンです。
VoyageAI（1本）
テキスト埋め込みの基礎知識。voyage-2/voyage-code-2モデル、input_type指定（query vs document）、コサイン類似度計算を解説します。
10. その他のディレクトリ
finetuning/ — Claude 3 Haikuのファインチューニング
Amazon Bedrockでのファインチューニングガイドです。JSONL形式のデータセット作成 → S3アップロード → boto3でジョブ起動 → Provisioned Throughputでデプロイの流れを解説します。
coding/ — フロントエンドデザインのプロンプティング
Claudeに「AIっぽくない」洗練されたフロントエンドを生成させるためのプロンプト技法です。
- タイポグラフィ: Inter、Arial、Roboto以外のフォント指定
- カラー: CSS変数による統一テーマ
- モーション: マイクロインタラクション
- 背景: レイヤードグラデーション、パターン
デザインの各次元を個別に指示する方法と、参考となるデザインスタイル（IDEテーマ、文化的美学など）を明示する方法が紹介されています。
observability/ — Usage & Cost Admin API
Admin API（sk-ant-admin-*キー）でClaude APIの使用量とコストをプログラマティックに取得する方法です。モデル別・ワークスペース別のトークン消費、キャッシュ効率の測定、CSV出力などが含まれます。
tool_evaluation/ — ツール評価フレームワーク
ツール定義の品質を評価するフレームワークです。XMLファイルに評価タスク（プロンプト + 正解）を定義し、エージェントループで各タスクを実行して正答率・所要時間・ツール呼び出し回数を測定します。Claudeがツール定義へのフィードバック（名前の分かりやすさ、パラメータの説明不足など）も自動生成します。
まとめ: 目的別おすすめNotebook
| やりたいこと | おすすめNotebook |
|---|---|
| RAGを構築したい | capabilities/retrieval_augmented_generation |
| ツール利用の基本を知りたい | tool_use/calculator_tool |
| 構造化データを抽出したい | tool_use/extracting_structured_json |
| APIコストを削減したい | misc/prompt_caching + misc/batch_processing |
| マルチエージェントを構築したい | claude_agent_sdk/01_The_chief_of_staff_agent |
| 画像からデータを取りたい | multimodal/crop_tool |
| 長文を扱いたい | tool_use/automatic-context-compaction |
| 評価基盤を作りたい | misc/building_evals |
| 大量のツールを管理したい | tool_use/tool_search_with_embeddings |
| フロントエンドを生成したい | coding/prompting_for_frontend_aesthetics |
すべてのNotebookはGitHubリポジトリから直接実行できます。APIキーを設定すれば、記事で紹介した全パターンを自分の手で試せます。