DeepReSearch は、LangGraph と LangChain を用いて多段階のウェブリサーチを編成する実験的なリサーチコパイロットです。自動計画、反復的な検索、人間によるチェックポイントを組み合わせ、構造化されたレポートを生成します。現在は FastAPI + LangGraph で構成されたバックエンドに加え、Next.js 製の Web コンソールからリアルタイムに進捗を監視・操作できるようになっています。
- LangGraph ワークフロー: クエリ解析 → 調査計画生成 → ReAct ベースの検索 → 結果レポート化をステートマシンで制御。
- Human in the loop: LangGraph の
interruptを利用し、調査計画を人間がレビュー・修正した上で再開可能。 - リアルタイム進捗 UI: WebSocket 経由のイベントログを Next.js から視覚化。調査計画のレビュー・編集、再開操作、レポート閲覧をブラウザ内で完結。
- 外部ツール連携: DuckDuckGo Search (
ddgs)、日付取得、検索結果の振り返りツールを LangChain Tools としてバインド。 - グラフ可視化:
graph.get_graph().draw_mermaid_png()により、現在の LangGraph ノード構成をgraph.pngに出力。
- Python 3.13 以上
- Node.js 18.17 以上 (Next.js 16 の動作要件)
- OpenRouter API キー (
OPENROUTER_API_KEY) - ネットワークアクセス（Web リサーチに DuckDuckGo を使用）
-
依存関係を同期し、仮想環境をアクティベートします。
uv sync source .venv/bin/activate -
OpenRouter の API キーを環境変数に設定します。
.envを利用する場合はpython-dotenvなどで読み込んでください。export OPENROUTER_API_KEY="your-key"
python -m pytestカバレッジと視覚的なレポートが必要な場合は次のように実行します。
python -m pytest --cov=src/backend --cov-report=term-missing --cov-report=htmlHTML レポートは htmlcov/index.html に生成され、ブラウザや VS Code の Live Preview で確認できます。
-
依存関係をインストールします。
cd src/frontend npm install -
必要に応じて
.env.localを作成し、API / WebSocket の接続先を設定します。# NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000 # NEXT_PUBLIC_WS_URL=ws://127.0.0.1:8000/ws/research
これらの値を変更すると、ブラウザから参照するバックエンドの URL を切り替えられます。
uvicorn src.backend.api.main:app --reload別ターミナルで Next.js の開発サーバーを立ち上げます。
cd src/frontend
npm run devブラウザで http://localhost:3000 を開くと DeepReSearch Console が表示され、以下をリアルタイムに確認できます。
- スレッド一覧と各ステータス
- 調査ログと進行中ステップ
- 調査計画のレビュー・編集フォーム (interrupt 発生時)
- 生成済みプランとレポートの閲覧
バックエンド API のエンドポイント一覧は http://127.0.0.1:8000/docs から確認できます。
ローカルに Node.js や Python の実行環境を構築せずに起動する場合は Docker Compose を利用できます。
-
OpenRouter の API キーをホスト側で環境変数として設定します。
export OPENROUTER_API_KEY="your-key"
-
コンテナをビルドして起動します。
docker compose up --build
-
ブラウザで
http://localhost:3000にアクセスするとフロントエンドが、http://localhost:8000/docsにアクセスするとバックエンド API のドキュメントが確認できます。
ローカルのソース更新を即時反映したい場合は、開発用オーバーライドを併用します。
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --buildこの構成ではバックエンドは uvicorn --reload、フロントエンドは Next.js の dev サーバーが起動し、src/backend や src/frontend 配下の変更がホットリロードされます。終了する際は Ctrl+C で停止してください。
src/backend/agent.py—OSSDeepResearchAgent。LangGraph グラフの定義とツールバインディングを管理。src/backend/api/— FastAPI エンドポイント群（ヘルスチェック、スレッド状態、WebSocket HITL インタフェース）。src/backend/ai/analyze/query_analyze.py— クエリ解析モジュールとResearchParametersモデル。src/backend/ai/schedule/plan_reserch.py— 調査計画生成モジュールと関連 Pydantic モデル。src/backend/ai/reflect/reflect_search_result.py— 検索結果の振り返りロジック。src/backend/ai/search/— ReAct で利用するシステムプロンプトなど検索関連の補助コード。src/backend/tools/— DuckDuckGo Web リサーチ、日付取得、検索結果の振り返りツール実装。src/frontend/src/app/— Next.js の画面実装。components/に UI コンポーネントを分割配置し、page.tsxがコンソールのエントリーポイント。src/frontend/src/lib/— API クライアントおよび WebSocket クライアント。clients/— WebSocket 経由で API と対話する CLI クライアント群。
- LangGraph の状態復元には
OPENROUTER_API_KEYが必須です。キーが未設定の場合、LLM 呼び出しで失敗します。 src/backend/agent.pyのget_compiled_graph()はMemorySaverを利用しているため、Human in the loop 中断後も状態を保持します。複数セッションを並列で扱う場合はthread_idを明示的に管理してください。- フロントエンドの DeepReSearch Console は WebSocket イベントをストリームし、調査計画のレビューや進捗がタイムライン順に並ぶよう調整されています。調査計画を更新すると、その後のメッセージがリアルタイムに追従します。
src/frontend/src/env.tsに開発用のデフォルト接続先が定義されています。本番環境へデプロイする場合はNEXT_PUBLIC_API_BASE_URLとNEXT_PUBLIC_WS_URLを環境変数で上書きしてください。