gpt-researcher

GPT Researcher 開発スキル

GPT Researcher は、速度と信頼性を高めるためにエージェントの作業を並列化する、プランナー・エグゼキューター・パブリッシャーのパターンを採用した LLM ベースの自律エージェントです。

クイックスタート

Python の基本的な使い方

from gpt_researcher import GPTResearcher
import asyncio

async def main():
    researcher = GPTResearcher(
        query="What are the latest AI developments?",
        report_type="research_report",  # or detailed_report, deep, outline_report
        report_source="web",            # or local, hybrid
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    print(report)

asyncio.run(main())

サーバーの実行

# Backend
python -m uvicorn backend.server.server:app --reload --port 8000

# Frontend
cd frontend/nextjs && npm install && npm run dev

---

主要なファイルの場所

用途	主なファイル	主なクラス
メインオーケストレーター	gpt_researcher/agent.py	GPTResearcher
リサーチロジック	gpt_researcher/skills/researcher.py	ResearchConductor
レポート作成	gpt_researcher/skills/writer.py	ReportGenerator
すべてのプロンプト	gpt_researcher/prompts.py	PromptFamily
設定	gpt_researcher/config/config.py	Config
設定のデフォルト値	gpt_researcher/config/variables/default.py	DEFAULT_CONFIG
API サーバー	backend/server/app.py	FastAPI app
検索エンジン	gpt_researcher/retrievers/	各種リトリーバー

---

アーキテクチャの概要

User Query → GPTResearcher.__init__()
                │
                ▼
         choose_agent() → (agent_type, role_prompt)
                │
                ▼
         ResearchConductor.conduct_research()
           ├── plan_research() → sub_queries
           ├── For each sub_query:
           │     └── _process_sub_query() → context
           └── Aggregate contexts
                │
                ▼
         [Optional] ImageGenerator.plan_and_generate_images()
                │
                ▼
         ReportGenerator.write_report() → Markdown report

アーキテクチャの詳細な図については、references/architecture.md を参照してください。

---

コアパターン

新機能の追加（8 ステップパターン）

1. 設定 → gpt_researcher/config/variables/default.py に追加します
2. プロバイダー → gpt_researcher/llm_provider/my_feature/ に作成します
3. スキル → gpt_researcher/skills/my_feature.py に作成します
4. エージェント → gpt_researcher/agent.py に統合します
5. プロンプト → gpt_researcher/prompts.py を更新します
6. WebSocket → stream_output() 経由でイベントを送信します
7. フロントエンド → useWebSocket.ts でイベントを処理します
8. ドキュメント → docs/docs/gpt-researcher/gptr/my_feature.md を作成します

画像生成のケーススタディを含む、新機能追加の完全ガイドについては、references/adding-features.md を参照してください。

新しいリトリーバーの追加

# 1. Create: gpt_researcher/retrievers/my_retriever/my_retriever.py
class MyRetriever:
    def __init__(self, query: str, headers: dict = None):
        self.query = query
    
    async def search(self, max_results: int = 10) -> list[dict]:
        # Return: [{"title": str, "href": str, "body": str}]
        pass

# 2. Register in gpt_researcher/actions/retriever.py
case "my_retriever":
    from gpt_researcher.retrievers.my_retriever import MyRetriever
    return MyRetriever

# 3. Export in gpt_researcher/retrievers/__init__.py

リトリーバーの詳細なドキュメントについては、references/retrievers.md を参照してください。

---

設定

設定キーは、アクセス時に小文字に変換されます。

# In default.py: "SMART_LLM": "gpt-4o"
# Access as: self.cfg.smart_llm  # lowercase!

優先順位：環境変数 → JSON 設定ファイル → デフォルト値

設定の完全なリファレンスについては、references/config-reference.md を参照してください。

---

主な統合ポイント

WebSocket ストリーミング

class WebSocketHandler:
    async def send_json(self, data):
        print(f"[{data['type']}] {data.get('output', '')}")

researcher = GPTResearcher(query="...", websocket=WebSocketHandler())

MCP データソース

researcher = GPTResearcher(
    query="Open source AI projects",
    mcp_configs=[{
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
    }],
    mcp_strategy="deep",  # or "fast", "disabled"
)

MCP 統合の詳細については、references/mcp.md を参照してください。

ディープリサーチモード

researcher = GPTResearcher(
    query="Comprehensive analysis of quantum computing",
    report_type="deep",  # Triggers recursive tree-like exploration
)

ディープリサーチの設定については、references/deep-research.md を参照してください。

---

エラー処理

スキルでは、常に適切な縮退処理を使用してください。

async def execute(self, ...):
    if not self.is_enabled():
        return []  # Don't crash
    
    try:
        result = await self.provider.execute(...)
        return result
    except Exception as e:
        await stream_output("logs", "error", f"⚠️ {e}", self.websocket)
        return []  # Graceful degradation

---

重要な注意点

❌ 誤り	✅ 正しい方法
config.MY_VAR	config.my_var（小文字）
pip でインストールしたパッケージを編集する	pip install -e .
async/await を忘れる	すべてのリサーチメソッドは非同期です
None に対して websocket.send_json() を呼び出す	先に if websocket: を確認します
リトリーバーを登録しない	retriever.py の match 文に追加します

---

リファレンスドキュメント

トピック	ファイル
システムアーキテクチャと図	references/architecture.md
コアコンポーネントとシグネチャ	references/components.md
リサーチフローとデータフロー	references/flows.md
プロンプトシステム	references/prompts.md
リトリーバーシステム	references/retrievers.md
MCP 統合	references/mcp.md
ディープリサーチモード	references/deep-research.md
マルチエージェントシステム	references/multi-agents.md
機能追加ガイド	references/adding-features.md
高度なパターン	references/advanced-patterns.md
REST および WebSocket API	references/api-reference.md
設定変数	references/config-reference.md