gen: #file:index.md にドキュメントを英語で記載してください。読者は LangGraph の知識がない人でできるだけ丁寧な説明と必要な出典を添えたドキュメントが望ましいです。以下の前提を考慮してください。

ks6088ts · ks6088ts · commit 14aa2fba260c · 2025-08-05T12:14:07.000+09:00
---
- data/: 仮想システム KABUTO のドキュメント。LLM が事前情報で解決できないことを証明するために架空のシステムのデータを生成している。FAQやドキュメントなどを配置している
- notebooks: jupyter lab で簡単に実行できるサンプル集。実行例と合わせて確認できる。主に説明目的
- scripts: ターミナルから実行できるスクリプト。
- template_langgraph.agents: 各種エージェントのユースケース
  - kabuto_helpdesk_agent: prebuilt な関数を使った簡易サンプル。初手はこれを読んで欲しい
  - chat_with_tools_agent: kabuto_helpdesk_agent とほぼ同様の処理を実装している tool call agent。ワークフローの実装や基礎的な LangGraph の関数の説明目的
  - issue_formatter_agent: structured output で構造化データに変換するサンプル
  - task_decomposer_agent: AI Agent の planning タスクの部分的な実装
  - supervisor_agent: supervisor パターンを langgraph supervisor パッケージを使って簡易実装したもの
- template_langgraph.llms: LLM の API wrapper 群
- template_langgraph.tools: AI Agent が tool calling する際の tool 群
- template_langgraph.utilities: ユーティリティライブラリ
diff --git a/docs/index.md b/docs/index.md
@@ -1,98 +1,253 @@
-# template-langgraph
+# LangGraph AI Agent Template
+
+A comprehensive template project for building AI agents using [LangGraph](https://langchain-ai.github.io/langgraph/), demonstrating various agent patterns, tool integration, and real-world use cases.
+
+## What is LangGraph?
+
+[LangGraph](https://langchain-ai.github.io/langgraph/) is a framework built on top of [LangChain](https://python.langchain.com/) that enables you to create stateful, multi-agent workflows. Unlike traditional chatbots that handle single interactions, LangGraph allows you to build complex AI systems that can:
+
+- Maintain conversation state across multiple turns
+- Use tools and external APIs
+- Implement complex reasoning patterns
+- Coordinate multiple AI agents
+- Handle cyclical workflows and conditional logic
+
+This template demonstrates these capabilities through practical examples using a fictional system called "KABUTO" for troubleshooting scenarios.
+
+## Project Overview
+
+This project showcases different AI agent patterns and architectures, from simple tool-calling agents to complex multi-agent systems. The examples use a fictional technical support scenario to demonstrate how agents can retrieve information from multiple data sources and provide structured responses.
+
+### Why This Template Exists
+
+Most AI applications need to:
+
+1. **Access external information** - LLMs don't have access to your specific data
+2. **Use tools** - Perform actions beyond text generation
+3. **Maintain context** - Remember previous interactions
+4. **Handle complex workflows** - Break down tasks into manageable steps
+
+This template provides working examples of all these patterns using LangGraph.
 
 ## Prerequisites
 
 - [Python 3.10+](https://www.python.org/downloads/)
-- [uv](https://docs.astral.sh/uv/getting-started/installation/)
-- [GNU Make](https://www.gnu.org/software/make/)
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) - Modern Python package manager
+- [GNU Make](https://www.gnu.org/software/make/) - For running common tasks
+- [Docker](https://www.docker.com/) - For running vector databases (optional)
 
-## Getting Started
+## Quick Start
 
-### Set up local environment
+### 1. Environment Setup
 
 ```shell
 # Clone the repository
 git clone https://github.com/ks6088ts-labs/template-langgraph.git
 cd template-langgraph
 
-# Start services using Docker Compose (Requires Docker)
-docker compose up -d
+# Install Python dependencies
+uv sync --all-extras
 
-# Create a .env file based on the template
+# Create environment configuration
 cp .env.template .env
-
-# Install required Python packages (Requires uv)
-uv sync --all-extras
+# Edit .env with your API keys (Azure OpenAI, etc.)
 ```
 
-### Set up infrastructure
+### 2. Start Supporting Services (Optional)
 
-Here are some commands you can use:
+For full functionality, start the vector databases:
+
+```shell
+# Start Qdrant and Elasticsearch using Docker
+docker compose up -d
+```
 
-**Create Qdrant collection:**
+### 3. Initialize Data Sources
 
-> [!NOTE]
-> Qdrant service is expected to be running
+**Set up Qdrant vector database:**
 
 ```shell
 uv run python scripts/qdrant_operator.py add-documents \
   --collection-name qa_kabuto \
   --verbose
 ```
 
-**Create Elasticsearch index:**
-
-> [!NOTE]
-> Elasticsearch service is expected to be running
+**Set up Elasticsearch search index:**
 
 ```shell
 uv run python scripts/elasticsearch_operator.py create-index \
   --index-name docs_kabuto \
   --verbose
 ```
 
-### Run applications
+## Project Structure
+
+### Core Components
+
+- **`data/`** - Sample data for the fictional KABUTO system (PDFs, FAQs, troubleshooting guides)
+- **`template_langgraph/`** - Main Python package containing all agent implementations
+- **`notebooks/`** - Jupyter notebooks with interactive examples and explanations
+- **`scripts/`** - Command-line tools for running agents
+
+### Agent Examples (`template_langgraph/agents/`)
+
+This project includes several agent implementations, each demonstrating different LangGraph patterns:
+
+#### 1. `kabuto_helpdesk_agent/` - **Start Here!**
+
+A simple agent using LangGraph's prebuilt `create_react_agent` function. This is the best starting point for understanding the basics.
+
+**Key concepts:** ReAct pattern, tool calling, prebuilt agents
+
+#### 2. `chat_with_tools_agent/` - **Core Implementation**
+
+A manual implementation of the same logic as the helpdesk agent, showing how LangGraph workflows are built from scratch.
+
+**Key concepts:** Graph construction, state management, node functions, edges
+
+#### 3. `issue_formatter_agent/` - **Structured Output**
+
+Demonstrates how to get structured data from AI responses using Pydantic models.
+
+**Key concepts:** Structured output, data validation, response formatting
+
+#### 4. `task_decomposer_agent/` - **Planning & Decomposition**
+
+Shows how to break down complex tasks into smaller, manageable steps.
+
+**Key concepts:** Task planning, multi-step reasoning, conditional workflows
+
+#### 5. `supervisor_agent/` - **Multi-Agent Coordination**
 
-#### LangGraph Studio
+Implements the supervisor pattern where one agent coordinates multiple specialized agents.
 
-From the command line, you can run the LangGraph Studio to interact with the application.
+**Key concepts:** Multi-agent systems, agent coordination, supervisor patterns
+
+### Supporting Modules
+
+- **`template_langgraph/llms/`** - LLM API wrappers (Azure OpenAI, etc.)
+- **`template_langgraph/tools/`** - Tool implementations for search, data retrieval
+- **`template_langgraph/utilities/`** - Helper functions for document loading and processing
+
+## Running the Examples
+
+### Option 1: LangGraph Studio (Recommended for Development)
+
+[LangGraph Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/) provides a visual interface for developing and debugging agents:
 
 ```shell
 uv run langgraph dev
 ```
 
+This opens a web interface where you can:
+
+- Visualize agent workflows
+- Step through executions
+- Debug state transitions
+- Test different inputs
+
 ![langgraph-studio.png](./images/langgraph-studio.png)
 
-#### Jupyter Lab
+### Option 2: Jupyter Notebooks (Best for Learning)
 
-From Jupyter Lab, you can run the notebooks in the `notebooks` directory to run various applications.
+Interactive notebooks with explanations and examples:
 
 ```shell
-# Run Jupyter Lab
 uv run jupyter lab
-
-# Go to http://localhost:8888 in your browser and run notebooks/*.ipynb.
+# Navigate to http://localhost:8888 and open notebooks/*.ipynb
 ```
 
 ![jupyterlab.png](./images/jupyterlab.png)
 
-#### Terminal
+### Option 3: Command Line (Production-like)
 
-From the command line, you can run scripts in the `scripts` directory to run various applications.
+Run agents from the terminal:
 
 ```shell
 uv run python scripts/agent_operator.py run \
   --name "chat_with_tools_agent" \
-  --question "KABUTOの起動時に、画面全体が紫色に点滅し、システムがフリーズします。KABUTO のマニュアルから、関連する情報を取得したり過去のシステムのトラブル シュート事例が蓄積されたデータベースから、関連する情報を取得して質問に答えてください" \
+  --question "KABUTO startup issue: screen flashes purple and system freezes" \
   --verbose
-2025-08-05 11:27:40,949 [    INFO] -------------------- (agent_operator.py:104)
-2025-08-05 11:27:40,949 [    INFO] Event: {'chat_with_tools': {'messages': [AIMessage(content='', additional_kwargs={'tool_calls': [{'index': 0, 'id': 'call_LTenxsczZMuCdIAK8IBT9e7r', 'function': {'arguments': '{"keywords": "KABUTO 起動 紫色 点滅 フリーズ"}', 'name': 'search_elasticsearch'}, 'type': 'function'}, {'index': 1, 'id': 'call_POOYozcQOSjnXEaVkbxQpTz7', 'function': {'arguments': '{"keywords": "KABUTO 起動 紫色 点滅 フリーズ"}', 'name': 'search_qdrant'}, 'type': 'function'}]}, response_metadata={'finish_reason': 'tool_calls', 'model_name': 'gpt-4o-2024-11-20', 'system_fingerprint': 'fp_ee1d74bde0'}, id='run--60587ca8-d54e-4c66-8d9c-c5a99ae479a9-0', tool_calls=[{'name': 'search_elasticsearch', 'args': {'keywords': 'KABUTO 起動 紫色 点滅 フリーズ'}, 'id': 'call_LTenxsczZMuCdIAK8IBT9e7r', 'type': 'tool_call'}, {'name': 'search_qdrant', 'args': {'keywords': 'KABUTO 起動 紫色 点滅 フリーズ'}, 'id': 'call_POOYozcQOSjnXEaVkbxQpTz7', 'type': 'tool_call'}])]}} (agent_operator.py:105)
-2025-08-05 11:27:41,458 [    INFO] -------------------- (agent_operator.py:104)
-2025-08-05 11:27:41,458 [    INFO] Event: {'tools': {'messages': [ToolMessage(content='"[ElasticsearchOutput(file_name=\'docs_kabuto.pdf\', content=\'「⻤灯」の実⾏中は、冷却システムが⼀時的に停⽌し、無⾳となる。これは内部エネルギーの流れを最適化するため\\\\nの仕様であり、異常ではない。ただし、この無⾳状態が 15 分以上継続する場合は、過熱の可能性があるため、アプリ\\\\nケーションの強制終了およびシステムの再起動が推奨される。\\\\n第 3 章  ソフトウェア・オペレーション\\\\n3.1 起動プロトコル\\\\nKABUTO の起動シーケンスは、「シノビ・プロトコル」に基づき実⾏される。このプロトコルの初期化フェーズで、\\\\n内部クロックと接続された外部周辺機器のクロックとの同期に失敗した場合、画⾯全体が紫⾊に点滅し、システムが\'), ElasticsearchOutput(file_name=\'docs_kabuto.pdf\', content=\'2.1 電源・起動システム\\\\nKABUTO の電源ランプは、通常の動作状態を以下のパターンで表⽰する。待機状態では⾚⾊点滅、稼働状態では⻘⾊\\\\n点滅が繰り返される。このパターンにない緑⾊の点滅は、システムが「禅モード」に移⾏していることを⽰す。禅モ\\\\nードでは、パフォーマンスが最⼩限に抑えられ、バックグラウンドでのシステム⾃⼰修復が実⾏される。このモード\\\\nからの強制離脱は、 KABUTO 本体に設置された「⿓⽟」ボタンを 5 秒以上⻑押しすることで可能となる。また、電源\\\\nOFF 後も微細な電流が流れ続ける「夢の海」と呼ばれる待機モードが存在し、これにより次回の起動⾼速化が図られ\'), ElasticsearchOutput(file_name=\'docs_kabuto.pdf\', content=\'フリーズする。この問題は、 KABUTO 本体の再起動前に、すべての周辺機器を 5 秒以上電源から抜くことで、外部ク\\\\nロックのキャッシュがクリアされ、同期が正常に⾏われる可能性が⾼まる。\\\\n3.2 セキュリティ・認証システム\\\\nログイン認証は、パスワード⼊⼒に加え、セキュリティモジュール「百⻤夜⾏」によるログイン試⾏者の「精神波\\\\n形」解析を伴う。パスワードが正しく⼊⼒された場合でも、精神波形が登録されたユーザーと⼀致しないと判断され\')]"', name='search_elasticsearch', id='33ac53bd-22d8-4fe1-9094-bd4869c4771a', tool_call_id='call_LTenxsczZMuCdIAK8IBT9e7r'), ToolMessage(content='"[QdrantOutput(file_name=\'./data/qa_kabuto.csv\', content=\'q: KABUTOの起動時に、画面全体が紫色に点滅し、システムがフリーズします。 a: この現象は、「シノビ・プロトコル」が初期化フェーズで、内部クロックと外部クロックの同期に失敗している場合に発生します。KABUTO本体を再起動する前に、必ず接続されているすべての周辺機器を5秒以上、電源から抜いてください。これにより、外部クロックのキャッシュがクリアされ、同期が正常に行われる可能性が高まります。\'), QdrantOutput(file_name=\'./data/qa_kabuto.csv\', content=\'q: KABUTOの電源ランプが、赤と青の交互点滅ではなく、緑色で点滅しています。 a: 通常、電源ランプは赤（待機中）と青（稼働中）の点滅を繰り返します。緑色の点滅は、KABUTOが「禅モード」に入っており、パフォーマンスを最小限に抑え、バックグラウンドでシステム自己修復を行っている状態を示します。この状態では、ユーザー操作はほとんど受け付けられません。このモードから強制的に脱出するには、KABUTO本体の「龍玉」ボタンを5秒以上長押ししてください。\'), QdrantOutput(file_name=\'./data/qa_kabuto.csv\', content=\'q: KABUTOの画面の隅に、時々「狐火」のような光の点が、不規則に現れては消えます。 a: 「狐火」は、KABUTOの演算コア「稲荷」が、膨大な量のタスクを処理しきれずに、一部の計算結果が視覚的なノイズとして現れている現象です。これは、システム負荷が高いことを示しています。この現象が頻繁に発生する場合は、バックグラウンドで動作している不要なアプリケーションを終了させるか、KABUTOを再起動してください。\')]"', name='search_qdrant', id='97878816-f478-4bd5-a78e-0b668311bf05', tool_call_id='call_POOYozcQOSjnXEaVkbxQpTz7')]}} (agent_operator.py:105)
-2025-08-05 11:27:45,507 [    INFO] -------------------- (agent_operator.py:104)
-2025-08-05 11:27:45,508 [    INFO] Event: {'chat_with_tools': {'messages': [AIMessage(content='KABUTOの起動時に画面全体が紫色に点滅し、システムがフリーズする問題について、以下の情報が得られました。\n\n### 原因\nこの現象は、「シノビ・プロトコル」が初期化フェーズで、内部クロックと外部クロックの同期に失敗している場合に発生します。\n\n### 解決方法\n1. **周辺機器の電源を切る**:\n   - KABUTO本体を再起動する前に、接続されているすべての周辺機器を5秒以上電源から抜いてください。\n   - これにより、外部クロックのキャッシュがクリアされ、同期が正常に行われる可能性が高まります。\n\n2. **強制再起動**:\n   - 必要に応じて、KABUTO本体の「龍玉」ボタンを5秒以上長押しして強制再起動を試みてください。\n\n### 注意点\n- この問題が頻繁に発生する場合は、システムの内部エネルギー流れや冷却システムの状態を確認する必要があります。\n- 再起動後も問題が解決しない場合は、専門の技術者に相談することをお勧めします。\n\nこれらの手順を試してみてください。問題が解決しない場合は、さらに詳細な情報を提供していただければ追加のサポートを行います。', additional_kwargs={}, response_metadata={'finish_reason': 'stop', 'model_name': 'gpt-4o-2024-11-20', 'system_fingerprint': 'fp_ee1d74bde0'}, id='run--c3c0ecb8-b85f-4072-8420-eeb94f2b62a1-0')]}} (agent_operator.py:105)
 ```
 
-## Tutorials
+Example output showing the agent's reasoning process:
+
+```text
+Event: {'chat_with_tools': {'messages': [AIMessage(content='', tool_calls=[
+  {'name': 'search_elasticsearch', 'args': {'keywords': 'KABUTO startup purple flashing freeze'}},
+  {'name': 'search_qdrant', 'args': {'keywords': 'KABUTO startup purple flashing freeze'}}
+])]}}
+
+Event: {'tools': {'messages': [ToolMessage(content='Found documentation about startup protocol...')]}}
+
+Event: {'chat_with_tools': {'messages': [AIMessage(content='
+### Problem Analysis
+The purple screen flashing during KABUTO startup indicates a "Shinobi Protocol" initialization failure...
+
+### Solution
+1. **Disconnect peripheral devices**: Unplug all connected devices for 5+ seconds
+2. **Clear external clock cache**: This resolves clock synchronization issues
+3. **Restart KABUTO**: Use the "Dragon Ball" button for 5+ seconds if needed
+')]}}
+```
+
+## Key Concepts Demonstrated
+
+### 1. **ReAct Pattern** (Reasoning + Acting)
+
+The foundation of modern AI agents - the ability to reason about what to do, take actions, and reason about the results.
+
+### 2. **Tool Calling**
+
+How agents can use external functions to:
+
+- Search databases (Elasticsearch, Qdrant)
+- Call APIs
+- Process files
+- Execute calculations
+
+### 3. **State Management**
+
+How LangGraph maintains context across multiple interaction steps, enabling complex multi-turn conversations.
+
+### 4. **Conditional Workflows**
+
+Using graph structures to create branching logic based on agent decisions or external conditions.
+
+### 5. **Multi-Agent Systems**
+
+Coordinating multiple specialized agents to handle complex tasks that require different expertise.
+
+## Data Sources Explained
+
+The project uses fictional data about a system called "KABUTO" to demonstrate real-world scenarios:
+
+- **`data/docs_kabuto.pdf`** - Technical documentation (simulates user manuals)
+- **`data/qa_kabuto.csv`** - FAQ database (simulates past support tickets)
+- **`data/docs_kabuto.md`** - Additional documentation
+
+This fictional data serves a purpose: it proves that the AI agents can work with information that isn't in the LLM's training data, demonstrating the value of retrieval-augmented generation (RAG).
+
+## Next Steps
+
+1. **Start with the basics**: Run the `kabuto_helpdesk_agent` example
+2. **Understand the implementation**: Compare it with `chat_with_tools_agent`
+3. **Explore advanced patterns**: Try the task decomposer and supervisor agents
+4. **Build your own**: Use this template as a starting point for your use case
+
+## Learning Resources
+
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [LangChain Documentation](https://python.langchain.com/)
+
+## Architecture Examples
+
+This template demonstrates several proven agent architectures:
+
+1. **Single Agent with Tools** - Basic tool-calling pattern
+2. **ReAct Agent** - Reasoning and acting in loops
+3. **Structured Output Agent** - Returning formatted data
+4. **Planning Agent** - Breaking down complex tasks
+5. **Supervisor Agent** - Coordinating multiple agents
 
-<!-- Add docs here -->
+Each pattern is implemented with clear examples and documentation to help you understand when and how to use them.
