tavily-search

Tavily Search

Web search using Tavily API - optimized for AI agents and RAG applications.

Quick Start

Prerequisites

Set your Tavily API key:

export TAVILY_API_KEY="tvly-your-api-key"

Or use the Python client directly with API key.

Basic Search

from tavily import TavilyClient
client = TavilyClient(api_key="tvly-your-api-key")
response = client.search("Latest AI developments")
for result in response['results']:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Content: {result['content'][:200]}...")

Q&A Search (Get Direct Answers)

answer = client.qna_search(query="Who won the 2024 US Presidential Election?")
print(answer)

Context Search (For RAG Applications)

context = client.get_search_context(
    query="Climate change effects on agriculture",
    max_tokens=4000
)
Use context directly in LLM prompts

Search Parameters

Common Parameters

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | query | string | Search query (required) | - | | search_depth | string | "basic" or "comprehensive" | "basic" | | max_results | int | Number of results (1-20) | 5 | | include_answer | bool | Include AI-generated answer | False | | include_raw_content | bool | Include full page content | False | | include_images | bool | Include image URLs | False |

Advanced Parameters

| Parameter | Type | Description | |-----------|------|-------------| | topic | string | Search topic: "general" or "news" | | time_range | string | Time filter: "day", "week", "month", "year" | | include_domains | list | Restrict to specific domains | | exclude_domains | list | Exclude specific domains | | exact_match | bool | Require exact phrase matching |

Response Format

Standard Search Response

{
  "query": "search query",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com/article",
      "content": "Snippet or full content...",
      "score": 0.95,
      "raw_content": "Full page content (if requested)..."
    }
  ],
  "answer": "AI-generated answer (if requested)",
  "images": ["image_url1", "image_url2"],
  "response_time": 1.23
}

Error Handling

Common Errors

from tavily import TavilyClient
from tavily.exceptions import TavilyError, RateLimitError, InvalidAPIKeyError
client = TavilyClient(api_key="your-api-key")
try:
    response = client.search("query")
except InvalidAPIKeyError:
    print("Invalid API key. Check your TAVILY_API_KEY.")
except RateLimitError:
    print("Rate limit exceeded. Please wait before retrying.")
except TavilyError as e:
    print(f"Tavily error: {e}")

Best Practices

1. Use Context Search for RAG

For retrieval-augmented generation, use get_search_context() instead of standard search:

context = client.get_search_context(
    query=user_query,
    max_tokens=4000,  # Fit within your LLM's context window
    search_depth="comprehensive"
)
Use in prompt
prompt = f"""Based on the following context:
{context}
Answer this question: {user_query}"""

2. Handle Rate Limits

Tavily has rate limits. Implement exponential backoff:

import time
from tavily.exceptions import RateLimitError
def search_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search(query)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

3. Filter Results

Use domain filters to improve result quality:

# Only search trusted news sources
response = client.search(
    query="breaking news",
    include_domains=["bbc.com", "reuters.com", "apnews.com"],
    time_range="day"  # Only recent news
)

4. Use Q&A Mode for Facts

For factual questions, use Q&A mode for direct answers:

# Good for: "Who won the 2024 election?"
answer = client.qna_search("Who won the 2024 US Presidential Election?")
Good for: "What is the capital of France?"
answer = client.qna_search("Capital of France")

Additional Resources

Skill Maintenance

This skill requires:

For issues or updates, refer to the Tavily documentation or GitHub repository.

Prerequisites

Set your Tavily API key:

export TAVILY_API_KEY="tvly-your-api-key"

Or use the Python client directly with API key.

Basic Search

from tavily import TavilyClient
client = TavilyClient(api_key="tvly-your-api-key")
response = client.search("Latest AI developments")
for result in response['results']:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Content: {result['content'][:200]}...")

Q&A Search (Get Direct Answers)

answer = client.qna_search(query="Who won the 2024 US Presidential Election?")
print(answer)

Context Search (For RAG Applications)

context = client.get_search_context(
    query="Climate change effects on agriculture",
    max_tokens=4000
)
Use context directly in LLM prompts

Set your Tavily API key:

export TAVILY_API_KEY="tvly-your-api-key"

Or use the Python client directly with API key.

Basic Search

from tavily import TavilyClient
client = TavilyClient(api_key="tvly-your-api-key")
response = client.search("Latest AI developments")
for result in response['results']:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Content: {result['content'][:200]}...")

Q&A Search (Get Direct Answers)

answer = client.qna_search(query="Who won the 2024 US Presidential Election?")
print(answer)

Context Search (For RAG Applications)

context = client.get_search_context(
    query="Climate change effects on agriculture",
    max_tokens=4000
)
Use context directly in LLM prompts

1. Use Context Search for RAG

For retrieval-augmented generation, use get_search_context() instead of standard search:

context = client.get_search_context(
    query=user_query,
    max_tokens=4000,  # Fit within your LLM's context window
    search_depth="comprehensive"
)
Use in prompt
prompt = f"""Based on the following context:
{context}
Answer this question: {user_query}"""

2. Handle Rate Limits

Tavily has rate limits. Implement exponential backoff:

import time
from tavily.exceptions import RateLimitError
def search_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search(query)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

3. Filter Results

Use domain filters to improve result quality:

# Only search trusted news sources
response = client.search(
    query="breaking news",
    include_domains=["bbc.com", "reuters.com", "apnews.com"],
    time_range="day"  # Only recent news
)

4. Use Q&A Mode for Facts

For factual questions, use Q&A mode for direct answers:

# Good for: "Who won the 2024 election?"
answer = client.qna_search("Who won the 2024 US Presidential Election?")
Good for: "What is the capital of France?"
answer = client.qna_search("Capital of France")