tavily

Tavily AI 検索

概要

Tavily は、LLM や AI アプリケーションに特化して最適化された検索エンジンです。従来の検索 API とは異なり、Tavily は AI での利用に適した検索結果を提供し、回答の生成、クリーンなコンテンツ抽出、ドメインのフィルタリング機能をオプションで利用できます。

主な機能：

• 検索結果から AI が生成する回答の要約
• LLM の処理に最適化された、クリーンで構造化された検索結果
• 高速な検索モード（basic）と包括的な検索モード（advanced）
• ドメインのフィルタリング（特定のソースを含める／除外する）
• 最新の出来事に焦点を当てたニュース検索
• 関連するビジュアルコンテンツを含む画像検索
• 詳細な分析に向けた生コンテンツの抽出

アーキテクチャ

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

クイックスタート

基本検索

# Simple query with AI answer
scripts/tavily_search.py "What is quantum computing?"

# Multiple results
scripts/tavily_search.py "Python best practices" --max-results 10

高度な検索

# Comprehensive research mode
scripts/tavily_search.py "Climate change solutions" --depth advanced

# News-focused search
scripts/tavily_search.py "AI developments 2026" --topic news

ドメインのフィルタリング

# Search only trusted domains
scripts/tavily_search.py "Python tutorials" \
  --include-domains python.org docs.python.org realpython.com

# Exclude low-quality sources
scripts/tavily_search.py "How to code" \
  --exclude-domains w3schools.com geeksforgeeks.org

画像を使用する

# Include relevant images
scripts/tavily_search.py "Eiffel Tower architecture" --images

検索モード

Basic と Advanced の比較

モード	速度	網羅性	用途
basic	1-2s	良好	簡単な事実、単純なクエリ
advanced	5-10s	優秀	調査、複雑なトピック、包括的な分析

判断フロー：

1. 簡単な事実や定義が必要ですか？ → basic を使用します
2. 複雑なトピックを調査していますか？ → advanced を使用します
3. 複数の視点が必要ですか？ → advanced を使用します
4. 時間的制約のあるクエリですか？ → basic を使用します

一般検索とニュース検索

トピック	期間	ソース	用途
general	全期間	幅広いウェブ	長期間有効なコンテンツ、チュートリアル、ドキュメント
news	過去 7 日間	ニュースサイト	時事問題、最近の動向、速報

判断フロー：

1. クエリに「latest」、「recent」、「current」、「today」が含まれていますか？ → news を使用します
2. 歴史的なコンテンツや長期間有効なコンテンツを探していますか？ → general を使用します
3. 最新情報が必要ですか？ → news を使用します

API キーの設定

オプション 1：Clawdbot の設定（推奨）

Clawdbot の設定に追加します。

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Clawdbot の設定システムを使って、スクリプトからアクセスできます。

オプション 2：環境変数

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

~/.clawdbot/.env またはシェルのプロファイルに追加します。

API キーの取得

1. https://tavily.com にアクセスします
2. アカウントを登録します
3. ダッシュボードに移動します
4. API キーを生成します（tvly- で始まります）
5. プランのレート制限とクレジットの割り当てを確認します

よくあるユースケース

1. 調査と事実確認

# Comprehensive research with answer
scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

# Multiple authoritative sources
scripts/tavily_search.py "Best practices for REST API design" \
  --max-results 10 \
  --include-domains github.com microsoft.com google.com

2. 時事問題

# Latest news
scripts/tavily_search.py "AI policy updates" --topic news

# Recent developments in a field
scripts/tavily_search.py "quantum computing breakthroughs" \
  --topic news \
  --depth advanced

3. 特定分野の調査

# Academic sources only
scripts/tavily_search.py "machine learning algorithms" \
  --include-domains arxiv.org scholar.google.com ieee.org

# Technical documentation
scripts/tavily_search.py "React hooks guide" \
  --include-domains react.dev

4. ビジュアル調査

# Gather visual references
scripts/tavily_search.py "modern web design trends" \
  --images \
  --max-results 10

5. コンテンツの抽出

# Get raw HTML content for deeper analysis
scripts/tavily_search.py "Python async/await" \
  --raw-content \
  --max-results 5

レスポンスの処理

AI の回答

AI が生成する回答は、検索結果を統合した簡潔な要約です。

{
  "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..."
}

使用する場合：

• 手早く要約を得たい
• 複数のソースから統合された情報が必要
• 質問への直接的な回答を探している

使用しない場合（--no-answer）：

• ソース URL のみが必要
• 独自に情報を統合したい
• API クレジットを節約したい

構造化された検索結果

各検索結果には以下が含まれます。

• title：ページタイトル
• url：ソース URL
• content：抽出されたテキストの抜粋
• score：関連性スコア（0-1）
• raw_content：HTML 全体（--raw-content が有効な場合）

画像

--images を有効にすると、検索中に見つかった関連画像の URL が返されます。

ベストプラクティス

1. 適切な検索の深さを選ぶ

• ほとんどのクエリでは basic から始めます（高速で低コスト）
• 次の場合に限り advanced に切り替えます。
  • 最初の検索結果では不十分な場合
  • トピックが複雑、または微妙な違いを含む場合
  • 包括的な網羅性が必要な場合

2. ドメインのフィルタリングを戦略的に使う

ドメインを含める場合：

• 学術研究（.edu ドメイン）
• 公式ドキュメント（プロジェクトの公式サイト）
• 信頼できるニュースソース
• 信頼性の高い情報源として知られるサイト

ドメインを除外する場合：

• 品質の低いコンテンツファームとして知られるサイト
• 関係のないコンテンツ形式（ビジュアル以外のクエリでの Pinterest）
• ペイウォールやアクセス制限のあるサイト

3. コストを最適化する

• デフォルトでは basic を使用します
• 実際に使う件数に合わせて max_results を制限します
• 必要でない限り include_raw_content を無効にします
• 繰り返し使うクエリの検索結果をローカルにキャッシュします

4. エラーを適切に処理する

このスクリプトは、わかりやすいエラーメッセージを表示します。

# Missing API key
Error: Tavily API key required
Setup: Set TAVILY_API_KEY environment variable or pass --api-key

# Package not installed
Error: tavily-python package not installed
To install: pip install tavily-python

統合パターン

プログラムからの使用

from tavily_search import search

result = search(
    query="What is machine learning?",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

解析用の JSON 出力

scripts/tavily_search.py "Python tutorials" --json > results.json

他のツールとの連携

# Search and extract content
scripts/tavily_search.py "React documentation" --json | \
  jq -r '.results[].url' | \
  xargs -I {} curl -s {}

他の検索 API との比較

Brave Search との比較：

• ✅ AI による回答生成
• ✅ 生のコンテンツを抽出
• ✅ ドメインのフィルタリング機能が優れている
• ❌ Brave より遅い
• ❌ クレジットが必要

Perplexity との比較：

• ✅ ソースをより細かく制御できる
• ✅ 生のコンテンツを利用可能
• ✅ 専用のニュースモード
• ≈ 回答の品質は同程度
• ≈ 速度は同程度

Google Custom Search との比較：

• ✅ LLM に最適化された検索結果
• ✅ 回答生成
• ✅ シンプルな API
• ❌ インデックスの規模が小さい
• ≈ コスト体系は同程度

トラブルシューティング

スクリプトが実行できない

# Make executable
chmod +x scripts/tavily_search.py

# Check Python version (requires 3.6+)
python3 --version

# Install dependencies
pip install tavily-python

API キーの問題

# Verify API key format (should start with tvly-)
echo $TAVILY_API_KEY

# Test with explicit key
scripts/tavily_search.py "test" --api-key "tvly-..."

レート制限エラー

• https://tavily.com でプランのクレジット割当量を確認します
• クレジットの消費を抑えるため、max_results の値を減らします
• advanced ではなく basic の深度を使用します
• 繰り返しのクエリにはローカルキャッシュを実装します

リソース

api-reference.md を参照してください。内容は次のとおりです。

• API パラメーターの完全なドキュメント
• レスポンス形式の仕様
• エラー処理の詳細
• コストとレート制限に関する情報
• 高度な使用例

依存関係

• Python 3.6+
• tavily-python パッケージ（インストール：pip install tavily-python）
• 有効な Tavily API キー

クレジットと帰属

• Tavily API：https://tavily.com
• Python SDK：https://github.com/tavily-ai/tavily-python
• ドキュメント：https://docs.tavily.com