TavilyWebSearch

Search the web using Tavily, an AI-powered search API optimized for LLM applications.

Key Features

• AI-powered web search optimized for use in LLM pipelines.
• Returns search results as Haystack Document objects with content and metadata.
• Also returns raw links alongside documents for downstream use.
• Configurable number of results with top_k.
• Supports additional Tavily search parameters like search_depth, include_domains, and exclude_domains.

Configuration

1. Drag the TavilyWebSearch component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Create a secret with your Tavily API key and set it as api_key. Use TAVILY_API_KEY as the environment variable name. For instructions, see Create Secrets. Get your API key from tavily.com.
   2. Set top_k to control the maximum number of search results to return.
4. Go to the Advanced tab to configure search_params for Tavily-specific options such as search_depth, include_domains, and exclude_domains.

Connections

TavilyWebSearch receives a query string and outputs a list of Document objects containing search result content and a list of raw URLs. Connect its documents output to a PromptBuilder or ranker to use the results in a pipeline.

Source Code

To check this component's source code, open tavily_websearch.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  TavilyWebSearch:
    type: haystack_integrations.components.websearch.tavily.tavily_websearch.TavilyWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TAVILY_API_KEY
        strict: false
      top_k: 10

Using the Component in a Pipeline

# haystack-pipeline
components:
  TavilyWebSearch:
    type: haystack_integrations.components.websearch.tavily.tavily_websearch.TavilyWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - TAVILY_API_KEY
        strict: false
      top_k: 5
      search_params:
        search_depth: advanced

  prompt_builder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      required_variables: "*"
      template:
      - role: user
        content: |
          Answer based on these web search results:
          {% for doc in documents %}
          {{ doc.content }}
          {% endfor %}
          Question: {{ question }}

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - OPENAI_API_KEY
        strict: false
      model: gpt-4o-mini

connections:
- sender: TavilyWebSearch.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: llm.messages

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - TavilyWebSearch.query
  - prompt_builder.question

Parameters

Inputs

Parameter	Type	Description
query	str	The search query to send to Tavily.
search_params	Optional[Dict[str, Any]]	Additional Tavily search parameters to override init-time values.

Outputs

Parameter	Type	Description
documents	List[Document]	The search results as Haystack Documents.
links	List[str]	The URLs of the search results.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
api_key	Secret	Secret.from_env_var("TAVILY_API_KEY")	The Tavily API key.
top_k	Optional[int]	10	The maximum number of search results to return.
search_params	Optional[Dict[str, Any]]	None	Additional Tavily API parameters, such as search_depth ("basic" or "advanced"), include_domains, exclude_domains, include_answer, and include_raw_content.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		The search query to send to Tavily.
search_params	Optional[Dict[str, Any]]	None	Additional Tavily search parameters to override init-time values.

Related Information

• Pipeline Components