diff --git a/docs/index.ja.md b/docs/index.ja.md index 4020c68..82f590f 100644 --- a/docs/index.ja.md +++ b/docs/index.ja.md @@ -83,6 +83,20 @@ uv run python scripts/elasticsearch_operator.py create-index \ --verbose ``` +**任意: 追加データソースの設定:** + +```shell +# Azure AI Search +make create-ai-search-index + +# Azure Cosmos DB +make create-cosmosdb-index + +# またはオペレータースクリプトを直接使用: +# uv run python scripts/ai_search_operator.py add-documents --verbose +# uv run python scripts/cosmosdb_operator.py add-documents --verbose +``` + ## プロジェクト構造 ### コアコンポーネント @@ -91,6 +105,11 @@ uv run python scripts/elasticsearch_operator.py create-index \ - **`template_langgraph/`** - すべてのエージェント実装を含むメイン Python パッケージ - **`notebooks/`** - インタラクティブな例と説明付き Jupyter ノートブック - **`scripts/`** - エージェント実行用コマンドラインツール + - `agent_operator.py` - プロダクションエージェント用メインランナー + - `demo_agents_operator.py` - シンプルなデモエージェント用ランナー + - データベース/検索オペレーター(`qdrant_operator.py`、`elasticsearch_operator.py`、`ai_search_operator.py`、`cosmosdb_operator.py`) + - LLM テストオペレーター(`azure_openai_operator.py`、`azure_ai_foundry_operator.py`、`ollama_operator.py`) + - その他ユーティリティ(`dify_operator.py`、`otel_operator.py`) ### エージェントの例(`template_langgraph/agents/`) @@ -104,9 +123,17 @@ uv run python scripts/elasticsearch_operator.py create-index \ - `news_summarizer_agent/` — Web/YouTube 要約。取得 → 要約 → 通知。主要概念: 扇形サブタスク、Notifier/Scraper/Summarizer を差し替え。 - `image_classifier_agent/` — 画像分類。ローカル画像を分類し通知。主要概念: 画像 ×LLM、並列サブタスク。 +#### デモエージェント(`template_langgraph/agents/demo_agents/`) + +学習と実演用の追加シンプルエージェント: + +- `weather_agent.py` — シンプルなツール呼び出しエージェント。モック天気検索ツールを使った基本的な ReAct パターン。主要概念: ツール呼び出し、基本エージェントパターン。 +- `multi_agent.py` — マルチエージェント協調。転送機能を使ったエージェント間の引き渡しを実演。主要概念: エージェント協調、ワークフロー転送。 +- `parallel_processor_agent/` — 並列実行タスク分解。目標をタスクに分解し並列処理。主要概念: 並列処理、タスク分解、Send 操作。 + ### サポートモジュール -- `template_langgraph/llms/`: LLM ラッパー(Azure OpenAI など) +- `template_langgraph/llms/`: LLM ラッパー(Azure OpenAI、Azure AI Foundry、Ollama) - `template_langgraph/tools/`: ツール実装 - Azure AI Search(`ai_search_tool.py`) - Azure Cosmos DB Vector Search(`cosmosdb_tool.py`) @@ -242,6 +269,32 @@ uv run python scripts/agent_operator.py image-classifier-agent \ --verbose ``` +### デモエージェント実行例 + +- Weather agent(シンプルなツール呼び出し): + +```shell +uv run python scripts/demo_agents_operator.py weather-agent \ + --query "日本の天気はどうですか?" \ + --verbose +``` + +- Multi agent(エージェント協調): + +```shell +uv run python scripts/demo_agents_operator.py multi-agent \ + --query "東京の天気はどうですか?" \ + --verbose +``` + +- Parallel processor agent(タスク分解): + +```shell +uv run python scripts/demo_agents_operator.py parallel-processor-agent \ + --goal "ソフトウェア会社立ち上げのための情報収集戦略を計画する" \ + --verbose +``` + Makefile のショートカット(例: `make run-chat-with-tools-agent`, `make run-issue-formatter-agent`, `make run-news-summarizer-agent`, `make run-image-classifier-agent`)も用意しています。 ## 実演されている主要概念 @@ -289,6 +342,11 @@ LangGraph が複数のインタラクションステップにわたってコン - `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_API_VERSION` - `AZURE_OPENAI_MODEL_CHAT`, `AZURE_OPENAI_MODEL_EMBEDDING`, `AZURE_OPENAI_MODEL_REASONING` - Entra ID 認証の任意設定: `AZURE_OPENAI_USE_MICROSOFT_ENTRA_ID=true` +- Azure AI Foundry + - `AZURE_AI_FOUNDRY_INFERENCE_ENDPOINT`, `AZURE_AI_FOUNDRY_INFERENCE_API_VERSION` + - `AZURE_AI_FOUNDRY_INFERENCE_MODEL_CHAT` +- Ollama(ローカル) + - `OLLAMA_MODEL_CHAT` - Azure AI Search - `AI_SEARCH_ENDPOINT`, `AI_SEARCH_KEY`, `AI_SEARCH_INDEX_NAME` - Azure Cosmos DB(ベクター) @@ -319,9 +377,10 @@ make mcp-inspector ## 次のステップ 1. **基本から始める**: `kabuto_helpdesk_agent`の例を実行 -2. **実装を理解する**: `chat_with_tools_agent`と比較 -3. **高度なパターンを探索**: タスク分解器とスーパーバイザーエージェントを試す -4. **独自のものを構築**: このテンプレートをあなたのユースケースの出発点として使用 +2. **デモエージェントを試す**: `weather_agent`、`multi_agent`、`parallel_processor_agent`でシンプルなパターンを探索 +3. **実装を理解する**: `chat_with_tools_agent`と比較 +4. **高度なパターンを探索**: タスク分解器とスーパーバイザーエージェントを試す +5. **独自のものを構築**: このテンプレートをあなたのユースケースの出発点として使用 ## 可観測性(任意) @@ -340,10 +399,11 @@ uv run python scripts/otel_operator.py run -q "health check" -v このテンプレートは複数の実証済みエージェントアーキテクチャを実演しています: -1. **ツール付きシングルエージェント** - 基本的なツール呼び出しパターン -2. **ReAct エージェント** - ループでの推論と行動 -3. **構造化出力エージェント** - フォーマットされたデータの返却 -4. **計画エージェント** - 複雑なタスクの分解 -5. **スーパーバイザーエージェント** - 複数エージェントの協調 +1. **ツール付きシングルエージェント** - 基本的なツール呼び出しパターン(`weather_agent`) +2. **ReAct エージェント** - ループでの推論と行動(`kabuto_helpdesk_agent`) +3. **構造化出力エージェント** - フォーマットされたデータの返却(`issue_formatter_agent`) +4. **計画エージェント** - 複雑なタスクの分解(`task_decomposer_agent`) +5. **マルチエージェントシステム** - 複数エージェントの協調(`supervisor_agent`、`multi_agent`) +6. **並列処理** - 同時タスク実行(`parallel_processor_agent`) 各パターンは、いつどのように使用するかを理解するのに役立つ明確な例と文書で実装されています。 diff --git a/docs/index.md b/docs/index.md index c0c8a9a..31015d4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -83,6 +83,20 @@ uv run python scripts/elasticsearch_operator.py create-index \ --verbose ``` +**Optional: Set up additional data sources:** + +```shell +# Azure AI Search +make create-ai-search-index + +# Azure Cosmos DB +make create-cosmosdb-index + +# Or use the operator scripts directly: +# uv run python scripts/ai_search_operator.py add-documents --verbose +# uv run python scripts/cosmosdb_operator.py add-documents --verbose +``` + ## Project Structure ### Core Components @@ -91,6 +105,11 @@ uv run python scripts/elasticsearch_operator.py create-index \ - **`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_operator.py` - Main agent runner for production agents + - `demo_agents_operator.py` - Runner for simple demo agents + - Database/search operators (`qdrant_operator.py`, `elasticsearch_operator.py`, `ai_search_operator.py`, `cosmosdb_operator.py`) + - LLM testing operators (`azure_openai_operator.py`, `azure_ai_foundry_operator.py`, `ollama_operator.py`) + - Other utilities (`dify_operator.py`, `otel_operator.py`) ### Agent Examples (`template_langgraph/agents/`) @@ -104,9 +123,17 @@ This project includes several agent implementations, each demonstrating differen - `news_summarizer_agent/` — Web/YouTube summarization. Scrapes content, summarizes to `StructuredArticle`, and notifies. Key: fan-out subtasks, notifier/scraper/summarizer plugins. - `image_classifier_agent/` — Vision classification. Classifies local images and notifies results. Key: LLM-based image classification, parallel subtasks. +#### Demo Agents (`template_langgraph/agents/demo_agents/`) + +Additional simple agents for learning and demonstration: + +- `weather_agent.py` — Simple tool-calling agent. Basic ReAct pattern with mock weather search tool. Key: tool calling, basic agent pattern. +- `multi_agent.py` — Multi-agent coordination. Demonstrates agent-to-agent handoff using transfer functions. Key: agent coordination, workflow transfer. +- `parallel_processor_agent/` — Task decomposition with parallel execution. Breaks down goals into tasks and processes them in parallel. Key: parallel processing, task decomposition, Send operations. + ### Supporting Modules -- `template_langgraph/llms/`: LLM wrappers (Azure OpenAI, etc.) +- `template_langgraph/llms/`: LLM wrappers (Azure OpenAI, Azure AI Foundry, Ollama) - `template_langgraph/tools/`: Tool implementations used by agents - Azure AI Search (`ai_search_tool.py`) - Azure Cosmos DB Vector Search (`cosmosdb_tool.py`) @@ -242,6 +269,32 @@ uv run python scripts/agent_operator.py image-classifier-agent \ --verbose ``` +### Demo agent runs + +- Weather agent (simple tool calling): + +```shell +uv run python scripts/demo_agents_operator.py weather-agent \ + --query "What's the weather in Japan?" \ + --verbose +``` + +- Multi agent (agent coordination): + +```shell +uv run python scripts/demo_agents_operator.py multi-agent \ + --query "What's the weather in Tokyo?" \ + --verbose +``` + +- Parallel processor agent (task decomposition): + +```shell +uv run python scripts/demo_agents_operator.py parallel-processor-agent \ + --goal "Plan information gathering strategy for launching a software company" \ + --verbose +``` + Makefile shortcuts are also available (e.g., `make run-chat-with-tools-agent`, `make run-issue-formatter-agent`, `make run-news-summarizer-agent`, `make run-image-classifier-agent`). ## Key Concepts Demonstrated @@ -289,6 +342,11 @@ The default toolset is configured in `template_langgraph/tools/common.py` and in - `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_API_VERSION` - `AZURE_OPENAI_MODEL_CHAT`, `AZURE_OPENAI_MODEL_EMBEDDING`, `AZURE_OPENAI_MODEL_REASONING` - Optional Entra ID auth: `AZURE_OPENAI_USE_MICROSOFT_ENTRA_ID=true` +- Azure AI Foundry + - `AZURE_AI_FOUNDRY_INFERENCE_ENDPOINT`, `AZURE_AI_FOUNDRY_INFERENCE_API_VERSION` + - `AZURE_AI_FOUNDRY_INFERENCE_MODEL_CHAT` +- Ollama (local) + - `OLLAMA_MODEL_CHAT` - Azure AI Search - `AI_SEARCH_ENDPOINT`, `AI_SEARCH_KEY`, `AI_SEARCH_INDEX_NAME` - Azure Cosmos DB (vector) @@ -321,9 +379,10 @@ make mcp-inspector ## 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 +2. **Try demo agents**: Explore the simple patterns with `weather_agent`, `multi_agent`, and `parallel_processor_agent` +3. **Understand the implementation**: Compare it with `chat_with_tools_agent` +4. **Explore advanced patterns**: Try the task decomposer and supervisor agents +5. **Build your own**: Use this template as a starting point for your use case ## Observability (optional) @@ -342,10 +401,11 @@ uv run python scripts/otel_operator.py run -q "health check" -v 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 +1. **Single Agent with Tools** - Basic tool-calling pattern (`weather_agent`) +2. **ReAct Agent** - Reasoning and acting in loops (`kabuto_helpdesk_agent`) +3. **Structured Output Agent** - Returning formatted data (`issue_formatter_agent`) +4. **Planning Agent** - Breaking down complex tasks (`task_decomposer_agent`) +5. **Multi-Agent Systems** - Coordinating multiple agents (`supervisor_agent`, `multi_agent`) +6. **Parallel Processing** - Concurrent task execution (`parallel_processor_agent`) Each pattern is implemented with clear examples and documentation to help you understand when and how to use them.