deep-research

ディープリサーチスキル

Google Gemini のディープリサーチエージェントを活用して、詳細な調査を実行します。ドキュメントをファイル検索ストアにアップロードし、RAG に基づく回答を取得できます。永続的なワークスペース状態で調査セッションを管理します。

AI エージェント向け

機能マニフェスト、判断ツリー、出力仕様の全文を確認できます。

uv run {baseDir}/scripts/onboard.py --agent

詳細な構造化ブリーフィングは、AGENTS.md を参照してください。

コマンド	内容
uv run {baseDir}/scripts/research.py start "question"	ディープリサーチを開始します
uv run {baseDir}/scripts/research.py start "question" --context ./path --dry-run	コストを見積もります
uv run {baseDir}/scripts/research.py start "question" --context ./path --output report.md	RAG に基づく調査を実行します
uv run {baseDir}/scripts/store.py query <name> "question"	アップロード済みドキュメントを対象に簡単な質疑応答を行います

セキュリティと透明性

認証情報：このスキルには Google/Gemini API キー（GOOGLE_API_KEY、GEMINI_API_KEY、GEMINI_DEEP_RESEARCH_API_KEY のいずれか）が必要です。キーは環境変数から読み込まれ、google-genai SDK に渡されます。ログへの記録、ファイルへの書き込みは行われず、Google Gemini API 以外に送信されることもありません。

ファイルのアップロード：--context フラグを指定すると、RAG に基づく回答のためにローカルファイルが Google の一時的なファイル検索ストアにアップロードされます。機密ファイルは自動的に除外されます：.env*、credentials.json、secrets.*、秘密鍵（.pem、.key）、認証トークン（.npmrc、.pypirc、.netrc）。バイナリファイルは MIME タイプによるフィルタリングで拒否されます。ビルドディレクトリ（node_modules、__pycache__、.git、dist、build）はスキップされます。一時ストアは、--keep-context を指定しない限り、調査の完了後に自動的に削除されます。何も送信せずにアップロード対象を確認するには、--dry-run を使用してください。アップロードされるのは、--context で明示的に指定したファイルのみです。親ディレクトリやホームフォルダーが自動的にスキャンされることはありません。

非対話モード：標準入力が TTY ではない場合（エージェント／CI での使用）、確認プロンプトは自動的にスキップされます。これはエージェントとの連携を想定した動作ですが、ファイルシステムにアクセスできる自律エージェントがアップロードを実行する可能性があることを意味します。エージェントがアクセスできるパスを制限するか、--dry-run と --max-cost のガードを使用してください。

難読化なし：コードはすべて、PEP 723 のインラインメタデータを含む読みやすい Python です。バイナリブロブ、圧縮されたスクリプト、テレメトリー、分析機能はありません。ソースコード全文は github.com/24601/agent-deep-research で監査できます。

ローカル状態：調査セッションの状態は、作業ディレクトリ内の .gemini-research.json に書き込まれます。このファイルには、インタラクション ID、ストアの対応関係、アップロードハッシュが含まれます。認証情報や調査内容は含まれません。クラッシュした実行で残された孤立ストアをクリーンアップするには、state.py gc を使用してください。

前提条件

• Google API キー（GOOGLE_API_KEY または GEMINI_API_KEY 環境変数）
• uv がインストールされていること（uv のインストール手順を参照）

クイックスタート

# Run a deep research query
uv run {baseDir}/scripts/research.py "What are the latest advances in quantum computing?"

# Check research status
uv run {baseDir}/scripts/research.py status <interaction-id>

# Save a completed report
uv run {baseDir}/scripts/research.py report <interaction-id> --output report.md

# Research grounded in local files (auto-creates store, uploads, cleans up)
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --output report.md

# Export as HTML or PDF
uv run {baseDir}/scripts/research.py start "Analyze the API" --context ./src --format html --output report.html

# Auto-detect prompt template based on context files
uv run {baseDir}/scripts/research.py start "How does auth work?" --context ./src --prompt-template auto --output report.md

環境変数

次のいずれかを設定してください（優先順位の高い順に確認されます）。

変数	説明
GEMINI_DEEP_RESEARCH_API_KEY	このスキル専用のキー（最優先）
GOOGLE_API_KEY	標準の Google AI キー
GEMINI_API_KEY	Gemini 専用キー

任意のモデル設定：

変数	説明	デフォルト
GEMINI_DEEP_RESEARCH_MODEL	ファイル検索クエリに使用するモデル	gemini-3.1-pro-preview
GEMINI_MODEL	フォールバックモデル名	gemini-3.1-pro-preview
GEMINI_DEEP_RESEARCH_AGENT	ディープリサーチエージェントの識別子	deep-research-pro-preview-12-2025

調査コマンド

調査を開始する

uv run {baseDir}/scripts/research.py start "your research question"

フラグ	説明
--report-format FORMAT	出力構成：executive_summary、detailed_report、comprehensive
--store STORE_NAME	ファイル検索ストア（表示名またはリソース ID）を使って調査の根拠とします
--no-thoughts	中間の思考ステップを非表示にします
--follow-up ID	以前の調査セッションを続行します
--output FILE	完了まで待機し、レポートを単一のファイルに保存します
--output-dir DIR	完了まで待機し、構造化された結果をディレクトリに保存します（下記参照）
--timeout SECONDS	ポーリング時の最大待機時間（デフォルト：1800＝30 分）
--no-adaptive-poll	履歴に基づく適応型ポーリングを無効にし、代わりに固定間隔のカーブを使います
--context PATH	RAG に基づく調査のため、ファイルまたはディレクトリから一時ストアを自動作成します
--context-extensions EXT	拡張子でコンテキストのアップロードを絞り込みます（例：py,md または .py .md）
--keep-context	調査完了後も一時コンテキストストアを保持します（デフォルト：自動削除）
--dry-run	調査を開始せずにコストを見積もります（JSON 形式のコスト見積もりを出力）
--format {md,html,pdf}	レポートの出力形式（デフォルト：md。pdf には weasyprint が必要です）
--prompt-template {typescript,python,general,auto}	ドメイン固有のプロンプト接頭辞。auto はコンテキストファイルの拡張子から自動判定します
--depth {quick,standard,deep}	調査の深さ：quick（約 2～5 分）、standard（約 5～15 分）、deep（約 15～45 分）
--max-cost USD	推定コストがこの上限を超えた場合に中止します（例：--max-cost 3.00）
--input-file PATH	位置引数の代わりに、ファイルから調査クエリを読み込みます
--no-cache	調査キャッシュを使わず、新たに実行します

start サブコマンドはデフォルトなので、research.py "question" と research.py start "question" は同じです。

重要：--output または --output-dir を使うと、調査が完了するまでコマンドはブロックされます（2～10 分以上）。& を使ってバックグラウンドで実行しないでください。ブロックしないモード（--output を省略）で ID をすぐに取得し、その後 status でポーリングして report で保存してください。

ステータスを確認する

uv run {baseDir}/scripts/research.py status <interaction-id>

現在のステータス（in_progress、completed、failed）と、利用可能な場合は出力を返します。

レポートを保存する

uv run {baseDir}/scripts/research.py report <interaction-id>

フラグ	説明
--output FILE	レポートを指定したファイルパスに保存します（デフォルト：report-<id>.md）
--output-dir DIR	構造化された結果をディレクトリに保存します

構造化出力（--output-dir）

--output-dir を使うと、結果は構造化されたディレクトリに保存されます。

<output-dir>/
  research-<id>/
    report.md          # Full final report
    metadata.json      # Timing, status, output count, sizes
    interaction.json   # Full interaction data (all outputs, thinking steps)
    sources.json       # Extracted source URLs/citations

500 文字未満の簡潔な JSON サマリーが標準出力に表示されます。

{
  "id": "interaction-123",
  "status": "completed",
  "output_dir": "research-output/research-interaction-1/",
  "report_file": "research-output/research-interaction-1/report.md",
  "report_size_bytes": 45000,
  "duration_seconds": 154,
  "summary": "First 200 chars of the report..."
}

これは AI エージェントとの統合に推奨されるパターンです。エージェントは小さな JSON ペイロードを受け取り、完全なレポートはディスクに書き込まれます。

適応型ポーリング

--output または --output-dir を使うと、調査が完了するまでスクリプトは Gemini API をポーリングします。デフォルトでは、過去の調査完了時間から学習する履歴適応型ポーリングを使います。

• 完了時間は .gemini-research.json の researchHistory に記録されます（直近 50 件。根拠ありの調査と根拠なしの調査では別々のカーブを使用）。
• 一致するデータポイントが 3 件以上ある場合、ポーリング間隔は過去の分布に合わせて調整されます。
  • 調査が一度も完了していない場合：低頻度のポーリング（30s）
  • 完了する可能性が高い時間帯（p25～p75）：高頻度のポーリング（5s）
  • 終盤（p75 を過ぎた後）：中程度の頻度でポーリング（15～30s）
  • 通常より大幅に長い実行（これまでの最長時間の 1.5 倍を超える場合）：低頻度のポーリング（60s）
• 安全策として、すべての間隔は [2s, 120s] の範囲内に制限されます。

履歴が不十分な場合（データポイントが 3 件未満）、または --no-adaptive-poll が渡された場合は、間隔を段階的に延ばす固定カーブを使います：5s（最初の 30s）、10s（30s～2min）、30s（2～10min）、60s（10min 以降）。

コスト見積もり（--dry-run）

調査を実行する前に、推定コストをプレビューします。

uv run {baseDir}/scripts/research.py start "Analyze security architecture" --context ./src --dry-run

コンテキストのアップロードコスト、調査クエリのコスト、合計を含むコスト見積もりを JSON 形式で stdout に出力します。見積もりはヒューリスティックに基づいており（Gemini API はトークン数や請求データを返しません）、その旨が明確に示されます。

--output-dir を指定して調査が完了すると、metadata.json ファイルに usage キーが追加され、実際の出力サイズと所要時間に基づいた実行後のコスト見積もりが含まれます。

File Search Store コマンド

RAG に基づく調査や Q&A 用のファイル検索ストアを管理します。

ストアを作成する

uv run {baseDir}/scripts/store.py create "My Project Docs"

ストアの一覧を表示する

uv run {baseDir}/scripts/store.py list

ストアにクエリを実行する

uv run {baseDir}/scripts/store.py query <store-name> "What does the auth module do?"

フラグ	説明
--output-dir DIR	応答とメタデータをディレクトリに保存します

ストアを削除する

uv run {baseDir}/scripts/store.py delete <store-name>

--force を指定すると、確認プロンプトをスキップします。stdin が TTY ではない場合（例：AI エージェントから呼び出された場合）、プロンプトは自動的にスキップされます。

ファイルのアップロード

ファイルまたはディレクトリ全体をファイル検索ストアにアップロードします。

uv run {baseDir}/scripts/upload.py ./src fileSearchStores/abc123

フラグ	説明
--smart-sync	変更されていないファイルをスキップします（ハッシュ比較）
--extensions EXT [EXT ...]	含めるファイル拡張子（カンマまたはスペース区切り。例：py,ts,md または .py .ts .md）

ハッシュキャッシュはアップロードが成功するたびに保存されるため、最初のアップロードで --smart-sync を使用していなくても、次回の --smart-sync 実行時には変更されていないファイルが正しくスキップされます。

MIME タイプのサポート

36 種類のファイル拡張子が Gemini File Search API でネイティブにサポートされています。一般的なプログラミングファイル（JS、TS、JSON、CSS、YAML など）は、フォールバック機構によって text/plain として自動的にアップロードされます。バイナリファイルは拒否されます。完全な一覧については、references/file_search_guide.md を参照してください。

ファイルサイズ制限：1 ファイルあたり 100 MB です。

セッション管理

調査 ID とストアの対応関係は、現在の作業ディレクトリにある .gemini-research.json にキャッシュされます。

セッションの状態を表示する

uv run {baseDir}/scripts/state.py show

調査セッションのみを表示する

uv run {baseDir}/scripts/state.py research

ストアのみを表示する

uv run {baseDir}/scripts/state.py stores

エージェント向け JSON 出力

任意の状態サブコマンドに --json を追加すると、構造化された JSON が stdout に出力されます。

uv run {baseDir}/scripts/state.py --json show
uv run {baseDir}/scripts/state.py --json research
uv run {baseDir}/scripts/state.py --json stores

セッションの状態をクリアする

uv run {baseDir}/scripts/state.py clear

-y を指定すると、確認プロンプトをスキップします。stdin が TTY ではない場合（例：AI エージェントから呼び出された場合）、プロンプトは自動的にスキップされます。

非対話モード

stdin が TTY ではない場合、すべての確認プロンプト（store.py delete、state.py clear）は自動的にスキップされます。これにより、AI エージェントや CI パイプラインが対話プロンプトで停止することなく、これらのコマンドを呼び出せます。

ワークフローの例

一般的な根拠に基づく調査ワークフロー：

# 1. Create a file search store
STORE_JSON=$(uv run {baseDir}/scripts/store.py create "Project Codebase")
STORE_NAME=$(echo "$STORE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])")

# 2. Upload your documents
uv run {baseDir}/scripts/upload.py ./docs "$STORE_NAME" --smart-sync

# 3. Query the store directly
uv run {baseDir}/scripts/store.py query "$STORE_NAME" "How is authentication handled?"

# 4. Start grounded deep research (blocking, saves to directory)
uv run {baseDir}/scripts/research.py start "Analyze the security architecture" \
  --store "$STORE_NAME" --output-dir ./research-output --timeout 3600

# 5. Or start non-blocking and check later
RESEARCH_JSON=$(uv run {baseDir}/scripts/research.py start "Analyze the security architecture" --store "$STORE_NAME")
RESEARCH_ID=$(echo "$RESEARCH_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 6. Check progress
uv run {baseDir}/scripts/research.py status "$RESEARCH_ID"

# 7. Save the report when completed
uv run {baseDir}/scripts/research.py report "$RESEARCH_ID" --output-dir ./research-output

出力規約

すべてのスクリプトは、二重出力のパターンに従います：

• stderr：リッチ形式の、人が読みやすい出力（テーブル、パネル、プログレスバー）
• stdout：プログラムで処理できる JSON

つまり、2>/dev/null を指定すると人間向けの出力が非表示になり、stdout をパイプするとクリーンな JSON が得られます。