こんにちは。よっしーです(^^)
背景
この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。
1. 一言でいうと
Agent SDK で「実際に動くもの」を見たいときの案内板です。中身は3つの行き先の紹介だけで、(1) まず最小限のエージェントを動かす（クイックスタートか Hello World）、(2) 作りたいものに形が近いデモアプリケーションを claude-agent-sdk-demos リポジトリからクローンする、(3) Python のノートブックで段階的に学ぶ Claude Cookbook のレシピを進める、という順路を示しています。
第76回から続けてきた Agent SDK の回の、最後の1本です。これまでは機能ごとのガイドとリファレンスで部品を1つずつ見てきました。このページは、それらが組み合わさった完成品の置き場所を教えるページです。
2. どういう場面で役立つか
シーン1：SDK をまだ1回も動かしていない
原文は、完全なアプリケーションに手を出す前に、最小限のエージェントから始めるよう書いています。文章で手順を追いたいならクイックスタート、コードから入りたいなら Hello World のリポジトリ、という分け方です。
シーン2：作りたいアプリに近いお手本が欲しい
メールクライアントのようなアプリや、複数のエージェントが協力して調べ物をするシステムなど、作りたいものの「形」が決まっている場面です。形の近いデモをクローンして、そこから改造を始められます。
シーン3：Python で、段階を追って学びたい
Claude Cookbook の Agent SDK シリーズは、簡単な調査エージェントから始まり、少しずつ機能を足して、洗練されたマルチエージェントのシステムへ進む構成です。ノートブックなので、セルを実行しながら1段ずつ確かめられます。
不要・向かないケース
- 仕様や既定値を確かめたい：例のコードは「動く一例」であって仕様書ではありません。オプションの正確な意味や既定値は、第104回・第105回のリファレンスで確かめます。
- そのまま本番に載せたい：原文はデモをローカル開発用と書いています。本番に載せるなら、第94回のホスティング、第95回の安全なデプロイ、第96回の可観測性の検討が別に必要です。
- TypeScript のノートブックで学びたい：原文によれば、Cookbook のレシピは Python のノートブックです。TypeScript なら、Hello World やデモのリポジトリから入ることになります。
3. 行き先の解説
原文には実行できるコード例が含まれていません（fenced コードブロックは0本）。ページ全体が外部のリポジトリとノートブックへの案内なので、この節では、3つの行き先の特徴と使い分けを整理し、これまでの連載の回とどう組み合わせて読むとよいかを示します。
3-1. 3つの行き先
| 行き先 | 言語 | 中身 | 向いている人 |
|---|---|---|---|
| Agent SDK クイックスタート | TypeScript／Python | 最初に動くエージェントを作る手順。セットアップを含む。例のエージェントはサンプルファイルのバグを見つけて直す | 文章の手順に沿って始めたい |
Hello World（claude-agent-sdk-demos の hello-world） | TypeScript | クローンして始める最小限のプロジェクト | リポジトリのコードから始めたい |
デモアプリケーション（claude-agent-sdk-demos） | （原文に言語の記載なし） | メールクライアントからマルチエージェントの調査システムまでのデモ。ローカル開発用 | 作りたいものの形が決まっている |
| Claude Cookbook の Agent SDK シリーズ | Python | ノートブックのレシピの連続。前のレシピを土台に新しい概念と機能を足していく。最初は「ワンライナー研究エージェント」 | 段階を追って学びたい |
表は原文の記述を筆者が整理したものです。原文は、デモの一覧や各デモの中身までは書いていません。どんなデモがあるかは、リポジトリを開いて確かめる必要があります。
Claude の製品全体のレシピは、完全な Claude Cookbook にある、とも原文は案内しています。
3-2. 選び方
原文の構成をそのまま順路として読むと、次のようになります。
- まず最小限のエージェントを動かす。クイックスタート（第78回）か Hello World。SDK のインストール、認証、
query()の呼び出しが一通り動くことを確かめる。 - 形の近いデモをクローンする。作りたいもの（メール処理、調査システムなど）に近いものを選び、改造の出発点にする。
- Python なら Cookbook のレシピを順に進める。ワンライナー研究エージェントから始めて、前へ進む。
1番を飛ばさない理由として、原文は「SDK でまだ何も構築していない場合は、完全なアプリケーションの前に」と書いています。デモが動かないとき、それが SDK の導入の問題なのか、デモ固有の問題なのかを切り分けられなくなるから、と読めます（筆者の解釈）。第97回で見た「CLI が見つからない」「起動しない」といった失敗は、最小限のエージェントの段階で潰しておくのが効率的です。
3-3. Cookbook のシリーズとこれまでの回
この連載では、すでに Cookbook の Agent SDK シリーズの一部に出会っています。
| 出会った回 | レシピ | URL の名前 |
|---|---|---|
| 第94回（ホスティング） | エージェントのホスティング（Docker・Modal・Kubernetes のデプロイ可能なコード付き） | 07_Hosting_the_agent.ipynb |
| 第103回（移行ガイド） | OpenAI Agents SDK からの移行レシピ | claude-agent-sdk-04-migrating-from-openai-agents-sdk |
| 第106回（今回） | ワンライナー研究エージェント | claude-agent-sdk-00-the-one-liner-research-agent |
URL の名前に 00・04・07 と番号が付いていることから、これらは同じ番号付きのシリーズの一部で、今回の「ワンライナー研究エージェント」がその最初（00）だと読めます（筆者の対応づけ。シリーズの全体の一覧はこのページには載っていません）。
3-4. 例を読むときに、連載のどの回を手元に置くか
デモやレシピのコードには、これまでの回で見た部品が組み合わさって出てきます。コードを読んでいて気になったときに引く回を、部品ごとにまとめます。
| コードで見かけるもの | 引く回 |
|---|---|
query() のループ、メッセージの種類、結果の subtype | 第77回（エージェントループ） |
| オプションの意味 | 第79回（設定）、第104回・第105回（リファレンス） |
allowedTools・permissionMode・canUseTool | 第80回・第81回（権限、ユーザー入力） |
| フック | 第82回 |
| 自作ツール、MCP サーバー | 第83回・第84回 |
| システムプロンプト | 第86回 |
| セッションの再開・fork、別ホストでの再開 | 第87回・第93回 |
| サブエージェント（マルチエージェントの調査システムなど） | 第89回 |
| スキル、プラグイン、CLAUDE.md などのファイルの機能 | 第90回・第99回・第100回 |
対話型か1回きりか、ClaudeSDKClient | 第91回・第105回 |
| 費用の集計 | 第92回 |
| 構造化出力 | 第98回 |
| ストリーミング出力、進捗表示 | 第101回・第102回 |
表は筆者の整理です。
筆者の指摘：デモやレシピは「動くこと」を優先した例なので、権限の設定は手早く動く形になっていることが多いはずです。これまでの回でも、例のコードが acceptEdits で実際にファイルを書き換えたり（第102回）、権限設定が無いために Bash が承認されない可能性があったり（第98回）、文字列の部分一致で危険なコマンドを止めようとしていたり（第100回）しました。デモを改造して自分のアプリにするときは、第80回の権限の評価順序と、第95回の「エージェントの境界の外に大事なものを置く」考え方で、設定を一度見直すのが安全です。
4. まとめ
- このページは Agent SDK の完成品の置き場所の案内板。コード例は含まれていない。
- 順路は、最小限のエージェント（クイックスタートか Hello World）→ 形の近いデモをクローン → Python なら Cookbook のレシピを順に。
- デモは
claude-agent-sdk-demosリポジトリにあり、メールクライアントからマルチエージェントの調査システムまで。ローカル開発用なので、本番には第94〜96回の検討が要る。 - Cookbook の Agent SDK シリーズは Python のノートブックで、ワンライナー研究エージェントから始めて前のレシピの上に積み上げる。第94回のホスティング、第103回の移行のレシピも同じシリーズと読める。
- 例のコードを読むときは、部品ごとにこれまでの回を引く。改造して使うなら、権限と安全の設定を見直す。
これで第76回から続いた Agent SDK の回は一巡です。
次回予告
次回は 「エラーリファレンス」（errors） を取り上げる予定です。
第97回の Agent SDK のトラブルシューティングでは、Not logged in・Invalid API key・API Error・429・選んだモデルの問題といった、認証や API に関わるエラーは本体側のエラーリファレンスの担当として回されていました。次回は Agent SDK を離れ、Claude Code 全体で出会うエラーのメッセージごとに、何が起きていて、どう直せばよいのかを見ていきます。
何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。
それでは、また明日お会いしましょう(^^)
コメント