10章・実験付きでAIエージェントを読み解く：bojieli/ai-agent-bookの要約と導入ガイド

bojieli/ai-agent-book の中核公式、10章の学習順序、付随実験の使い分けを整理し、まず第1章の実験を動かしてから本番設計の論点へ進む道筋がわかります。

📌 bojieli/ai-agent-bookとは何か：AIエージェントの教科書ではなく、実験付きの地図

一言で言えば、bojieli/ai-agent-book は AIエージェントを「モデルの賢さ」だけでなく、コンテキスト・ツール・評価・運用まで含むシステムとして学ぶ、オープンソースの書籍兼実験リポジトリです。日常の例えなら、料理のレシピ本に、食材の比較表、調理器具、失敗した鍋の記録、再現用の台所まで付いてきます。読むだけでも構造は見えますが、手を動かすと「なぜその設計なのか」が腹落ちします。

中心に置かれている公式は、次の一行です。

Agent = LLM + コンテキスト + ツール

LLM（大規模言語モデル）は考える頭脳、コンテキスト（その時点でモデルに見えている情報）は目、ツールは外界へ働きかける手足です。たとえば検索結果を見て、コードを実行し、その結果を受けて次の行動を決める。この「考える → 実行する → 観察する」を繰り返す ReAct（Reasoning and Acting、推論と行動を交互に進めるループ）が、単なるチャットとエージェントの境目です。

リポジトリを開くと、読者は次のものを手にできます。

• 原理からエンジニアリング実践までを積み上げる10章の本文
• 日本語を含む15言語のドキュメントと、PDF・EPUBの配布物
• README、コード、テスト、ログ、受け入れ条件を備えた付随プロジェクト
• 章ごとの実験を比較し、設計の寄与を確かめるアブレーション（要素を一つ外して影響を測る実験）
• uv.lock、実験台帳、manifest（実験条件と成果物を結び付ける記録）による再現性への配慮

ただし、ここで最初からすべての実験を走らせようとしてはいけません。冷蔵庫の食材を全部鍋に入れても、豪華な料理ではなく、たいていは片付けの難しい何かになります。

動機：AIエージェントの情報収集が「モデル名の一覧」で終わってしまう

AIエージェントを学び始めると、検索結果にはモデル、フレームワーク、MCP、RAG、Computer Use、マルチエージェントという単語が一気に並びます。MCP（Model Context Protocol）はモデルと外部ツールやデータソースを接続するプロトコル、RAG（Retrieval-Augmented Generation）は検索した知識を生成モデルへ渡す構成です。どちらも重要ですが、個別の用語だけ追うと「結局、どの順に設計し、何を測るのか」が見えにくい。

実務では、デモが動いた後に問題が出ます。ツールの説明が長すぎて選択を誤る。履歴を削ったら同じ失敗を繰り返す。検索結果を受け取っても検証しない。モデルを交換したら性能が変わり、改善したのか偶然なのか判定できない。人間なら、引き継ぎ資料なしで複数部署を転々とするようなものです。

ai-agent-book が面白いのは、この混乱を「章の順番」と「実験の比較」に変換している点です。モデルを選ぶ前に、何を見せるか、何をさせるか、どう確かめるかを考える。つまり、最新モデルのカタログではなく、エージェントを検証可能なシステムへ変えるための学習導線として読むべきリポジトリです。

仮説：AIエージェントは「強いモデルを呼ぶ」より先に、観測・行動・検証を設計できるかで決まる

ここで仮説を置きます。同じモデルでも、コンテキストとツールの設計を変えれば、実行できるタスクの範囲と失敗の仕方は変わる。そして、その差を評価できなければ改善とは呼べない。

これは、人に仕事を頼む場面に似ています。「優秀な人を採用する」だけでは仕事は終わりません。必要な資料を机に置き、触れてよいシステムを決め、成果物の検品方法を用意して、失敗した時の戻り道を作る必要があります。エージェントでは、その机・権限・検品・戻り道がそれぞれコンテキスト、ツール、制約、検証、是正に当たります。

リポジトリの日本語学習ガイドは、本番システムを次の見方でも整理しています。

Agent = Model + Harness

Harness = コンテキスト管理 + ツールインターフェース + 制約 + 検証 + 是正

ここでいうHarness（ハーネス）は、モデルを囲む実行・ガバナンス層です。ハーネスという言葉は馬具を指しますが、馬の力を奪うためではなく、走る方向を導き、危険な場所で止めるためのものです。ai-agent-book の価値は、モデルの能力を説明した後で、モデルの外側にある設計責任を隠さないところにあります。

検証：10章は「構築」から「向上」へ進む

10章は、ばらばらの技術解説ではありません。第1章から第6章でエージェントを構築し、第7章から第10章で評価・学習・継続的改善・協調へ進む二部構成です。学習の地図を先に見ておくと、気になる単語へ迷子になりにくくなります。

第1〜2章：まず「何を見て、何をするか」を固める

第1章は、公式とReActループから始まり、ツール呼び出し、コンテキストの役割、Harnessエンジニアリングへ進みます。特に重要なのは「回答を返した」ことと「タスクを完了した」ことを分ける視点です。ツール定義が消えた場合、モデルは黙るとは限りません。観測なしでも、もっともらしい文章を返せてしまう。見た目が整っているからこそ検証が必要になります。

第1章の context 実験は、履歴、reasoning（推論過程）、ツール呼び出し、ツール結果を切り替えます。完全なコンテキストと、どれか一つを欠いた構成を比べるアブレーションです。医師が症状の原因を一つずつ切り分けるように、どの要素が挙動に効くかを観察します。

第2章では、コンテキストの組み立てをコストとレイテンシの問題まで掘り下げます。プロンプトを長くすればよいわけではありません。固定部分を不用意に変えるとキャッシュを使いにくくなり、動的な情報を詰め込みすぎるとモデルの注意が分散します。Agent Skills（必要な手順をオンデマンドで読み込む仕組み）は、最初から全マニュアルを机に広げるのではなく、索引を見て必要なページだけ開くやり方に近いものです。

第3〜6章：記憶、道具、コード、世界への接続を広げる

第3章は、ユーザーメモリとRAGを扱います。メモリは「前に何を好んだか」を残し、RAGは「外部資料のどこに何が書かれているか」を取り出します。検索方式も、密ベクトル、疎検索、再ランキング、構造化インデックス、知識グラフ、Agentic RAGへ広がります。検索を付ければ自動的に正確になるのではなく、チャンク分割、検索失敗、根拠の提示まで含めて設計する章です。

第4章では、ツールをAgentの手足として整理します。知覚ツールは外界を読む窓、実行ツールは外界を変える手、協調ツールは他のAgentや人へ仕事を渡す窓口です。MCPを使うと接続の標準化は進みますが、接続できることと安全に実行できることは同じではありません。ファイル操作、コードインタープリタ、仮想ターミナルには、入力検証、権限、承認、出力の要約や保存が要ります。

第5章はCoding Agentとコード生成です。コードは単なる成果物ではなく、実行時に新しいツールや処理経路を作るメタ能力になります。数学問題にコードを使う、論理パズルを制約充足問題へ変換する、ログ形式に合わせてパーサーを更新する、といった実験が並びます。ここでソフトウェア開発のテスト、型チェック、Gitという既存のHarnessが、AIエージェントの検証基盤として効いてきます。

第6章は観察と動作の空間を、テキストの外へ広げます。非同期Agent、イベント駆動、音声、Computer Use、ロボット操作が同じ地図に載ります。入力を待つだけのチャットから、メールやWebhookで起き、音声を聞き、GUIを操作し、必要なら人へ制御を返すシステムへ進むわけです。ここまで来ると、キャンセル、セーフポイント、タイムアウト、リソース解放は「あれば便利」ではなく、動作の一部になります。

第7〜10章：作ったものを測り、学習させ、協調させる

第7章のメッセージは明快です。評価がなければ、設計変更で良くなったのか、たまたま良い回答を引いたのかを区別できません。ベンチマーク、タスク設計、指標、LLM-as-a-Judge（別のLLMに評価させる方式）、統計的有意性、可観測性を扱います。モデルの点数だけでなく、Harnessを含むシステムとして評価するという発想が重要です。

第8章はモデルのポストトレーニングです。SFTは望ましい例を覚えさせる方向、RLは環境からの報酬を使って方策を汎化させる方向、と整理できます。ただし、学習を始める前にデータ、環境、報酬、評価を設計しなければなりません。付属実験には、教師モデルの例を学生側へ蒸留するプロジェクトもあります。モデル訓練の章はリポジトリ内で最も専門性が高く、GPUや機械学習の知識が必要な領域です。

第9章は、運用中の軌跡から経験を抽出し、知識・指示・プログラム・パラメータという更新経路へつなげます。「ログを保存した」だけでは学習ではありません。成功と失敗を評価し、条件を比較し、古いルールを退役させ、回帰テストを通す必要があります。Agentが自分を書き換える話に見えても、実際にはレビュー、受け入れ条件、カナリア、ロールバックが必要な変更管理の話です。

第10章はマルチAgent協調です。複数のAgentを並べれば自動的に賢くなるわけではありません。後続Agentが前のAgentと同じ情報を見て同じ推測をするだけなら、計算コストが増えただけです。外部検索、コード実行、レンダリング、独立した検証など、生成時にはなかった新しい情報を持ち込むときに協調の価値が生まれます。コンテキストを共有するか、ファイルやメッセージバスで分離するか、Managerで動的に割り当てるかが設計論点になります。

結果：付随実験は「動く／再現／進行中」を区別している

このリポジトリの実験を紹介するとき、最も大切なのは「すべてが同じ条件で、すぐ動く」と誤解させないことです。なお、実験数の集計は版によって差があります。今回取得したコミットでは、日本語READMEが93個、原版READMEが冒頭で108個、概要表で103個と案内しています。章間プロジェクトや更新タイミングで数え方が変わるため、この記事では個数を評価軸にせず、章別READMEと実験台帳を確認する読み方を勧めます。日本語READMEでは、付随プロジェクトを次の3種類に分けています。

ここで、リポジトリの実験台帳にある重要な注意を押さえます。clone、依存関係のインストール、スモークテストの成功だけでは、実験完了の証明になりません。 完了とは、本文が求める実行と証拠のゲートを満たし、確認可能な成果物が保存されている状態です。しかも、完了した実験でも結果が仮説を支持するとは限りません。これは科学実験として健全な態度です。

💡 活用事例：第10章の並列Web調査は、速さより終了処理を学ぶ教材

このリポジトリの活用方法を、具体的な物語で見てみましょう。ある開発者が、大学サイトを一件ずつ開いて教員プロフィールを探す調査を自動化したいとします。最初の発想は、検索担当Agentを10個並列に起動すれば速くなる、です。

しかし、10個が同時に見つけたらどうするのか。最初の一件が正しい結果を返した後も、残り9個を走らせ続けるのか。サイトの一つがタイムアウトしたら全体を失敗にするのか。ここで chapter10/parallel-web-research が教材になります。独立したPlaywrightブラウザセッション（Chromiumを自動操作するためのライブラリの実行単位）を使い、実サイトを読み、LLMで引用可能な証拠を抽出します。さらに、状態通知、サイト単位のエラー隔離、最初の結果を一度だけ確定するロック、終了通知、ブラウザコンテキストの解放までを受け入れ条件にしています。

保存済みの記録では、2026年7月29日の10ページ比較で、並列の壁時計時間は18.542秒、逐次は58.264秒、測定された高速化は3.142倍でした。これは特定のサイト、モデル、実行環境における記録であり、一般の速度保証ではありません。後続の来歴完全なキャンペーンでは、速度は1.872倍と記録され、どちらも「測定値を条件付きで読む」必要を教えてくれます。

この例の本当の学びは3.142という数字ではありません。並列化の価値は、workerを増やすことではなく、勝者を一度だけ確定し、敗者を安全に止め、資源を閉じ、証拠を残すところまで含めて設計することです。速い検索だけ欲しいなら、単純な並列HTTPリクエストでもよい。しかし、エージェント協調を学びたいなら、終了処理と監査まで読むべきです。

💡 もう一つの活用例：教師の出力を小型モデルへ移す

別の開発者は、高価で強いモデルを毎回呼ぶコストを下げたいとします。そこで第8章の prompt-distillation を読み、教師モデルの出力を集め、学生モデルを学習させ、品質・レイテンシ・コストを比較します。蒸留（大きなモデルの振る舞いを小さなモデルへ移す方法）は、単にサンプルを作って終わりではありません。

保存済みの実験台帳には、教師の学習用160件、保持評価用80件の実行記録、CUDA（GPUで並列計算を行うためのプラットフォーム）で学習した SmolLM2-135M-Instruct のLoRA（モデル全体ではなく追加の小さな重みを学習する手法）チェックポイントが記録されています。保持評価では教師100%、ベースライン0%、学習後の学生95%とされ、レイテンシは約197倍、入力トークンは約75%削減と報告されています。

ただし、これも万能な結論ではありません。対象タスク、教師、学生、データ、評価方法が固定された一つのキャンペーンです。別のタスクで同じ数字になるとは限らない。むしろ、数字が条件と一緒に保存されていること自体が、このリポジトリの教材価値です。

📌 注目ポイント：このリポジトリを読むときの5つの視点

ここまでの要約を、設計レビューで使える5つの問いに変換します。

1. モデルの前に、観測と行動の境界を見る。 何がコンテキストに入り、どのツールがどんな引数で呼ばれるか。見えていないものは、モデルにとって存在しません。
2. 本文の抽象と実験の実装を混同しない。 本文は機構の骨格、実験はSDK、アダプター、テスト、ログ、証拠を含む具体例です。一つのAPIの書き方を普遍的な設計原則だと思わない。
3. 結果ではなく、検証器と受け入れ条件を見る。 成功率だけではなく、失敗をどう分類し、何を証拠として残し、未達をどう記録したかを確認します。
4. コスト・レイテンシ・安全性を同じ表に置く。 速くなったが外部呼び出しが増えた、精度が上がったがGPUが必要になった、というトレードオフを隠さない。
5. 変更経路に戻り道があるかを見る。 生成、学習、自己更新、マルチAgent化のどの段階にも、テスト、承認、カナリア、ロールバックを置けるかが問われます。

🔥 ハマりポイント：READMEを読んだだけで「再現できた」と思わない

このリポジトリは親切に見えるからこそ、読み方を間違えると時間が溶けます。症状 → 原因 → 対処法の順で、典型的な落とし穴を見ておきましょう。

その1：付随実験を一括で動かそうとする

〜と思いがちだが、実は、章ごとに依存関係、API、GPU、ブラウザ、外部リポジトリの条件が違います。症状は、巨大な環境を作ったのに最初の実験すら動かないこと。原因は、入門実験と訓練実験を同じ土俵に載せたことです。対処法は、まず第1章の context だけを選び、章別のextraを使うことです。

その2：cloneやインストール成功を実験成功とみなす

〜と思いがちだが、実は、リポジトリは実験ステータスと証拠を分離して管理しています。症状は「コードはあるのに、本文の主張を再現した証拠がない」こと。原因は、環境準備と受け入れを同一視したことです。対処法は、READMEの受け入れ条件、docs/EXPERIMENT_STATUS.md、章別のEXPERIMENT_LEDGER.md、保存済みmanifestを順番に確認します。

その3：日本語版を原版と同じ鮮度だと思う

〜と思いがちだが、実は、日本語を含む翻訳版はコミュニティによる貢献で、中国語原版より遅れる場合があるとREADMEに明記されています。症状は、本文と最新コードの章番号や実験名がずれること。原因は、翻訳・実装・ビルドの更新タイミングが一致しないことです。対処法は、まず中国語原版の変更履歴とルートREADMEを確認し、必要なら日本語本文と実験READMEを突き合わせます。

その4：外部リポジトリを内蔵コードだと思う

〜と思いがちだが、実は、第6・7・9・10章のベンチマーク、訓練フレームワーク、ロボット関連など、23個の外部リポジトリはサイズとライセンスの理由で同梱されていません。症状は、章のリンク先にコードがなく、実験が途中で止まること。原因は、再現ガイドがcloneを前提にしていることです。対処法は、各READMEの指定コミットを確認し、外部プロジェクト固有のライセンスと環境条件を守って取得します。

その5：古い実験結果の数字を最新版の性能だと思う

〜と思いがちだが、実は、結果はモデル、プロンプト、サイト、データ、ハードウェア、APIの状態に依存します。症状は、別の環境で同じ速度や精度が出ないこと。原因は、条件付きのキャンペーンを一般化したことです。対処法は、数字の横に測定日、モデル、プロバイダー、タスク数、ハードウェア、比較条件があるか確認し、なければ記事や報告書で断言しないことです。

🔄 代替技術との比較：本・SDK・ベンチマークは役割が違う

ai-agent-book は特定SDKの使い方だけを最短で覚える教材ではありません。代替となる学び方にも向き不向きがあります。

SDKのAPIを明日使う必要があるなら、公式Quickstartが近道です。一方、「検索を付けると何が変わるか」「ツール定義を削るとどう壊れるか」「複数Agentにする価値はどこから生まれるか」を知りたいなら、ai-agent-book の本文と実験の組み合わせが向いています。

🚀 取り込み方：今日・今週・今月でリポジトリを自分の設計材料にする

読む順番を決めないままcloneすると、巨大なファイル一覧に圧倒されます。最初は「一つの問い、一つの実験、一つの記録」に絞りましょう。

今日（5分でできること）は、公式リポジトリの日本語READMEと学習ヒントを開き、次の問いをメモします。

• 自分の業務でAgentに見せるべき情報は何か
• Agentに許可する操作は何か
• 成功をモデルの自己申告以外でどう確認するか

次に、Python環境を確認して、ルートで第1章用の依存関係を入れます。リポジトリREADMEが案内する現行の共通対応範囲はPython 3.11〜3.13です。uv（Python環境と依存関係を高速に管理するツール）を使う場合の推奨コマンドは次のとおりです。

uv sync --locked --extra ch1
uv run python chapter1/context/main.py --mode ablation

APIキーを用いる実験では、先に対象実験のREADMEで必要なプロバイダーと環境変数を確認します。第1章 context のコードは、--mode interactive、--mode single、--mode ablationを持ち、--ablation-modes full no_historyのように比較対象を絞れます。まずは一つのプロバイダー、一つのケース、一つの実験結果から始めるのが安全です。なお、APIキーを記事やログへ書き込まないでください。

今週は、第1章と第2章を本文 → Code map → 最小実験 → テストの順に読みます。第1章では完全なコンテキストと欠損コンテキストを比較し、第2章では圧縮とキャッシュを観察します。結果を次のような表に自分で残すと、単なる写経から設計レビューへ変わります。

今月は、自分の業務の小さなタスクへ移植します。ただし本番へ直接コピーするのではなく、教材と本番の差分を埋めます。具体的には、入力データと命令を分離し、ツールを最小権限にし、タイムアウトとリトライを決め、成功を構造化データで検証し、失敗時のロールバックを用意します。第7章の評価の考え方を使い、代表ケース、境界ケース、既知の失敗ケースを評価セットにします。第9章の継続的進化へ進むのは、更新前後を比較できるようになってからです。

📅 今後の展望：書籍は完成品ではなく、更新される学習インフラ

ai-agent-book は、固定された紙の本というより、コードとドキュメントが一緒に更新される学習インフラです。本文、翻訳、実験、図版、ビルド、CI（継続的インテグレーション、変更を自動検査する仕組み）が同じリポジトリにあります。GitHub Actionsには、最新版PDF/EPUBのビルド、Pagesへのデプロイ、翻訳の整合性確認、依存関係の検査、実験別テスト、Star履歴更新のワークフローが置かれています。

この運用形態には利点と弱点があります。利点は、仕様書だけでなく、実行入口・テスト・証拠・変更履歴を同じ場所で追えること。弱点は、上流コードやモデルAPIの変化が速く、翻訳版、サンプル、外部リポジトリの固定コミットがずれる可能性があることです。だからこそ、記事や社内教材として引用する場合は「2026年9月3日に取得したコミット dc2fd304a177bdccbe2e73d5b6163cf560915f64 の状態」といった時点を添えるのが誠実です。

バージョン2.0では、旧第4章の非同期インタラクションと旧第9章のマルチモーダルAgentを統合して第6章を再構成し、評価・ポストトレーニング・継続的進化を後ろへ移したとREADMEに記載されています。古いPDFと現在の章リンクが一致しない場合があるため、最新版の配布物と現在のREADMEを基準にするのが安全です。

✅ 要点まとめ

最後に、記事を閉じた後も残してほしいポイントを圧縮します。

• bojieli/ai-agent-book は、AIエージェントをLLM単体ではなく、LLM・コンテキスト・ツールのシステムとして学ぶ教材です。
• 10章は「構築（第1〜6章）」から「向上（第7〜10章）」へ進み、原理・実装・評価・協調をつなぎます。
• 付随プロジェクトは、単独実行、外部リポジトリの再現ガイド、進行中／設計の3種類に分かれます。
• 実験数の多さは魅力ですが、最初に全部動かすのではなく、章のStarter入口を一つ選ぶべきです。
• 実験の数値は条件付きの測定結果です。測定日、モデル、プロバイダー、タスク、ハードウェアを一緒に読みます。
• 本番へ移すときは、教材コードへ制約・検証・是正・監査・ロールバックを追加します。

まとめ：このリポジトリを「読む本」から「設計レビューの相手」へ変える

bojieli/ai-agent-book の魅力は、AIエージェントを流行語のコレクションにせず、何を見せるか、何をさせるか、どう測るか、どう直すかという設計問題へ戻してくれる点にあります。特に、章本文と付随実験、Code map、テスト、実験台帳を往復すると、モデルの回答だけでなく、システムの状態遷移と失敗経路を読めるようになります。

導入の最短ルートは、今日 chapter1/context のアブレーションを一度動かし、今週第2章まで読んで、今月自分の業務タスク一つへ評価セットを作ることです。これを読んだあなたは、ai-agent-book を「AIエージェントの用語集」として眺めるのではなく、自分のAgent設計を比較・検証・改善するための地図として使い始められます。

参考文献

本文の確認には、対象リポジトリのREADME、学習ガイド、実験台帳、代表実験のREADME、依存関係定義を使いました。数値や対応範囲は、取得時点の一次資料に照らして読んでください。

1. Bojie Li, bojieli/ai-agent-book（取得コミット: dc2fd304a177bdccbe2e73d5b6163cf560915f64）
   https://github.com/bojieli/ai-agent-book
2. ai-agent-book 日本語README
   https://github.com/bojieli/ai-agent-book/blob/main/docs/ja/README.md
3. ai-agent-book 原版README
   https://github.com/bojieli/ai-agent-book/blob/main/README.md
4. ai-agent-book 日本語・学習のヒント
   https://github.com/bojieli/ai-agent-book/blob/main/docs/ja/LEARNING.md
5. ai-agent-book 実験ステータスと証拠
   https://github.com/bojieli/ai-agent-book/blob/main/docs/EXPERIMENT_STATUS.md
6. ai-agent-book 実験レイアウト規約
   https://github.com/bojieli/ai-agent-book/blob/main/docs/EXPERIMENT_CONVENTIONS.md
7. ai-agent-book 第1章日本語README
   https://github.com/bojieli/ai-agent-book/blob/main/chapter1/README.ja.md
8. ai-agent-book 第10章並列Web調査README
   https://github.com/bojieli/ai-agent-book/blob/main/chapter10/parallel-web-research/README.md
9. ai-agent-book 第8章実験台帳
   https://github.com/bojieli/ai-agent-book/blob/main/chapter8/EXPERIMENT_LEDGER.md
10. ai-agent-book pyproject.toml（依存関係・Python対応範囲）
    https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml
11. ai-agent-book GitHub Actions workflows
    https://github.com/bojieli/ai-agent-book/tree/main/.github/workflows