tavily-dynamic-search

Tavily ダイナミック検索

大きなウェブの生データはディスクに保存し、タスクに必要なエビデンスだけを返します。これは、--include-raw-content を使用する場合、複数のクエリを組み合わせる場合、または複数の長いページから情報を抽出する場合に便利です。通常の tvly search --json で直接回答できる簡単な検索には、このワークフローを使用しないでください。

実行する前に

検索と抽出は、上限付きの認証不要アクセスに対応しています。tvly が利用可能な場合は、そのまま実行してください。tvly が見つからない場合は、tavily-cli のセットアップに従ってください。最初のリクエストを送る前に、API キーを探したり認証したりしないでください。対話セッション中に認証不要アクセスの上限に達した場合は、tvly login を実行してブラウザーで OAuth を開き、ブロックされたリクエストを一度だけ再試行してください。無人環境では、対話的なフローを開始するのではなく、上限に達したことと認証方法を報告してください。

ワークフロー

1. 生コンテンツを含めずに幅広く検索し、タイトル、URL、スコア、スニペットを確認します。
2. 最適なソースのみ、全コンテンツを取得します。
3. 生データの出力が大きくなる可能性がある場合は、-o で保存し、モデルのコンテキストに表示する前にファイルをフィルタリングします。
4. 抽出したすべての事実に、ソースの URL を併記します。

ユーザーが公式ドメインまたは指定ドメインのエビデンスに限定した場合は、ローカルでのフィルタリング中に、選択したすべての URL のホスト名を検証してください。--include-domains は検索範囲を絞り込みますが、返されたすべての結果が許可されたホストに属することを証明するものではありません。ページ全体を抽出できない場合は、ページ本文を確認したかのように示すのではなく、結論に検索スニペットに基づくエビデンスであることを明記してください。

関連するソースとフィルターがすでに分かっている場合は、1 回のターン内で処理を完了してください。最初の検索によって抽出対象が変わる場合に限り、別のターンを使用してください。

エビデンスを保存する前に、一意な一時タスクディレクトリを作成し、複数のエージェントが互いのファイルを上書きしないようにしてください。mktemp が使用できない場合は、Python の tempfile.mkdtemp() を利用できます。タスクの生データとフィルタリング済みの成果物は、すべてそのディレクトリに保存してください。

小さな結果：直接の JSON レスポンスをフィルタリングする

検索結果が小さい場合は、パイプで十分です。

tvly search "query" --max-results 5 --json | python3 -c '
import json, sys
data = json.load(sys.stdin)
for result in data.get("results", []):
    score = result.get("score") or 0
    title = result.get("title") or ""
    print(f"[{score:.2f}] {title}")
    print(result.get("url", ""))
    print(result.get("content", "")[:300])
'

標準エラー出力を破棄しないでください。認証エラー、認証不要アクセスの上限メッセージ、API エラーは対処が必要なため、表示したままにしてください。

大きな結果：先に保存してからフィルタリングする

CLI のファイル出力を使い、ページの生コンテンツがツールのレスポンスを経由しないようにします。

tvly search "query" \
  --include-raw-content markdown \
  --max-results 8 \
  --json \
  -o /tmp/tavily-search-results.json

次に、範囲を絞ったエビデンスだけを出力します。

python3 -c '
import json
from pathlib import Path

data = json.loads(Path("/tmp/tavily-search-results.json").read_text())
for result in data.get("results", []):
    title = result.get("title") or ""
    url = result.get("url") or ""
    print(f"## {title}")
    print(f"URL: {url}")
    print((result.get("raw_content") or result.get("content") or "")[:1200])
    print()
'

質問に応じてフィルタリングのロジックを調整してください。対象となる情報が分かっている場合は、固定長の文字列を切り出すよりも、関連する段落やフィールドを優先してください。表やコードブロックで本当に必要な場合を除き、ソースごとにおよそ 150～600 トークンを目安にしてください。

対象を絞った抽出

検索で適切な URL が見つかった場合は、それらのページだけを抽出します。

tvly extract "https://example.com/article" \
  --json \
  -o /tmp/tavily-extract-results.json

特定のトピックに焦点を当てたページでは、ローカルでフィルタリングする前に Tavily を使ってレスポンスを絞り込みます。

tvly extract "https://example.com/docs" \
  --query "authentication API" \
  --chunks-per-source 3 \
  --json \
  -o /tmp/tavily-extract-results.json

複数のクエリ

複数の観点から調査する場合は、焦点を絞った検索を少数実行し、URL で重複を排除してから、抽出の優先順位を付けてください。Python でコマンドをオーケストレーションする場合は、subprocess.run(..., capture_output=True, text=True) を使用してください。returncode を確認し、コマンドが失敗した場合は、標準エラー出力を提示して処理を停止するか、意図を持って再試行してください。エビデンスの欠落を隠してしまう except Exception: continue のような一律の処理は絶対に使用しないでください。

レスポンスの形式

tvly search --json は、query、省略可能な answer、results、response_time を返します。各結果には通常、url、title、content、score、省略可能な raw_content が含まれます。

tvly extract --json は、results、failed_results、response_time を返します。成功した各結果には通常、url、raw_content、省略可能な画像が含まれます。

フィールドは省略可能なものとして扱い、フィルタリングでは .get() を使用してください。リクエストしたすべての URL の抽出に成功したと決めつけず、failed_results を確認してください。

便利なオプション

オプション	目的
--max-results	検索結果数を制限します。デフォルトは5、最大は20です
--depth	ultra-fast、fast、basic、advancedから選択します
--time-range	結果をday、week、month、yearに制限します
--include-domains	信頼できるドメインをカンマ区切りのリストで指定し、結果を制限します
--exclude-domains	カンマ区切りのリストで指定したドメインを除外します
--include-raw-content	全文をmarkdownまたはtextとして含めます
-o, --output	応答全体をファイルに保存します

Pythonを利用できない場合に限り、短いフィルターにはjqを使用します：

tvly search "query" --json | jq '[.results[] | {title, url, score, content}]'