AIエージェント作りの学習をしたく、「現場で活用するためのAIエージェント実践入門」を読んでいる。この本はいろんな事例でAIエージェントの具体的な実装を教えてくれる。サンプルコードが多く、実践でどう作るといいのかを学ぶことができる。かなり面白いのでAIエージェント作りに興味がある人は買いましょう。
一方で、AIエージェント作りをやったことない身としては、具体事例を実装していく章を読んでも完成系のコードしかないため、実装ステップが大きすぎて理解しきれなかった。一歩ずつ理解するために、自分で手を動かしながら段階的に学んでいきたい。
そこでAIにハンズオンを作ってもらって、まずは「4章 ヘルプデスク担当者を支援する」の内容を学ぶことにした。
ハンズオンを作って学ぶ
著者が https://github.com/masamasa59/genai-agent-advanced-book にサンプルコードを公開してくれている。この内容を読み込んだ上で、自分の学びたい内容のハンズオンを作ると良さそうだ。Claude Codeに以下のようなプロンプトを投げて、インタラクティブにハンズオンドキュメントを作っていってもらった。
@chapter4/ について、自分が学びたいところを限定して、自分で再実装することによって理解を深めたい。ベテランのAIエンジニアとして、まずこの中でどういうカテゴリの実 装があるか調べてみて
さらにどんどん会話を進めていき、自分専用のハンズオンドキュメントを完成たせた。僕の場合は、LangGraphによるエージェントフロー設計、Plan-and-Executeパターンを重点的に学びたいが、RAGについては既に知っていたので今学ぶ必要がなかった。また開発環境のdocker-compose.ymlなどは全てコピーで良いだろう。そのあたりをチューニングした。
ハンズオンドキュメントを作るやりとり
> @chapter4/ について、自分が学びたいところを限定して、自分で再実装することによって理解を深めたい。ベテランのAIエンジニアとして、まずこの中でどういうカテゴリの実
装があるか調べてみて。そして、何を学びたいか壁打ちして
⏺ おっけー！chapter4の中身を詳しく調べてみるね！まずは全体構造を見てみよう 📂
⏺ おっけー！全体像がわかったよ！ 🎉
---
Chapter4の実装カテゴリまとめ
このchapter4は**「RAGを活用したヘルプデスクエージェント」の実装だね！大きく分けて5つのカテゴリ**に分けられるよ！
---
1️⃣ LangGraphによるエージェントフロー設計（agent.py）
最も複雑で学びが多い部分！
- メイングラフ: create_plan → execute_subtasks（並列実行）→ create_answer
- サブグラフ（ループあり）: select_tools → execute_tools → create_subtask_answer → reflect_subtask → （条件分岐で繰り返し or 終了）
- 状態管理: AgentState, AgentSubGraphState によるTypedDictでの状態定義
- 並列実行: Send を使ったサブタスクの並列処理
---
2️⃣ Plan-and-Execute パターン（agent.py + prompts.py）
エージェントの思考フレームワーク！
- 計画生成（Planner）: ユーザーの質問をサブタスクに分解
- サブタスク実行: 各サブタスクを独立して実行
- リフレクション（自己評価）: 回答が十分か評価し、不十分ならリトライ（最大3回）
- 最終回答生成: サブタスク結果を統合して回答
---
3️⃣ RAG（検索拡張生成）のツール実装（tools/）
2種類の検索方式を実装！
| ツール | 検索方式 | バックエンド | ユースケース |
|-------------------|--------------------------|---------------------------|----------------------------|
| search_xyz_manual | キーワード検索（BM25） | Elasticsearch + Kuromoji | エラーコード、固有名詞検索 |
| search_xyz_qa | ベクトル検索（Semantic） | Qdrant + OpenAI Embedding | 過去のQ&Aから類似質問検索 |
---
4️⃣ インデックス構築パイプライン（scripts/create_index.py）
RAGの基盤づくり！
- PDFローダー + テキストスプリッティング（300文字チャンク）
- CSVローダー（Q&Aデータ）
- Elasticsearch: 日本語形態素解析（Kuromoji）設定
- Qdrant: ベクトルDB + Embedding生成
---
5️⃣ Structured Output / OpenAI API連携（models.py + agent.py）
LLMとの連携パターン！
- Pydanticモデルでレスポンス構造を定義（Plan, ReflectionResultなど）
- response_format によるStructured Output
- Tool Calling: convert_to_openai_tool でLangChainツールをOpenAI形式に変換
---
🤔 壁打ち：何を学びたい？
さて！どこを再実装したい？いくつか質問させて〜
Q1. 現在の経験レベルは？
- LangChain/LangGraphは触ったことある？
- RAG（Elasticsearch、ベクトルDB）は経験ある？
Q2. 何に一番興味がある？
- A) LangGraphのフロー制御 → サブグラフ、条件分岐、並列実行の理解
- B) Plan-and-Execute + Reflection → エージェントの思考パターン
- C) RAGツールの実装 → 検索システムの構築
- D) 全体をシンプルに作り直す → ミニマム構成で再構築
Q3. 再実装の目的は？
- 理解を深めるため？
- 自分のプロジェクトに応用したい？
- 特定の技術（例：LangGraph）を覚えたい？
これ教えてくれたら、どこをどう再実装するといいかアドバイスできるよ！ ✨
> 学びたいところは、AIエージェントを作るコア部分で、
LangGraphによるエージェントフロー設計やPlan-and-Executeパターンを学びたい。逆にツール作りやインデックス構築の部分は不要。
LangChain/LangGraphは触ったことはない、RAGはかなり理解が深い。
再実装の目的はAIエージェント作りの基礎の理解を深めるため。
ハンズオン形式で学びたいのでハンズオン形式での資料がほしいが、他に情報は必要？
⏺ なるほど！いい感じに絞れてきたね！ 🎯
ハンズオン資料を作る前に、いくつか確認させて〜
---
確認したいこと
Q1. 実行環境について
- このchapter4のプロジェクト内で進める？それとも別ディレクトリで一から作る？
- Docker（Elasticsearch, Qdrant）を起動して実際のツールを使う？それともモックツール（ダミーの検索結果を返す）で進める？
- RAG理解済みならモックで十分かも！エージェントのフロー学習に集中できるし
Q2. ハンズオンの進め方
- A) 写経スタイル: ステップごとにコードを自分で書いていく（理解が深まる）
- B) 実行＆解説スタイル: 解説付きコードを読みながら実行していく（早い）
- C) 穴埋めスタイル: 骨組みは用意して、核心部分だけ自分で実装する
Q3. 最終成果物のイメージ
- フル版: chapter4と同等の機能（サブグラフ、並列実行、リフレクション全部入り）
- シンプル版: 最小構成から段階的に機能追加（おすすめ！）
- Step1: 単純なグラフ（直列フロー）
- Step2: Plan-and-Execute追加
- Step3: Reflection追加
- Step4: サブグラフ・並列実行追加
Q4. 使用するLLM
- OpenAI API？Claude API？その他？
---
この辺教えてくれたら、いい感じのハンズオン資料作れると思う！✨
> 別ディレクトリで。Dockerを起動して実際のツールを使う形式で、そこはchapter4ディレクトリそのままでいい。
ハンズオンは写経スタイルで。僕に考えさせるポイントも作るようにしてみて。
最終的にはフル版まで作るが、段階的に作るようにしよう。どういう段階を踏めば理解できるか検討したいので、複数パターン出してほしい。
使用するLLMは元々と同じでいい
⏺ いいね！しっかり考えながら進めたいってことだね 💪
じゃあ段階的に学ぶパターンを4つ出すね！
---
📚 段階的学習パターン案
パターンA: 構造駆動（LangGraphから攻める）
LangGraphの仕組みを先に理解 → エージェントパターンを乗せる
| Step | 内容 | 学ぶこと |
|------|---------------------------|----------------------------------|
| 1 | 最小グラフ（直列3ノード） | StateGraph, ノード, エッジの基本 |
| 2 | 条件分岐を追加 | conditional_edges, 分岐ロジック |
| 3 | ループを追加 | 条件付きで前のノードに戻る |
| 4 | サブグラフ化 | グラフのネスト, 責務分離 |
| 5 | 並列実行 | Send, 複数ノード同時実行 |
| 6 | Plan-and-Execute適用 | 計画→実行→回答のフロー |
| 7 | Reflection統合 | 自己評価, リトライ |
メリット: LangGraphを体系的に理解できる、応用が効く
デメリット: 最初は「何のためにやってるか」が見えにくい
---
パターンB: 機能駆動（動くものから育てる）
最小のエージェントから機能を足していく
| Step | 内容 | 学ぶこと |
|------|-------------------------------|-----------------------------|
| 1 | 最小エージェント（質問→回答） | LangGraph基本, OpenAI連携 |
| 2 | Tool Calling追加 | ツール選択・実行の仕組み |
| 3 | Plan追加（計画→実行→回答） | 計画生成, Structured Output |
| 4 | サブタスク分割 | 複数タスクの実行 |
| 5 | Reflection追加 | 自己評価, 条件分岐, ループ |
| 6 | 並列実行 | Send, パフォーマンス向上 |
| 7 | サブグラフでリファクタ | コード整理, 再利用性 |
メリット: 常に動くものがある、達成感を得やすい
デメリット: 途中でリファクタが必要になる
---
パターンC: 課題駆動（問題を体感してから解決）
「なぜこの機能が必要か」を実感しながら進める
| Step | 内容 | 体感する課題 |
|------|------------------|---------------------------------------------|
| 1 | 最小エージェント | 「複雑な質問に1回で答えられない…」 |
| 2 | Plan追加 | 「計画はできたけど実行が直列で遅い…」 |
| 3 | 並列実行追加 | 「速くなったけど回答の質がバラバラ…」 |
| 4 | Reflection追加 | 「リトライで質は上がったけどコードが複雑…」 |
| 5 | サブグラフ化 | 「整理できた！でももっと拡張したい…」 |
| 6 | 拡張ポイント検討 | 設計の振り返り |
メリット: 「なぜ」が腹落ちする、設計判断力がつく
デメリット: 意図的に「悪い設計」を経験するので遠回り感
---
パターンD: レイヤー駆動（部品を作って組み立てる）
各要素を独立して学び、最後に統合
| Step | 内容 | 学ぶこと |
|------|-------------------|------------------------------------|
| 1 | 状態管理だけ | TypedDict, Annotated, operator.add |
| 2 | LangGraph基礎だけ | ノード, エッジ, コンパイル |
| 3 | Tool Callingだけ | OpenAI形式, ツール実行 |
| 4 | Plannerだけ | 計画生成, Structured Output |
| 5 | Reflectorだけ | 自己評価ロジック |
| 6 | 全体統合 | 部品を組み合わせてエージェント完成 |
メリット: 各要素を深く理解できる、テストしやすい
デメリット: 全体像が見えるまで時間がかかる
---
🤔 どれがいい？
個人的なおすすめは パターンB か パターンC かな！
- パターンB: 「まず動かしたい、着実に進めたい」タイプ向け
- パターンC: 「なぜその設計になるか納得したい」タイプ向け
どのパターンがしっくりくる？それとも組み合わせたい部分ある？ 🎯
> Bで行こう。
かなり色々とやり取りして、最終的にできたハンズオン資料はchapter4-handson/handson.md。Stepごとに動くものを作っていきながら、より高度なAIエージェントに進化していく学習ができるようになったと思う。
この資料を使って学ぶことで、書籍で説明されている内容を実際に手を動かしながらしっかり理解できた。
その後のハンズオン資料を作りやすくしておく
ハンズオン資料を作る時、最初は自分の好みの流れの資料を作れない。そのため、何度も何度もやり取りして資料を仕上げていく必要がある。
しかし一度作った後は、その次の章のハンズオン資料は作りやすくしたい。そこで次のハンズオン資料を作りやすくするために、作るときに参考にするhandson-guide.mdという資料を残しておいた。
この資料もClaude Codeに作ってもらった。ハンズオンを作った時のセッション上で「ハンズオン資料を作る時に検討すべきことをこのセッション内容からまとめて」といった指示をしてやりとりするだけだ。
あとは5章以降を作りたいとなった時も、この資料を参照して自分好みのハンズオンを作れそうだ。
まとめ
AI時代によって工夫をすれば自分好みの学習資料を作れるのは非常に良い。僕は手を動かして写経しながら学ぶ方が理解が深まると感じているため、このような資料をAIに作ってもらえるようになったのは良い時代だ。
