BraveWebSearch

Search the web using the Brave Search API and return results as Haystack Documents.

Key Features

• Web search powered by the privacy-focused Brave Search engine.
• 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 locale filtering with country and search_lang parameters.
• Configurable timeout and retry logic.

Configuration

1. Drag the BraveWebSearch 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 Brave Search API key and set it as api_key. Use BRAVE_API_KEY as the environment variable name. For instructions, see Create Secrets. Get your API key from brave.com/search/api.
   2. Set top_k to control the maximum number of search results to return.
4. Go to the Advanced tab to configure country, search_lang, timeout, max_retries, and extra_params.

Connections

BraveWebSearch 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 brave_websearch.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  BraveWebSearch:
    type: haystack_integrations.components.websearch.brave.brave_websearch.BraveWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - BRAVE_API_KEY
        strict: false
      top_k: 10
      timeout: 10
      max_retries: 3

Using the Component in a Pipeline

# haystack-pipeline
components:
  BraveWebSearch:
    type: haystack_integrations.components.websearch.brave.brave_websearch.BraveWebSearch
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - BRAVE_API_KEY
        strict: false
      top_k: 5

  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: BraveWebSearch.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: llm.messages

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - BraveWebSearch.query
  - prompt_builder.question

Parameters

Inputs

Parameter	Type	Description
query	str	The search query to send to Brave Search.
top_k	Optional[int]	The maximum number of results to return. Overrides the init-time top_k if provided.

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("BRAVE_API_KEY")	The Brave Search API key.
top_k	Optional[int]	10	The maximum number of search results to return.
country	Optional[str]	None	The country code for localized search results (for example, US, GB).
search_lang	Optional[str]	None	The language code for search results (for example, en, de).
extra_params	Optional[Dict[str, Any]]	None	Additional Brave Search API parameters.
timeout	int	10	Request timeout in seconds.
max_retries	int	3	Maximum number of retries on API errors.

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 Brave Search.
top_k	Optional[int]	None	The maximum number of results to return. Overrides the init-time top_k.

Related Information

• Pipeline Components