バイブコードでWeb検索AIエージェントを構築・デプロイ

┌─────────────────────────────────────────────────────────────────────┐
│                        ユーザーインターフェース (React)             │
│                    "最新のAIニュースは何ですか？"                    │
└──────────────────────────────────┬──────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      PYTHONバックエンド (FastAPI)                   │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────────┐   │
│  │   エージェント │────▶│    LLM      │────▶│   ウェブスクラパー    │   │
│  │ (オーケストレータ)│    │  (脳)       │     │ (BrightData SERP)   │   │
│  └─────────────┘     └─────────────┘     └─────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

mkdir deep-research-agent

ウェブ検索が必要なときに検索して質問に答えられるディープリサーチAIエージェントを構築したいです。

バックエンドはPython、フロントエンドはReactになります。以下の構造を持つクリーンなプロジェクト構造を設定してください：
- サービスフォルダにバックエンドとフロントエンドディレクトリ
- 共通コマンド実行用のMakefile

今のところフォルダ構造だけ作成してください。

services/backend/ にPythonバックエンドをセットアップします。

必要となるのは：
- FastAPI (ウェブサーバー用)
- API呼び出し用の非同期HTTPクライアント
- 環境変数サポート
- データ検証

必要な依存関係を含むrequirements.txtを作成してください。

2つのサービスのAPIキーを保存する必要があります：
1. Zeabur AI Hub - OpenAI互換LLM API (トークン: ZEABUR_API_TOKEN)
2. BrightData - ウェブスクレイピングサービス (トークン: BRIGHTDATA_API_TOKEN)

backendフォルダに.env.exampleテンプレートと.envファイルを作成してください。また、ZEABUR_MODEL変数をgpt-4o-miniにデフォルト設定してください。

また、pydantic-settingsを使用して環境変数を読み込むconfig.pyファイルも作成してください。
重要: CORS_ORIGINSフィールドにはUnion[List[str], str]型を使用し、@field_validatorを追加して.envからのカンマ区切り文字列をリストに解析してください。これにより解析エラーを防ぎます。

Zeabur AI Hubと通信する必要があります。これはOpenAI互換APIです。

services/backend/llm.py に以下の機能を持つPythonクライアントを作成してください：
- プロンプト送信とレスポンス取得
- 会話履歴のサポート (チャット)
- エラー処理

ベースURLは https://sfo1.aihub.zeabur.ai で、標準的なOpenAIチャットコンプリーション形式を使用します。HTTP呼び出しにはasync/awaitを使用してください。

BrightDataのSERP APIを使用してウェブ検索を行いたいです。

services/backend/scraper.py に以下の機能を持つPythonクライアントを作成してください：
- 検索クエリを受け取りGoogle検索結果を返す
- https://api.brightdata.com/request のBrightData APIを使用
- 解析された検索結果をJSONとして返す
- エラー処理をクラッシュなしで行う

APIはBearerトークン認証を使用し、以下のパラメータが必要です：
- zone: "serp_api1"
- format: "json"
- data_format: "parsed_light"

重要な修正点：
1. urllib.parse.quote_plus をインポートして使用し、Google検索URL構築前に検索クエリをURLエンコードしてください
2. "language"パラメータを含めないでください (BrightDataはそれを拒否します)
3. BrightDataは {status_code, headers, body} 構造のレスポンスを返します。_parse_search_resultsで：
   - データに 'body' フィールドがあるか確認し抽出
   - bodyがJSON文字列の場合、json.loads()で解析
   - 次に 'organic' または 'organic_results' フィールドを検索結果として探す

今度はすべてを統合するAIエージェントを構築します。

services/backend/agent.py に以下の機能を持つエージェントを作成してください：
1. ユーザーの質問を受け取る
2. LLMを使用して判断: "これは現在のウェブ情報が必要ですか？"
3. はいの場合: 検索キーワードを抽出し、ウェブ検索を行い、結果に基づいて回答
4. いいえの場合: LLMの知識から直接回答

エージェントは作成したLLMクライアントとウェブスクラッパーを使用してください。各ステップで何が起こっているか確認できるようにロギングを追加してください。

重要: answer()メソッドはuse_web_searchパラメータを受け入れる必要があります (デフォルトはTrue)。
use_web_searchがFalseの場合、ウェブ検索決定ロジックを完全にスキップしてLLMの知識から直接回答してください。

services/backend/main.py に以下の機能を持つFastAPIサーバーを作成してください：
- 質問を受け取りエージェントの回答を返すPOST /api/queryエンドポイント
- ヘルスチェックエンドポイント (GET / と GET /health)
- config.py設定を使用して環境変数からAPIキーを読み込み
- フロントエンドから呼び出せるようにCORSを有効化

リクエストは {"query": "...", "use_web_search": true} で、レスポンスは {"answer": "..."} である必要があります。

重要: 非推奨の@app.on_event("startup")および@app.on_event("shutdown")デコレーターを使用しないでください。
代わりに現代的な方法を使用してください：
1. contextlibからasynccontextmanagerをインポート
2. スタートアップとシャットダウンを処理するlifespan非同期コンテキストマネージャー関数を作成
3. FastAPIに渡す: app = FastAPI(lifespan=lifespan)

これにより非推奨警告を回避します。

Viteを使用してservices/frontend/ にReact TypeScriptフロントエンドをセットアップします。

必要となるのは：
- TypeScript付きReact
- マークダウンレンダラー (react-markdown with remark-gfm) でフォーマットされたAI応答を表示
- API URLの環境変数サポート

必要な設定ファイル (package.json, vite.config.ts, tsconfig.json, index.html) と基本的なエントリーポイントファイルを作成してください。

services/frontend/src/App.tsx にメインReactコンポーネントを作成してください。

以下の機能を持つシンプルなチャットインターフェースが欲しいです：
- 入力フィールドに質問を入力
- 「Ask」ボタンをクリック (またはEnterを押して) 提出
- 待機中のスピナーローディング表示
- AIの回答をマークダウンとして表示 (表、リスト、リンク等)
- 最近のクエリ履歴表示 (直近5件)
エラーを適切に処理しエラーメッセージをユーザーに表示

services/frontend/src/App.css にモダンでプロフェッショナルなCSSスタイルを作成してください。

欲しいのは：
- グラデーション背景 (ダークブルーからレッドトーン)
- 中央にきれいな白カードコンテンツ
- 良い入力フィールドとボタンスタイル
- スピニングローダーアニメーション
- マークダウンコンテンツの良いタイポグラフィ (見出し、リスト、表、コードブロック)
- モバイル対応デザイン

プロフェッショナルで洗練された外観にしてください。

ルートプロジェクトに以下のコマンドを持つMakefileを作成：
- すべての依存関係をインストール (バックエンドとフロントエンド両方)
- バックエンドサーバーを実行
- フロントエンド開発サーバーを実行
- 両方を一緒に実行

"make install"と"make dev"だけで簡単に開始できるようにしてください。

重要: 両方のコマンドが機能するようにコマンドエイリアスを追加：
- make run-backend と make dev-backend (両方同じことを行う)
- make run-frontend と make dev-frontend (両方同じことを行う)

これにより異なる命名規則の整合性を確保します。

フロントエンドに「Web検索」チェックボックスを追加し、AIエージェントがBrightDataを使用するかどうかをユーザーが制御できるようにします。

フロントエンド変更 (services/frontend/src/App.tsx)：
- チェックボックス状態 (useWebSearch) を追加しデフォルトをtrueに
- 入力フィールド上部に明確なラベルと説明を持つチェックボックスUIを追加
- チェックボックス状態 (use_web_search) をAPIリクエストボディで送信
- ウェブ検索が有効かどうかに基づいてローディングメッセージを更新

バックエンド変更 (services/backend/main.py)：
- QueryRequestモデルを更新してオプションのuse_web_searchブール値を受け入れる (デフォルトはTrue)
- このパラメータをエージェントに渡す

バックエンド変更 (services/backend/agent.py)：
- run()メソッドを更新してuse_web_searchパラメータを受け入れる
- use_web_searchがFalseの場合、すべてのウェブ検索ロジックをスキップしLLMで直接回答
- ウェブ検索が有効/無効かどうかを示すロギングを追加

この機能によりユーザーはウェブ検索あり/なしでの回答を比較できます。

deep-research-agent/
├── services/
│   ├── backend/
│   │   ├── .env
│   │   ├── .env.example
│   │   ├── agent.py
│   │   ├── llm.py
│   │   ├── main.py
│   │   ├── requirements.txt
│   │   └── scraper.py
│   └── frontend/
│       ├── src/
│       │   ├── App.css
│       │   ├── App.tsx
│       │   ├── index.css
│       │   └── main.tsx
│       ├── .env
│       ├── index.html
│       ├── package.json
│       ├── tsconfig.json
│       └── vite.config.ts
└── Makefile

# すべての依存関係をインストール
make install

# または個別にインストール：
cd services/backend && pip3 install -r requirements.txt
cd services/frontend && npm install

make dev-backend
# または: cd services/backend && python3 main.py

✅ 環境ロード成功
🔗 Zeabur AI Hubに接続中: https://sfo1.aihub.zeabur.ai
🤖 モデル使用中: gpt-4o-mini
🚀 Web検索AIエージェントサーバーが http://localhost:8000 で実行中

make dev-frontend
# または: cd services/frontend && npm run dev

VITE ready in XXX ms
➜  Local:   http://localhost:5173/

make install
make dev-backend  # ターミナル1
make dev-frontend # ターミナル2