Skip to content

Commit 0767418

Browse files
anakin87anakin87
authored
docs: add doc page for TavilyWebSearchTool (#12015)
1 parent 615dfad commit 0767418

6 files changed

Lines changed: 211 additions & 1 deletion

File tree

‎docs-website/docs/tools/ready-made-tools.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,5 @@ These are the ready-made Tools and Toolsets available in Haystack:
2121
| [GitHubRepoViewerTool](ready-made-tools/githubrepoviewertool.mdx) | Navigates and fetches content from GitHub repositories. |
2222
| [Mem0MemoryRetrieverTool](ready-made-tools/mem0memorytools.mdx) | Retrieves long-term memories from Mem0 for Agent workflows. |
2323
| [Mem0MemoryWriterTool](ready-made-tools/mem0memorytools.mdx) | Stores long-term memories in Mem0 for future Agent runs. |
24+
| [MirageShellTool](ready-made-tools/mirageshelltool.mdx) | Gives Agents a bash shell over a Mirage unified virtual filesystem, mounting backends like S3, Google Drive, and Postgres as one file tree. |
25+
| [TavilyWebSearchTool](ready-made-tools/tavilywebsearchtool.mdx) | Searches the web with Tavily and returns results Agents can cite. |

‎docs-website/docs/tools/ready-made-tools/tavilywebsearchtool.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "TavilyWebSearchTool"
3+
id: tavilywebsearchtool
4+
slug: "/tavilywebsearchtool"
5+
description: "A Tool that allows Agents to search the web with Tavily."
6+
---
7+
8+
# TavilyWebSearchTool
9+
10+
A Tool that allows Agents to search the web with Tavily.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Mandatory init variables** | `api_key`: The Tavily API key. Can be set with the `TAVILY_API_KEY` env var. |
17+
| **API reference** | [Tavily](/reference/integrations-tavily) |
18+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/tavily/src/haystack_integrations/tools/tavily/websearch_tool.py |
19+
| **Package name** | `tavily-haystack` |
20+
21+
</div>
22+
23+
## Overview
24+
25+
`TavilyWebSearchTool` wraps the [`TavilyWebSearch`](../../pipeline-components/websearch/tavilywebsearch.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
26+
27+
The tool parameters are derived from the component's `run` method, so the LLM can pass a `query` and, optionally, `search_params` that override the ones set at initialization time.
28+
29+
Results are formatted as a string, with each result showing a title, the exact URL, and a content snippet. This makes it straightforward for the LLM to cite its sources.
30+
31+
### Parameters
32+
33+
All parameters are keyword-only.
34+
35+
- `api_key` is _mandatory_ and holds the Tavily API key. The default setting reads it from the `TAVILY_API_KEY` environment variable.
36+
- `top_k` is _optional_ and sets the maximum number of results to return. If unset, the `TavilyWebSearch` default applies.
37+
- `search_params` is _optional_ and takes additional parameters for the Tavily search API. Supported keys include `search_depth`, `include_answer`, `include_raw_content`, `include_domains`, and `exclude_domains`.
38+
- `name` is _optional_ and defaults to "web_search". Specifies the name of the tool.
39+
- `description` is _optional_ and provides context to the LLM about what the tool does. If not provided, a default description is applied.
40+
41+
## Usage
42+
43+
Install the Tavily integration to use the `TavilyWebSearchTool`:
44+
45+
```shell
46+
pip install tavily-haystack
47+
```
48+
49+
### On its own
50+
51+
Basic usage to search the web:
52+
53+
```python
54+
from haystack_integrations.tools.tavily import TavilyWebSearchTool
55+
56+
tool = TavilyWebSearchTool(top_k=3)
57+
58+
result = tool.invoke(query="What is Haystack by deepset?")
59+
60+
for document in result["documents"]:
61+
print(document.meta["title"], "-", document.meta["url"])
62+
```
63+
64+
```bash
65+
GitHub - deepset-ai/haystack: Open-source AI orchestration framework ... - https://github.com/deepset-ai/haystack
66+
deepset - Wikipedia - https://en.wikipedia.org/wiki/Deepset
67+
Haystack | Haystack - https://haystack.deepset.ai
68+
```
69+
70+
### With an Agent
71+
72+
You can use `TavilyWebSearchTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when it needs information from the web.
73+
74+
```python
75+
from haystack.components.agents import Agent
76+
from haystack.components.generators.chat import OpenAIChatGenerator
77+
from haystack.dataclasses import ChatMessage
78+
from haystack_integrations.tools.tavily import TavilyWebSearchTool
79+
80+
web_search = TavilyWebSearchTool(top_k=5, search_params={"search_depth": "advanced"})
81+
82+
agent = Agent(
83+
chat_generator=OpenAIChatGenerator(model="gpt-5-mini"),
84+
tools=[web_search],
85+
)
86+
87+
result = agent.run(messages=[ChatMessage.from_user("What is Haystack by deepset?")])
88+
89+
print(result["last_message"].text)
90+
```
91+
92+
```bash
93+
Haystack (by deepset) is an open-source Python framework for building production-ready
94+
LLM applications, especially Retrieval-Augmented Generation (RAG), semantic search,
95+
question answering, and agentic workflows.
96+
97+
It provides modular components and pipelines (document stores, retrievers, rankers,
98+
generators, routers, and tool integrations) so you can compose and control how data
99+
flows before a model sees it.
100+
101+
Source repo: https://github.com/deepset-ai/haystack
102+
```

‎docs-website/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -721,6 +721,7 @@ export default {
721721
'tools/ready-made-tools/githubrepoviewertool',
722722
'tools/ready-made-tools/mem0memorytools',
723723
'tools/ready-made-tools/mirageshelltool',
724+
'tools/ready-made-tools/tavilywebsearchtool',
724725
],
725726
},
726727
],

‎docs-website/versioned_docs/version-2.31/tools/ready-made-tools.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,5 @@ These are the ready-made Tools and Toolsets available in Haystack:
2121
| [GitHubRepoViewerTool](ready-made-tools/githubrepoviewertool.mdx) | Navigates and fetches content from GitHub repositories. |
2222
| [Mem0MemoryRetrieverTool](ready-made-tools/mem0memorytools.mdx) | Retrieves long-term memories from Mem0 for Agent workflows. |
2323
| [Mem0MemoryWriterTool](ready-made-tools/mem0memorytools.mdx) | Stores long-term memories in Mem0 for future Agent runs. |
24+
| [MirageShellTool](ready-made-tools/mirageshelltool.mdx) | Gives Agents a bash shell over a Mirage unified virtual filesystem, mounting backends like S3, Google Drive, and Postgres as one file tree. |
25+
| [TavilyWebSearchTool](ready-made-tools/tavilywebsearchtool.mdx) | Searches the web with Tavily and returns results Agents can cite. |

‎docs-website/versioned_docs/version-2.31/tools/ready-made-tools/tavilywebsearchtool.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "TavilyWebSearchTool"
3+
id: tavilywebsearchtool
4+
slug: "/tavilywebsearchtool"
5+
description: "A Tool that allows Agents to search the web with Tavily."
6+
---
7+
8+
# TavilyWebSearchTool
9+
10+
A Tool that allows Agents to search the web with Tavily.
11+
12+
<div className="key-value-table">
13+
14+
| | |
15+
| --- | --- |
16+
| **Mandatory init variables** | `api_key`: The Tavily API key. Can be set with the `TAVILY_API_KEY` env var. |
17+
| **API reference** | [Tavily](/reference/integrations-tavily) |
18+
| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/tavily/src/haystack_integrations/tools/tavily/websearch_tool.py |
19+
| **Package name** | `tavily-haystack` |
20+
21+
</div>
22+
23+
## Overview
24+
25+
`TavilyWebSearchTool` wraps the [`TavilyWebSearch`](../../pipeline-components/websearch/tavilywebsearch.mdx) component, providing a tool interface for use in agent workflows and tool-based pipelines.
26+
27+
The tool parameters are derived from the component's `run` method, so the LLM can pass a `query` and, optionally, `search_params` that override the ones set at initialization time.
28+
29+
Results are formatted as a string, with each result showing a title, the exact URL, and a content snippet. This makes it straightforward for the LLM to cite its sources.
30+
31+
### Parameters
32+
33+
All parameters are keyword-only.
34+
35+
- `api_key` is _mandatory_ and holds the Tavily API key. The default setting reads it from the `TAVILY_API_KEY` environment variable.
36+
- `top_k` is _optional_ and sets the maximum number of results to return. If unset, the `TavilyWebSearch` default applies.
37+
- `search_params` is _optional_ and takes additional parameters for the Tavily search API. Supported keys include `search_depth`, `include_answer`, `include_raw_content`, `include_domains`, and `exclude_domains`.
38+
- `name` is _optional_ and defaults to "web_search". Specifies the name of the tool.
39+
- `description` is _optional_ and provides context to the LLM about what the tool does. If not provided, a default description is applied.
40+
41+
## Usage
42+
43+
Install the Tavily integration to use the `TavilyWebSearchTool`:
44+
45+
```shell
46+
pip install tavily-haystack
47+
```
48+
49+
### On its own
50+
51+
Basic usage to search the web:
52+
53+
```python
54+
from haystack_integrations.tools.tavily import TavilyWebSearchTool
55+
56+
tool = TavilyWebSearchTool(top_k=3)
57+
58+
result = tool.invoke(query="What is Haystack by deepset?")
59+
60+
for document in result["documents"]:
61+
print(document.meta["title"], "-", document.meta["url"])
62+
```
63+
64+
```bash
65+
GitHub - deepset-ai/haystack: Open-source AI orchestration framework ... - https://github.com/deepset-ai/haystack
66+
deepset - Wikipedia - https://en.wikipedia.org/wiki/Deepset
67+
Haystack | Haystack - https://haystack.deepset.ai
68+
```
69+
70+
### With an Agent
71+
72+
You can use `TavilyWebSearchTool` with the [Agent](../../pipeline-components/agents-1/agent.mdx) component. The Agent will automatically invoke the tool when it needs information from the web.
73+
74+
```python
75+
from haystack.components.agents import Agent
76+
from haystack.components.generators.chat import OpenAIChatGenerator
77+
from haystack.dataclasses import ChatMessage
78+
from haystack_integrations.tools.tavily import TavilyWebSearchTool
79+
80+
web_search = TavilyWebSearchTool(top_k=5, search_params={"search_depth": "advanced"})
81+
82+
agent = Agent(
83+
chat_generator=OpenAIChatGenerator(model="gpt-5-mini"),
84+
tools=[web_search],
85+
)
86+
87+
result = agent.run(messages=[ChatMessage.from_user("What is Haystack by deepset?")])
88+
89+
print(result["last_message"].text)
90+
```
91+
92+
```bash
93+
Haystack (by deepset) is an open-source Python framework for building production-ready
94+
LLM applications, especially Retrieval-Augmented Generation (RAG), semantic search,
95+
question answering, and agentic workflows.
96+
97+
It provides modular components and pipelines (document stores, retrievers, rankers,
98+
generators, routers, and tool integrations) so you can compose and control how data
99+
flows before a model sees it.
100+
101+
Source repo: https://github.com/deepset-ai/haystack
102+
```

‎docs-website/versioned_sidebars/version-2.31-sidebars.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -718,7 +718,8 @@
718718
"tools/ready-made-tools/githubprcreatortool",
719719
"tools/ready-made-tools/githubrepoviewertool",
720720
"tools/ready-made-tools/mem0memorytools",
721-
"tools/ready-made-tools/mirageshelltool"
721+
"tools/ready-made-tools/mirageshelltool",
722+
"tools/ready-made-tools/tavilywebsearchtool"
722723
]
723724
}
724725
]

0 commit comments

Comments
 (0)