Tavily

目的

Tavily の REST API への curl ベースのインターフェースを提供し、ウェブ検索、抽出、マッピング、クローリング、オプションのリサーチを実行します。LLM ワークフロー及び複数ステップの調査に適した構造化された結果を返します。

使用場面

• タスクがライブのウェブ情報、サイト抽出、マッピング、またはクローリングを必要とする場合。
• ウェブ検索が必要で組み込みツールが利用できない場合、または Tavily の LLM 対応出力（サマリー、チャンク、ソース、引用）が有益な場合。
• タスクが Tavily からの構造化された検索結果、抽出、またはサイト検出を必要とする場合。

必須環境

• 環境に TAVILY_API_KEY が必要です。
• TAVILY_API_KEY が見つからない場合は、処理を進める前にユーザーに API キーの提供を促します。

ベース URL と認証

• ベース URL: https://api.tavily.com
• 認証: Authorization: Bearer $TAVILY_API_KEY
• Content type: Content-Type: application/json
• オプションのプロジェクトトラッキング: プロジェクト属性が必要な場合は X-Project-ID: <project-id> を追加します。

ツールマッピング (Tavily REST)

1) search → POST /search

オプションの回答とコンテンツ抽出を伴うウェブ検索に使用します。

推奨される最小限のリクエスト:

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

主要なパラメータ (特に記載がない限りすべてオプション):

• query (必須): 検索テキスト
• search_depth: basic | advanced | fast | ultra-fast
• chunks_per_source: 1～3 (advanced のみ)
• max_results: 0～20
• topic: general | news | finance
• time_range: day|week|month|year|d|w|m|y
• start_date, end_date: YYYY-MM-DD
• include_answer: false | true | basic | advanced
• include_raw_content: false | true | markdown | text
• include_images: ブール値
• include_image_descriptions: ブール値
• include_favicon: ブール値
• include_domains, exclude_domains: 文字列配列
• country: 国名 (general トピックのみ)
• auto_parameters: ブール値
• include_usage: ブール値

期待される応答フィールド:

• answer (リクエストされた場合)、results[] に title、url、content、score、raw_content (オプション)、favicon (オプション)
• response_time、usage、request_id

2) extract → POST /extract

特定の URL からコンテンツを抽出する場合に使用します。

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "urls": ["https://example.com/article"],
    "query": "<optional intent for reranking>",
    "chunks_per_source": 3,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false,
    "include_favicon": false
  }'

主要なパラメータ:

• urls (必須): URL の配列
• query: インテント別にチャンクを再ランク付け
• chunks_per_source: 1～5 (query が提供されている場合のみ)
• extract_depth: basic | advanced
• format: markdown | text
• timeout: 1～60 秒
• include_usage: ブール値

期待される応答フィールド:

• results[] に url、raw_content、images、favicon
• failed_results[]、response_time、usage、request_id

3) map → POST /map

サイトマップ生成 (URL 検出のみ) に使用します。

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "allow_external": true
  }'

主要なパラメータ:

• url (必須)
• instructions: 自然言語ガイダンス (コストが増加します)
• max_depth: 1～5
• max_breadth: 1+
• limit: 1+
• select_paths、select_domains、exclude_paths、exclude_domains: 正規表現文字列の配列
• allow_external: ブール値
• timeout: 10～150 秒
• include_usage: ブール値

期待される応答フィールド:

• base_url、results[] (URL のリスト)、response_time、usage、request_id

4) crawl → POST /crawl

組み込み抽出機能付きのサイト走査に使用します。

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false
  }'

主要なパラメータ:

• url (必須)
• instructions: オプション; コストが増加し、chunks_per_source を有効にします
• chunks_per_source: 1～5 (instructions 付きのみ)
• max_depth、max_breadth、limit: map と同じ
• extract_depth: basic | advanced
• format: markdown | text
• include_images、include_favicon、allow_external
• timeout: 10～150 秒
• include_usage: ブール値

期待される応答フィールド:

• base_url、results[] に url、raw_content、favicon
• response_time、usage、request_id

オプションのリサーチワークフロー (深い調査)

クエリが複数ステップの分析と引用を必要とする場合に使用します。

リサーチタスクの作成 → POST /research

curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

期待される応答フィールド:

• request_id、created_at、status (pending)、input、model、response_time

リサーチステータスの取得 → GET /research/{request_id}

curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

期待される応答フィールド:

• status: completed
• content: レポートテキストまたは構造化オブジェクト
• sources[]: { title, url, favicon }

ストリーミングリサーチ (SSE)

POST ボディで "stream": true を設定し、curl で -N を使用してイベントをストリーミングします:

curl -N -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{"input":"<question>","stream":true,"model":"pro"}'

SSE イベント (tool calls、tool responses、content chunks、sources、done) を処理します。

使用に関する注意

• search、extract、map、crawl を検出とコンテンツ取得の主要なエンドポイントとして扱います。
• ダウンストリームで簡単に使用できるよう、URL、タイトル、サマリー付きの構造化された結果を返します。
• より深いリコールが必要な場合を除き、デフォルトで保守的なパラメータ (search_depth: basic、max_results: 5) を使用します。
• 呼び出し全体で一貫した リクエストボディを再利用して、結果を予測可能に保ちます。

エラーハンドリング

• リクエストが 401/403 を返す場合は、TAVILY_API_KEY をプロンプトで入力するか、再確認します。
• タイムアウトが発生した場合は、max_depth/limit を削減するか、search_depth: basic を使用します。
• レスポンスが大きすぎる場合は、max_results または chunks_per_source を低下させます。