Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Add Tavily Research and get Research (#5483)
Mani07364cf46ff9
diff --git a/docs/ar/tools/search-research/tavilyextractortool.mdx b/docs/ar/tools/search-research/tavilyextractortool.mdxindex e251f7e9a..3b5eb1aed 100644--- a/docs/ar/tools/search-research/tavilyextractortool.mdx+++ b/docs/ar/tools/search-research/tavilyextractortool.mdx@@ -12,7 +12,7 @@ mode: "wide"لاستخدام `TavilyExtractorTool`، تحتاج إلى تثبيت مكتبة `tavily-python`:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```تحتاج أيضاً إلى تعيين مفتاح Tavily API كمتغير بيئة:diff --git a/docs/ar/tools/search-research/tavilyresearchtool.mdx b/docs/ar/tools/search-research/tavilyresearchtool.mdxnew file mode 100644index 000000000..34fdc8c66--- /dev/null+++ b/docs/ar/tools/search-research/tavilyresearchtool.mdx@@ -0,0 +1,125 @@+---+title: "Tavily Research Tool"+description: "Run multi-step research tasks and get cited reports using the Tavily Research API"+icon: "flask"+mode: "wide"+---++The `TavilyResearchTool` lets CrewAI agents kick off Tavily research tasks, returning a synthesized, cited report (or a stream of progress events) instead of raw search results. Use it when an agent needs an investigative answer rather than a single web search.++## Installation++To use the `TavilyResearchTool`, install the `tavily-python` library alongside `crewai-tools`:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Set your Tavily API key:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++Get an API key at [https://app.tavily.com/](https://app.tavily.com/) (sign up, then create a key).++## Example Usage++```python+import os+from crewai import Agent, Crew, Task+from crewai_tools import TavilyResearchTool++# Ensure TAVILY_API_KEY is set in your environment+# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"++tavily_tool = TavilyResearchTool()++researcher = Agent(+ role="Research Analyst",+ goal="Investigate questions and produce concise, well-cited briefings.",+ backstory=(+ "You are a meticulous analyst who delegates web research to the Tavily "+ "Research tool, then synthesizes the findings into short briefings."+ ),+ tools=[tavily_tool],+ verbose=True,+)++research_task = Task(+ description=(+ "Investigate notable open-source agent orchestration frameworks released "+ "in the last six months and summarize their differentiators."+ ),+ expected_output="A bulleted briefing with citations.",+ agent=researcher,+)++crew = Crew(agents=[researcher], tasks=[research_task])+print(crew.kickoff())+```++## Configuration Options++The `TavilyResearchTool` accepts the following arguments — all can be set on the tool instance (defaults for every call) or per-call via the agent's tool input:++- `input` (str): **Required.** The research task or question to investigate.+- `model` (Literal["mini", "pro", "auto"]): The Tavily research model. `"auto"` lets Tavily pick; `"mini"` is faster/cheaper; `"pro"` is the most capable. Defaults to `"auto"`.+- `output_schema` (dict | None): Optional JSON Schema that structures the research output. Useful when you want strictly typed results.+- `stream` (bool): When `True`, the tool returns an iterator of SSE chunks emitting research progress and the final result instead of a single string. Defaults to `False`.+- `citation_format` (Literal["numbered", "mla", "apa", "chicago"]): Citation format for the report. Defaults to `"numbered"`.++## Advanced Usage++### Configure defaults on the tool instance++```python+from crewai_tools import TavilyResearchTool++tavily_tool = TavilyResearchTool(+ model="pro", # use Tavily's most capable research model+ citation_format="apa", # APA-style citations+)+```++### Stream research progress++When `stream=True`, the tool returns a generator (or async generator from `_arun`) of SSE chunks so your application can surface incremental progress:++```python+tavily_tool = TavilyResearchTool(stream=True)++for chunk in tavily_tool.run(input="Summarize recent advances in retrieval-augmented generation."):+ print(chunk)+```++### Structured output via JSON Schema++Pass an `output_schema` when you need a typed result instead of a free-form report:++```python+output_schema = {+ "type": "object",+ "properties": {+ "summary": {"type": "string"},+ "key_points": {"type": "array", "items": {"type": "string"}},+ "sources": {"type": "array", "items": {"type": "string"}},+ },+ "required": ["summary", "key_points", "sources"],+}++tavily_tool = TavilyResearchTool(output_schema=output_schema)+```++## Features++- **End-to-end research**: Returns a synthesized, cited report rather than raw search hits.+- **Model selection**: Trade off cost, speed, and depth via `mini`, `pro`, or `auto`.+- **Streaming**: Stream incremental progress and results as SSE chunks for responsive UIs.+- **Structured output**: Coerce results to a JSON Schema you define.+- **Multiple citation styles**: Choose from numbered, MLA, APA, or Chicago citations.+- **Sync and async**: Use either `_run` or `_arun` depending on your application's runtime.++Refer to the [Tavily API documentation](https://docs.tavily.com/) for full details on the Research API.diff --git a/docs/ar/tools/search-research/tavilysearchtool.mdx b/docs/ar/tools/search-research/tavilysearchtool.mdxindex e7ef712e4..bc2c52e72 100644--- a/docs/ar/tools/search-research/tavilysearchtool.mdx+++ b/docs/ar/tools/search-research/tavilysearchtool.mdx@@ -12,7 +12,7 @@ mode: "wide"لاستخدام `TavilySearchTool`، تحتاج إلى تثبيت مكتبة `tavily-python`:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```## متغيرات البيئةdiff --git a/docs/docs.json b/docs/docs.jsonindex 76d43b4e3..743cef205 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -247,6 +247,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -1199,6 +1200,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -1675,6 +1677,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -2151,6 +2154,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -2627,6 +2631,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -3102,6 +3107,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -3576,6 +3582,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -4050,6 +4057,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -4524,6 +4532,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -5000,6 +5009,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -5475,6 +5485,7 @@"en/tools/search-research/youtubevideosearchtool","en/tools/search-research/tavilysearchtool","en/tools/search-research/tavilyextractortool",+ "en/tools/search-research/tavilyresearchtool","en/tools/search-research/arxivpapertool","en/tools/search-research/serpapi-googlesearchtool","en/tools/search-research/serpapi-googleshoppingtool",@@ -11512,6 +11523,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -12454,6 +12466,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -12925,6 +12938,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -13396,6 +13410,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -13867,6 +13882,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -14337,6 +14353,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -14807,6 +14824,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -15277,6 +15295,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -15746,6 +15765,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -16215,6 +16235,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -16685,6 +16706,7 @@"ko/tools/search-research/youtubevideosearchtool","ko/tools/search-research/tavilysearchtool","ko/tools/search-research/tavilyextractortool",+ "ko/tools/search-research/tavilyresearchtool","ko/tools/search-research/arxivpapertool","ko/tools/search-research/serpapi-googlesearchtool","ko/tools/search-research/serpapi-googleshoppingtool",@@ -17186,6 +17208,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -18128,6 +18151,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -18599,6 +18623,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -19070,6 +19095,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -19541,6 +19567,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -20011,6 +20038,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -20481,6 +20509,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -20951,6 +20980,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -21420,6 +21450,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -21889,6 +21920,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",@@ -22359,6 +22391,7 @@"ar/tools/search-research/youtubevideosearchtool","ar/tools/search-research/tavilysearchtool","ar/tools/search-research/tavilyextractortool",+ "ar/tools/search-research/tavilyresearchtool","ar/tools/search-research/arxivpapertool","ar/tools/search-research/serpapi-googlesearchtool","ar/tools/search-research/serpapi-googleshoppingtool",diff --git a/docs/en/tools/search-research/tavilyextractortool.mdx b/docs/en/tools/search-research/tavilyextractortool.mdxindex 4b1d4b091..1530d54a9 100644--- a/docs/en/tools/search-research/tavilyextractortool.mdx+++ b/docs/en/tools/search-research/tavilyextractortool.mdx@@ -12,7 +12,7 @@ The `TavilyExtractorTool` allows CrewAI agents to extract structured content froTo use the `TavilyExtractorTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```You also need to set your Tavily API key as an environment variable:diff --git a/docs/en/tools/search-research/tavilyresearchtool.mdx b/docs/en/tools/search-research/tavilyresearchtool.mdxnew file mode 100644index 000000000..34fdc8c66--- /dev/null+++ b/docs/en/tools/search-research/tavilyresearchtool.mdx@@ -0,0 +1,125 @@+---+title: "Tavily Research Tool"+description: "Run multi-step research tasks and get cited reports using the Tavily Research API"+icon: "flask"+mode: "wide"+---++The `TavilyResearchTool` lets CrewAI agents kick off Tavily research tasks, returning a synthesized, cited report (or a stream of progress events) instead of raw search results. Use it when an agent needs an investigative answer rather than a single web search.++## Installation++To use the `TavilyResearchTool`, install the `tavily-python` library alongside `crewai-tools`:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Set your Tavily API key:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++Get an API key at [https://app.tavily.com/](https://app.tavily.com/) (sign up, then create a key).++## Example Usage++```python+import os+from crewai import Agent, Crew, Task+from crewai_tools import TavilyResearchTool++# Ensure TAVILY_API_KEY is set in your environment+# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"++tavily_tool = TavilyResearchTool()++researcher = Agent(+ role="Research Analyst",+ goal="Investigate questions and produce concise, well-cited briefings.",+ backstory=(+ "You are a meticulous analyst who delegates web research to the Tavily "+ "Research tool, then synthesizes the findings into short briefings."+ ),+ tools=[tavily_tool],+ verbose=True,+)++research_task = Task(+ description=(+ "Investigate notable open-source agent orchestration frameworks released "+ "in the last six months and summarize their differentiators."+ ),+ expected_output="A bulleted briefing with citations.",+ agent=researcher,+)++crew = Crew(agents=[researcher], tasks=[research_task])+print(crew.kickoff())+```++## Configuration Options++The `TavilyResearchTool` accepts the following arguments — all can be set on the tool instance (defaults for every call) or per-call via the agent's tool input:++- `input` (str): **Required.** The research task or question to investigate.+- `model` (Literal["mini", "pro", "auto"]): The Tavily research model. `"auto"` lets Tavily pick; `"mini"` is faster/cheaper; `"pro"` is the most capable. Defaults to `"auto"`.+- `output_schema` (dict | None): Optional JSON Schema that structures the research output. Useful when you want strictly typed results.+- `stream` (bool): When `True`, the tool returns an iterator of SSE chunks emitting research progress and the final result instead of a single string. Defaults to `False`.+- `citation_format` (Literal["numbered", "mla", "apa", "chicago"]): Citation format for the report. Defaults to `"numbered"`.++## Advanced Usage++### Configure defaults on the tool instance++```python+from crewai_tools import TavilyResearchTool++tavily_tool = TavilyResearchTool(+ model="pro", # use Tavily's most capable research model+ citation_format="apa", # APA-style citations+)+```++### Stream research progress++When `stream=True`, the tool returns a generator (or async generator from `_arun`) of SSE chunks so your application can surface incremental progress:++```python+tavily_tool = TavilyResearchTool(stream=True)++for chunk in tavily_tool.run(input="Summarize recent advances in retrieval-augmented generation."):+ print(chunk)+```++### Structured output via JSON Schema++Pass an `output_schema` when you need a typed result instead of a free-form report:++```python+output_schema = {+ "type": "object",+ "properties": {+ "summary": {"type": "string"},+ "key_points": {"type": "array", "items": {"type": "string"}},+ "sources": {"type": "array", "items": {"type": "string"}},+ },+ "required": ["summary", "key_points", "sources"],+}++tavily_tool = TavilyResearchTool(output_schema=output_schema)+```++## Features++- **End-to-end research**: Returns a synthesized, cited report rather than raw search hits.+- **Model selection**: Trade off cost, speed, and depth via `mini`, `pro`, or `auto`.+- **Streaming**: Stream incremental progress and results as SSE chunks for responsive UIs.+- **Structured output**: Coerce results to a JSON Schema you define.+- **Multiple citation styles**: Choose from numbered, MLA, APA, or Chicago citations.+- **Sync and async**: Use either `_run` or `_arun` depending on your application's runtime.++Refer to the [Tavily API documentation](https://docs.tavily.com/) for full details on the Research API.diff --git a/docs/en/tools/search-research/tavilysearchtool.mdx b/docs/en/tools/search-research/tavilysearchtool.mdxindex 0d3af2ba3..58c88a1ec 100644--- a/docs/en/tools/search-research/tavilysearchtool.mdx+++ b/docs/en/tools/search-research/tavilysearchtool.mdx@@ -12,7 +12,7 @@ The `TavilySearchTool` provides an interface to the Tavily Search API, enablingTo use the `TavilySearchTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```## Environment Variablesdiff --git a/docs/ko/tools/search-research/tavilyextractortool.mdx b/docs/ko/tools/search-research/tavilyextractortool.mdxindex 17a6d3df2..21211e9fd 100644--- a/docs/ko/tools/search-research/tavilyextractortool.mdx+++ b/docs/ko/tools/search-research/tavilyextractortool.mdx@@ -12,7 +12,7 @@ mode: "wide"`TavilyExtractorTool`을 사용하려면 `tavily-python` 라이브러리를 설치해야 합니다:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```또한 Tavily API 키를 환경 변수로 설정해야 합니다:diff --git a/docs/ko/tools/search-research/tavilyresearchtool.mdx b/docs/ko/tools/search-research/tavilyresearchtool.mdxnew file mode 100644index 000000000..34fdc8c66--- /dev/null+++ b/docs/ko/tools/search-research/tavilyresearchtool.mdx@@ -0,0 +1,125 @@+---+title: "Tavily Research Tool"+description: "Run multi-step research tasks and get cited reports using the Tavily Research API"+icon: "flask"+mode: "wide"+---++The `TavilyResearchTool` lets CrewAI agents kick off Tavily research tasks, returning a synthesized, cited report (or a stream of progress events) instead of raw search results. Use it when an agent needs an investigative answer rather than a single web search.++## Installation++To use the `TavilyResearchTool`, install the `tavily-python` library alongside `crewai-tools`:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Set your Tavily API key:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++Get an API key at [https://app.tavily.com/](https://app.tavily.com/) (sign up, then create a key).++## Example Usage++```python+import os+from crewai import Agent, Crew, Task+from crewai_tools import TavilyResearchTool++# Ensure TAVILY_API_KEY is set in your environment+# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"++tavily_tool = TavilyResearchTool()++researcher = Agent(+ role="Research Analyst",+ goal="Investigate questions and produce concise, well-cited briefings.",+ backstory=(+ "You are a meticulous analyst who delegates web research to the Tavily "+ "Research tool, then synthesizes the findings into short briefings."+ ),+ tools=[tavily_tool],+ verbose=True,+)++research_task = Task(+ description=(+ "Investigate notable open-source agent orchestration frameworks released "+ "in the last six months and summarize their differentiators."+ ),+ expected_output="A bulleted briefing with citations.",+ agent=researcher,+)++crew = Crew(agents=[researcher], tasks=[research_task])+print(crew.kickoff())+```++## Configuration Options++The `TavilyResearchTool` accepts the following arguments — all can be set on the tool instance (defaults for every call) or per-call via the agent's tool input:++- `input` (str): **Required.** The research task or question to investigate.+- `model` (Literal["mini", "pro", "auto"]): The Tavily research model. `"auto"` lets Tavily pick; `"mini"` is faster/cheaper; `"pro"` is the most capable. Defaults to `"auto"`.+- `output_schema` (dict | None): Optional JSON Schema that structures the research output. Useful when you want strictly typed results.+- `stream` (bool): When `True`, the tool returns an iterator of SSE chunks emitting research progress and the final result instead of a single string. Defaults to `False`.+- `citation_format` (Literal["numbered", "mla", "apa", "chicago"]): Citation format for the report. Defaults to `"numbered"`.++## Advanced Usage++### Configure defaults on the tool instance++```python+from crewai_tools import TavilyResearchTool++tavily_tool = TavilyResearchTool(+ model="pro", # use Tavily's most capable research model+ citation_format="apa", # APA-style citations+)+```++### Stream research progress++When `stream=True`, the tool returns a generator (or async generator from `_arun`) of SSE chunks so your application can surface incremental progress:++```python+tavily_tool = TavilyResearchTool(stream=True)++for chunk in tavily_tool.run(input="Summarize recent advances in retrieval-augmented generation."):+ print(chunk)+```++### Structured output via JSON Schema++Pass an `output_schema` when you need a typed result instead of a free-form report:++```python+output_schema = {+ "type": "object",+ "properties": {+ "summary": {"type": "string"},+ "key_points": {"type": "array", "items": {"type": "string"}},+ "sources": {"type": "array", "items": {"type": "string"}},+ },+ "required": ["summary", "key_points", "sources"],+}++tavily_tool = TavilyResearchTool(output_schema=output_schema)+```++## Features++- **End-to-end research**: Returns a synthesized, cited report rather than raw search hits.+- **Model selection**: Trade off cost, speed, and depth via `mini`, `pro`, or `auto`.+- **Streaming**: Stream incremental progress and results as SSE chunks for responsive UIs.+- **Structured output**: Coerce results to a JSON Schema you define.+- **Multiple citation styles**: Choose from numbered, MLA, APA, or Chicago citations.+- **Sync and async**: Use either `_run` or `_arun` depending on your application's runtime.++Refer to the [Tavily API documentation](https://docs.tavily.com/) for full details on the Research API.diff --git a/docs/ko/tools/search-research/tavilysearchtool.mdx b/docs/ko/tools/search-research/tavilysearchtool.mdxindex 183fc0549..264652708 100644--- a/docs/ko/tools/search-research/tavilysearchtool.mdx+++ b/docs/ko/tools/search-research/tavilysearchtool.mdx@@ -12,7 +12,7 @@ mode: "wide"`TavilySearchTool`을 사용하려면 `tavily-python` 라이브러리를 설치해야 합니다:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```## 환경 변수diff --git a/docs/pt-BR/tools/search-research/tavilyextractortool.mdx b/docs/pt-BR/tools/search-research/tavilyextractortool.mdxindex ed384de44..55030845c 100644--- a/docs/pt-BR/tools/search-research/tavilyextractortool.mdx+++ b/docs/pt-BR/tools/search-research/tavilyextractortool.mdx@@ -12,7 +12,7 @@ The `TavilyExtractorTool` allows CrewAI agents to extract structured content froTo use the `TavilyExtractorTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```You also need to set your Tavily API key as an environment variable:diff --git a/docs/pt-BR/tools/search-research/tavilyresearchtool.mdx b/docs/pt-BR/tools/search-research/tavilyresearchtool.mdxnew file mode 100644index 000000000..34fdc8c66--- /dev/null+++ b/docs/pt-BR/tools/search-research/tavilyresearchtool.mdx@@ -0,0 +1,125 @@+---+title: "Tavily Research Tool"+description: "Run multi-step research tasks and get cited reports using the Tavily Research API"+icon: "flask"+mode: "wide"+---++The `TavilyResearchTool` lets CrewAI agents kick off Tavily research tasks, returning a synthesized, cited report (or a stream of progress events) instead of raw search results. Use it when an agent needs an investigative answer rather than a single web search.++## Installation++To use the `TavilyResearchTool`, install the `tavily-python` library alongside `crewai-tools`:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Set your Tavily API key:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++Get an API key at [https://app.tavily.com/](https://app.tavily.com/) (sign up, then create a key).++## Example Usage++```python+import os+from crewai import Agent, Crew, Task+from crewai_tools import TavilyResearchTool++# Ensure TAVILY_API_KEY is set in your environment+# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"++tavily_tool = TavilyResearchTool()++researcher = Agent(+ role="Research Analyst",+ goal="Investigate questions and produce concise, well-cited briefings.",+ backstory=(+ "You are a meticulous analyst who delegates web research to the Tavily "+ "Research tool, then synthesizes the findings into short briefings."+ ),+ tools=[tavily_tool],+ verbose=True,+)++research_task = Task(+ description=(+ "Investigate notable open-source agent orchestration frameworks released "+ "in the last six months and summarize their differentiators."+ ),+ expected_output="A bulleted briefing with citations.",+ agent=researcher,+)++crew = Crew(agents=[researcher], tasks=[research_task])+print(crew.kickoff())+```++## Configuration Options++The `TavilyResearchTool` accepts the following arguments — all can be set on the tool instance (defaults for every call) or per-call via the agent's tool input:++- `input` (str): **Required.** The research task or question to investigate.+- `model` (Literal["mini", "pro", "auto"]): The Tavily research model. `"auto"` lets Tavily pick; `"mini"` is faster/cheaper; `"pro"` is the most capable. Defaults to `"auto"`.+- `output_schema` (dict | None): Optional JSON Schema that structures the research output. Useful when you want strictly typed results.+- `stream` (bool): When `True`, the tool returns an iterator of SSE chunks emitting research progress and the final result instead of a single string. Defaults to `False`.+- `citation_format` (Literal["numbered", "mla", "apa", "chicago"]): Citation format for the report. Defaults to `"numbered"`.++## Advanced Usage++### Configure defaults on the tool instance++```python+from crewai_tools import TavilyResearchTool++tavily_tool = TavilyResearchTool(+ model="pro", # use Tavily's most capable research model+ citation_format="apa", # APA-style citations+)+```++### Stream research progress++When `stream=True`, the tool returns a generator (or async generator from `_arun`) of SSE chunks so your application can surface incremental progress:++```python+tavily_tool = TavilyResearchTool(stream=True)++for chunk in tavily_tool.run(input="Summarize recent advances in retrieval-augmented generation."):+ print(chunk)+```++### Structured output via JSON Schema++Pass an `output_schema` when you need a typed result instead of a free-form report:++```python+output_schema = {+ "type": "object",+ "properties": {+ "summary": {"type": "string"},+ "key_points": {"type": "array", "items": {"type": "string"}},+ "sources": {"type": "array", "items": {"type": "string"}},+ },+ "required": ["summary", "key_points", "sources"],+}++tavily_tool = TavilyResearchTool(output_schema=output_schema)+```++## Features++- **End-to-end research**: Returns a synthesized, cited report rather than raw search hits.+- **Model selection**: Trade off cost, speed, and depth via `mini`, `pro`, or `auto`.+- **Streaming**: Stream incremental progress and results as SSE chunks for responsive UIs.+- **Structured output**: Coerce results to a JSON Schema you define.+- **Multiple citation styles**: Choose from numbered, MLA, APA, or Chicago citations.+- **Sync and async**: Use either `_run` or `_arun` depending on your application's runtime.++Refer to the [Tavily API documentation](https://docs.tavily.com/) for full details on the Research API.diff --git a/docs/pt-BR/tools/search-research/tavilysearchtool.mdx b/docs/pt-BR/tools/search-research/tavilysearchtool.mdxindex 3252e82ac..1207562cc 100644--- a/docs/pt-BR/tools/search-research/tavilysearchtool.mdx+++ b/docs/pt-BR/tools/search-research/tavilysearchtool.mdx@@ -12,7 +12,7 @@ The `TavilySearchTool` provides an interface to the Tavily Search API, enablingTo use the `TavilySearchTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```## Environment Variablesdiff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.tomlindex d900f859b..ec1bb518b 100644--- a/lib/crewai-tools/pyproject.toml+++ b/lib/crewai-tools/pyproject.toml@@ -69,7 +69,7 @@ linkup-sdk = ["linkup-sdk>=0.2.2",]tavily-python = [- "tavily-python>=0.5.4",+ "tavily-python~=0.7.14",]hyperbrowser = ["hyperbrowser>=0.18.0",diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.pyindex 2af540edc..3d5c23abd 100644--- a/lib/crewai-tools/src/crewai_tools/__init__.py+++ b/lib/crewai-tools/src/crewai_tools/__init__.py@@ -197,6 +197,12 @@ from crewai_tools.tools.stagehand_tool.stagehand_tool import StagehandToolfrom crewai_tools.tools.tavily_extractor_tool.tavily_extractor_tool import (TavilyExtractorTool,)+from crewai_tools.tools.tavily_get_research_tool.tavily_get_research_tool import (+ TavilyGetResearchTool,+)+from crewai_tools.tools.tavily_research_tool.tavily_research_tool import (+ TavilyResearchTool,+)from crewai_tools.tools.tavily_search_tool.tavily_search_tool import TavilySearchToolfrom crewai_tools.tools.txt_search_tool.txt_search_tool import TXTSearchToolfrom crewai_tools.tools.vision_tool.vision_tool import VisionTool@@ -310,6 +316,8 @@ __all__ = ["StagehandTool","TXTSearchTool","TavilyExtractorTool",+ "TavilyGetResearchTool",+ "TavilyResearchTool","TavilySearchTool","VisionTool","WeaviateVectorSearchTool",diff --git a/lib/crewai-tools/src/crewai_tools/tools/__init__.py b/lib/crewai-tools/src/crewai_tools/tools/__init__.pyindex 7cf61c7a3..11309c87e 100644--- a/lib/crewai-tools/src/crewai_tools/tools/__init__.py+++ b/lib/crewai-tools/src/crewai_tools/tools/__init__.py@@ -184,6 +184,12 @@ from crewai_tools.tools.stagehand_tool.stagehand_tool import StagehandToolfrom crewai_tools.tools.tavily_extractor_tool.tavily_extractor_tool import (TavilyExtractorTool,)+from crewai_tools.tools.tavily_get_research_tool.tavily_get_research_tool import (+ TavilyGetResearchTool,+)+from crewai_tools.tools.tavily_research_tool.tavily_research_tool import (+ TavilyResearchTool,+)from crewai_tools.tools.tavily_search_tool.tavily_search_tool import TavilySearchToolfrom crewai_tools.tools.txt_search_tool.txt_search_tool import TXTSearchToolfrom crewai_tools.tools.vision_tool.vision_tool import VisionTool@@ -293,6 +299,8 @@ __all__ = ["StagehandTool","TXTSearchTool","TavilyExtractorTool",+ "TavilyGetResearchTool",+ "TavilyResearchTool","TavilySearchTool","VisionTool","WeaviateVectorSearchTool",diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md b/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.mdindex 8e2794dd1..64e85c92d 100644--- a/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_extractor_tool/README.md@@ -9,7 +9,7 @@ The `TavilyExtractorTool` allows CrewAI agents to extract structured content froTo use the `TavilyExtractorTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```You also need to set your Tavily API key as an environment variable:diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/README.md b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/README.mdnew file mode 100644index 000000000..303121e0c--- /dev/null+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/README.md@@ -0,0 +1,44 @@+# Tavily Get Research Tool++## Description++The `TavilyGetResearchTool` provides an interface to Tavily's research status endpoint through the Tavily Python SDK. It retrieves the current status and results of an existing Tavily research task by `request_id`.++## Installation++To use the `TavilyGetResearchTool`, you need to install the `tavily-python` library:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Ensure your Tavily API key is set as an environment variable:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++## Example++```python+from crewai_tools import TavilyGetResearchTool++tavily_get_research_tool = TavilyGetResearchTool()++status_result = tavily_get_research_tool.run(+ request_id="Your Request ID Here"+)+print(status_result)+```++## Arguments++The `TavilyGetResearchTool` accepts the following arguments during initialization or when calling the `run` method:++- `request_id` (str): Existing Tavily research request ID to retrieve.++## Response Format++The tool returns a JSON string containing the current research task status and any available results from Tavily.diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/__init__.py b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/__init__.pynew file mode 100644index 000000000..8b1378917--- /dev/null+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/__init__.py@@ -0,0 +1 @@+diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/tavily_get_research_tool.py b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/tavily_get_research_tool.pynew file mode 100644index 000000000..c3d6787b3--- /dev/null+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/tavily_get_research_tool.py@@ -0,0 +1,120 @@+from __future__ import annotations++import json+import os+from typing import Any++from crewai.tools import BaseTool, EnvVar+from dotenv import load_dotenv+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr+++load_dotenv()+try:+ from tavily import AsyncTavilyClient, TavilyClient # type: ignore[import-untyped]++ TAVILY_AVAILABLE = True+except ImportError:+ TAVILY_AVAILABLE = False+++class TavilyGetResearchToolSchema(BaseModel):+ """Input schema for TavilyGetResearchTool."""++ request_id: str = Field(+ ...,+ description="Existing Tavily research request ID to fetch status and results for.",+ )+++class TavilyGetResearchTool(BaseTool):+ """Tool that uses the Tavily Research status endpoint to retrieve results."""++ model_config = ConfigDict(arbitrary_types_allowed=True)+ _client: Any | None = PrivateAttr(default=None)+ _async_client: Any | None = PrivateAttr(default=None)+ name: str = "Tavily Get Research"+ description: str = (+ "A tool that retrieves the status and results of an existing Tavily "+ "research task by request ID. It returns Tavily responses as JSON."+ )+ args_schema: type[BaseModel] = TavilyGetResearchToolSchema+ package_dependencies: list[str] = Field(default_factory=lambda: ["tavily-python"])+ env_vars: list[EnvVar] = Field(+ default_factory=lambda: [+ EnvVar(+ name="TAVILY_API_KEY",+ description="API key for Tavily research service",+ required=True,+ ),+ ]+ )++ def __init__(self, **kwargs: Any):+ super().__init__(**kwargs)+ if TAVILY_AVAILABLE:+ api_key = os.getenv("TAVILY_API_KEY")+ self._client = TavilyClient(api_key=api_key)+ self._async_client = AsyncTavilyClient(api_key=api_key)+ else:+ try:+ import subprocess++ import click+ except ImportError as e:+ raise ImportError(+ "The 'tavily-python' package is required. 'click' and "+ "'subprocess' are also needed to assist with installation "+ "if the package is missing. Please install 'tavily-python' "+ "manually (e.g., 'pip install tavily-python') and ensure "+ "'click' and 'subprocess' are available."+ ) from e++ if click.confirm(+ "You are missing the 'tavily-python' package, which is required "+ "for TavilyGetResearchTool. Would you like to install it?"+ ):+ try:+ subprocess.run(["uv", "add", "tavily-python"], check=True) # noqa: S607+ raise ImportError(+ "'tavily-python' has been installed. Please restart your "+ "Python application to use the TavilyGetResearchTool."+ )+ except subprocess.CalledProcessError as e:+ raise ImportError(+ f"Attempted to install 'tavily-python' but failed: {e}. "+ "Please install it manually to use the TavilyGetResearchTool."+ ) from e+ else:+ raise ImportError(+ "The 'tavily-python' package is required to use the "+ "TavilyGetResearchTool. Please install it with: uv add tavily-python"+ )++ @staticmethod+ def _stringify_response(response: Any) -> str:+ if isinstance(response, str):+ return response+ return json.dumps(response, indent=2)++ def _run(self, request_id: str) -> str:+ """Synchronously retrieves Tavily research task status and results."""+ if not self._client:+ raise ValueError(+ "Tavily client is not initialized. Ensure 'tavily-python' is "+ "installed and API key is set."+ )++ return self._stringify_response(self._client.get_research(request_id))++ async def _arun(self, request_id: str) -> str:+ """Asynchronously retrieves Tavily research task status and results."""+ if not self._async_client:+ raise ValueError(+ "Tavily async client is not initialized. Ensure 'tavily-python' is "+ "installed and API key is set."+ )++ return self._stringify_response(+ await self._async_client.get_research(request_id)+ )diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/README.md b/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/README.mdnew file mode 100644index 000000000..13e730e62--- /dev/null+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/README.md@@ -0,0 +1,132 @@+# Tavily Research Tool++## Description++The `TavilyResearchTool` provides an interface to Tavily Research through the Tavily Python SDK. It creates research tasks from an `input` prompt and can optionally stream Server-Sent Events (SSE) when `stream=True`.++## Installation++To use the `TavilyResearchTool`, you need to install the `tavily-python` library:++```shell+uv add 'crewai[tools]' tavily-python+```++## Environment Variables++Ensure your Tavily API key is set as an environment variable:++```bash+export TAVILY_API_KEY='your_tavily_api_key'+```++## Example++Here's how to initialize and use the `TavilyResearchTool` within a CrewAI agent:++```python+from crewai import Agent, Task, Crew+from crewai_tools import TavilyResearchTool++# Initialize the tool+tavily_research_tool = TavilyResearchTool()++# Create an agent that uses the tool+researcher = Agent(+ role="Research Analyst",+ goal="Produce structured research reports",+ backstory="An expert analyst who uses Tavily Research for deep web research.",+ tools=[tavily_research_tool],+ verbose=True,+)++# Create a task for the agent+research_task = Task(+ description="Research the latest developments in AI infrastructure startups.",+ expected_output="A detailed report with citations and supporting sources.",+ agent=researcher,+)++# Run the crew+crew = Crew(+ agents=[researcher],+ tasks=[research_task],+ verbose=2,+)++result = crew.kickoff()+print(result)++# Direct tool usage: create a structured research task+structured_result = tavily_research_tool.run(+ input="Research the latest developments in AI infrastructure startups.",+ model="pro",+ output_schema={+ "properties": {+ "summary": {+ "type": "string",+ "description": "A concise summary of the research findings",+ },+ "key_trends": {+ "type": "array",+ "description": "The major trends identified in the research",+ "items": {"type": "string"},+ },+ "companies": {+ "type": "array",+ "description": "Notable companies mentioned in the research",+ "items": {+ "type": "object",+ "description": "A company entry",+ "properties": {+ "name": {+ "type": "string",+ "description": "The company name",+ },+ "focus": {+ "type": "string",+ "description": "The company's main area of focus",+ },+ "notable_update": {+ "type": "string",+ "description": "A notable recent update about the company",+ },+ },+ "required": ["name", "focus", "notable_update"],+ },+ },+ },+ "required": ["summary", "key_trends", "companies"],+ },+ citation_format="apa",+)+print(structured_result)++# Direct tool usage: stream research updates+stream = tavily_research_tool.run(+ input="Research the latest developments in AI infrastructure startups.",+ model="mini",+ stream=True,+)+for chunk in stream:+ print(chunk.decode("utf-8", errors="replace"), end="")+```++## Arguments++The `TavilyResearchTool` accepts the following arguments during initialization or when calling the `run` method:++- `input` (str): The research task or question to investigate.+- `model` (Literal["mini", "pro", "auto"], optional): The Tavily research model to use. Defaults to `"auto"`.+- `output_schema` (dict[str, Any], optional): A JSON Schema used to structure the research output. Tavily expects top-level `properties` and optional `required` keys, and each property should include a `description`.+- `stream` (bool, optional): Whether to return Tavily's streaming SSE chunk generator. Defaults to `False`.+- `citation_format` (Literal["numbered", "mla", "apa", "chicago"], optional): Citation format for the report. Defaults to `"numbered"`.++## Response Format++The tool returns:++- A JSON string when creating a non-streaming research task+- A byte generator of SSE chunks when `stream=True`++Refer to the Tavily Research API documentation for the full response structure and streaming event format.diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/__init__.py b/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/tavily_research_tool.py b/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/tavily_research_tool.pynew file mode 100644index 000000000..084fefdf1--- /dev/null+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/tavily_research_tool.py@@ -0,0 +1,200 @@+from __future__ import annotations++from collections.abc import AsyncGenerator, Generator+import json+import os+from typing import Any, Literal, cast++from crewai.tools import BaseTool, EnvVar+from dotenv import load_dotenv+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr+++load_dotenv()+try:+ from tavily import ( # type: ignore[import-untyped, import-not-found, unused-ignore]+ AsyncTavilyClient,+ TavilyClient,+ )++ TAVILY_AVAILABLE = True+except ImportError:+ TAVILY_AVAILABLE = False+++class TavilyResearchToolSchema(BaseModel):+ """Input schema for TavilyResearchTool."""++ input: str = Field(+ ...,+ description="The research task or question to investigate.",+ )+ model: Literal["mini", "pro", "auto"] = Field(+ default="auto",+ description="The model used by the Tavily research agent.",+ )+ output_schema: dict[str, Any] | None = Field(+ default=None,+ description="Optional JSON Schema that structures the research output.",+ )+ stream: bool = Field(+ default=False,+ description="Whether to stream research progress and results as SSE chunks.",+ )+ citation_format: Literal["numbered", "mla", "apa", "chicago"] = Field(+ default="numbered",+ description="Citation format for the research report.",+ )+++class TavilyResearchTool(BaseTool):+ """Tool that uses the Tavily Research API to create research tasks."""++ model_config = ConfigDict(arbitrary_types_allowed=True)+ _client: Any | None = PrivateAttr(default=None)+ _async_client: Any | None = PrivateAttr(default=None)+ name: str = "Tavily Research"+ description: str = (+ "A tool that creates Tavily research tasks and can stream research "+ "progress and results. It returns Tavily responses as JSON or SSE chunks."+ )+ args_schema: type[BaseModel] = TavilyResearchToolSchema+ model: Literal["mini", "pro", "auto"] = Field(+ default="auto",+ description="Default model used for new Tavily research tasks.",+ )+ output_schema: dict[str, Any] | None = Field(+ default=None,+ description="Default JSON Schema used to structure research output.",+ )+ stream: bool = Field(+ default=False,+ description="Whether new Tavily research tasks should stream responses by default.",+ )+ citation_format: Literal["numbered", "mla", "apa", "chicago"] = Field(+ default="numbered",+ description="Default citation format for Tavily research results.",+ )+ package_dependencies: list[str] = Field(default_factory=lambda: ["tavily-python"])+ env_vars: list[EnvVar] = Field(+ default_factory=lambda: [+ EnvVar(+ name="TAVILY_API_KEY",+ description="API key for Tavily research service",+ required=True,+ ),+ ]+ )++ def __init__(self, **kwargs: Any):+ super().__init__(**kwargs)+ if TAVILY_AVAILABLE:+ api_key = os.getenv("TAVILY_API_KEY")+ self._client = TavilyClient(api_key=api_key)+ self._async_client = AsyncTavilyClient(api_key=api_key)+ else:+ try:+ import subprocess++ import click+ except ImportError as e:+ raise ImportError(+ "The 'tavily-python' package is required. 'click' and "+ "'subprocess' are also needed to assist with installation "+ "if the package is missing. Please install 'tavily-python' "+ "manually (e.g., 'pip install tavily-python') and ensure "+ "'click' and 'subprocess' are available."+ ) from e++ if click.confirm(+ "You are missing the 'tavily-python' package, which is required "+ "for TavilyResearchTool. Would you like to install it?"+ ):+ try:+ subprocess.run(["uv", "add", "tavily-python"], check=True) # noqa: S607+ raise ImportError(+ "'tavily-python' has been installed. Please restart your "+ "Python application to use the TavilyResearchTool."+ )+ except subprocess.CalledProcessError as e:+ raise ImportError(+ f"Attempted to install 'tavily-python' but failed: {e}. "+ "Please install it manually to use the TavilyResearchTool."+ ) from e+ else:+ raise ImportError(+ "The 'tavily-python' package is required to use the "+ "TavilyResearchTool. Please install it with: uv add tavily-python"+ )++ @staticmethod+ def _stringify_response(response: Any) -> str:+ if isinstance(response, str):+ return response+ return json.dumps(response, indent=2)++ def _run(+ self,+ input: str,+ model: Literal["mini", "pro", "auto"] | None = None,+ output_schema: dict[str, Any] | None = None,+ stream: bool | None = None,+ citation_format: Literal["numbered", "mla", "apa", "chicago"] | None = None,+ ) -> str | Generator[bytes, None, None]:+ """Synchronously creates Tavily research tasks or streams results."""+ if not self._client:+ raise ValueError(+ "Tavily client is not initialized. Ensure 'tavily-python' is "+ "installed and API key is set."+ )++ use_stream = self.stream if stream is None else stream+ result = self._client.research(+ input=input,+ model=self.model if model is None else model,+ output_schema=self.output_schema+ if output_schema is None+ else output_schema,+ stream=use_stream,+ citation_format=(+ self.citation_format if citation_format is None else citation_format+ ),+ )++ if use_stream:+ return cast(Generator[bytes, None, None], result)++ return self._stringify_response(result)++ async def _arun(+ self,+ input: str,+ model: Literal["mini", "pro", "auto"] | None = None,+ output_schema: dict[str, Any] | None = None,+ stream: bool | None = None,+ citation_format: Literal["numbered", "mla", "apa", "chicago"] | None = None,+ ) -> str | AsyncGenerator[bytes, None]:+ """Asynchronously creates Tavily research tasks or streams results."""+ if not self._async_client:+ raise ValueError(+ "Tavily async client is not initialized. Ensure 'tavily-python' is "+ "installed and API key is set."+ )++ use_stream = self.stream if stream is None else stream+ result = await self._async_client.research(+ input=input,+ model=self.model if model is None else model,+ output_schema=self.output_schema+ if output_schema is None+ else output_schema,+ stream=use_stream,+ citation_format=(+ self.citation_format if citation_format is None else citation_format+ ),+ )++ if use_stream:+ return cast(AsyncGenerator[bytes, None], result)++ return self._stringify_response(result)diff --git a/lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/README.md b/lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/README.mdindex 185b19887..e3d8ca6c3 100644--- a/lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/README.md+++ b/lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/README.md@@ -9,7 +9,7 @@ The `TavilySearchTool` provides an interface to the Tavily Search API, enablingTo use the `TavilySearchTool`, you need to install the `tavily-python` library:```shell-pip install 'crewai[tools]' tavily-python+uv add 'crewai[tools]' tavily-python```## Environment Variablesdiff --git a/lib/crewai-tools/tool.specs.json b/lib/crewai-tools/tool.specs.jsonindex c78dc2c1f..6a0bcc4c6 100644--- a/lib/crewai-tools/tool.specs.json+++ b/lib/crewai-tools/tool.specs.json@@ -25039,6 +25039,243 @@"type": "object"}},+ {+ "description": "A tool that retrieves the status and results of an existing Tavily research task by request ID. It returns Tavily responses as JSON.",+ "env_vars": [+ {+ "default": null,+ "description": "API key for Tavily research service",+ "name": "TAVILY_API_KEY",+ "required": true+ }+ ],+ "humanized_name": "Tavily Get Research",+ "init_params_schema": {+ "$defs": {+ "EnvVar": {+ "properties": {+ "default": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Default"+ },+ "description": {+ "title": "Description",+ "type": "string"+ },+ "name": {+ "title": "Name",+ "type": "string"+ },+ "required": {+ "default": true,+ "title": "Required",+ "type": "boolean"+ }+ },+ "required": [+ "name",+ "description"+ ],+ "title": "EnvVar",+ "type": "object"+ }+ },+ "description": "Tool that uses the Tavily Research status endpoint to retrieve results.",+ "properties": {},+ "required": [],+ "title": "TavilyGetResearchTool",+ "type": "object"+ },+ "name": "TavilyGetResearchTool",+ "package_dependencies": [+ "tavily-python"+ ],+ "run_params_schema": {+ "description": "Input schema for TavilyGetResearchTool.",+ "properties": {+ "request_id": {+ "description": "Existing Tavily research request ID to fetch status and results for.",+ "title": "Request Id",+ "type": "string"+ }+ },+ "required": [+ "request_id"+ ],+ "title": "TavilyGetResearchToolSchema",+ "type": "object"+ }+ },+ {+ "description": "A tool that creates Tavily research tasks and can stream research progress and results. It returns Tavily responses as JSON or SSE chunks.",+ "env_vars": [+ {+ "default": null,+ "description": "API key for Tavily research service",+ "name": "TAVILY_API_KEY",+ "required": true+ }+ ],+ "humanized_name": "Tavily Research",+ "init_params_schema": {+ "$defs": {+ "EnvVar": {+ "properties": {+ "default": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Default"+ },+ "description": {+ "title": "Description",+ "type": "string"+ },+ "name": {+ "title": "Name",+ "type": "string"+ },+ "required": {+ "default": true,+ "title": "Required",+ "type": "boolean"+ }+ },+ "required": [+ "name",+ "description"+ ],+ "title": "EnvVar",+ "type": "object"+ }+ },+ "description": "Tool that uses the Tavily Research API to create research tasks.",+ "properties": {+ "citation_format": {+ "default": "numbered",+ "description": "Default citation format for Tavily research results.",+ "enum": [+ "numbered",+ "mla",+ "apa",+ "chicago"+ ],+ "title": "Citation Format",+ "type": "string"+ },+ "model": {+ "default": "auto",+ "description": "Default model used for new Tavily research tasks.",+ "enum": [+ "mini",+ "pro",+ "auto"+ ],+ "title": "Model",+ "type": "string"+ },+ "output_schema": {+ "anyOf": [+ {+ "additionalProperties": true,+ "type": "object"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Default JSON Schema used to structure research output.",+ "title": "Output Schema"+ },+ "stream": {+ "default": false,+ "description": "Whether new Tavily research tasks should stream responses by default.",+ "title": "Stream",+ "type": "boolean"+ }+ },+ "required": [],+ "title": "TavilyResearchTool",+ "type": "object"+ },+ "name": "TavilyResearchTool",+ "package_dependencies": [+ "tavily-python"+ ],+ "run_params_schema": {+ "description": "Input schema for TavilyResearchTool.",+ "properties": {+ "citation_format": {+ "default": "numbered",+ "description": "Citation format for the research report.",+ "enum": [+ "numbered",+ "mla",+ "apa",+ "chicago"+ ],+ "title": "Citation Format",+ "type": "string"+ },+ "input": {+ "description": "The research task or question to investigate.",+ "title": "Input",+ "type": "string"+ },+ "model": {+ "default": "auto",+ "description": "The model used by the Tavily research agent.",+ "enum": [+ "mini",+ "pro",+ "auto"+ ],+ "title": "Model",+ "type": "string"+ },+ "output_schema": {+ "anyOf": [+ {+ "additionalProperties": true,+ "type": "object"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "description": "Optional JSON Schema that structures the research output.",+ "title": "Output Schema"+ },+ "stream": {+ "default": false,+ "description": "Whether to stream research progress and results as SSE chunks.",+ "title": "Stream",+ "type": "boolean"+ }+ },+ "required": [+ "input"+ ],+ "title": "TavilyResearchToolSchema",+ "type": "object"+ }+ },{"description": "A tool that performs web searches using the Tavily Search API. It returns a JSON object containing the search results.","env_vars": [diff --git a/uv.lock b/uv.lockindex 202cf6e17..c2e8b55b2 100644--- a/uv.lock+++ b/uv.lock@@ -13,7 +13,7 @@ resolution-markers = [][options]-exclude-newer = "2026-04-27T16:00:00Z"+exclude-newer = "2026-04-28T07:00:00Z"[manifest]members = [@@ -1660,7 +1660,7 @@ requires-dist = [{ name = "sqlalchemy", marker = "extra == 'singlestore'", specifier = ">=2.0.40" },{ name = "sqlalchemy", marker = "extra == 'sqlalchemy'", specifier = ">=2.0.35" },{ name = "stagehand", marker = "extra == 'stagehand'", specifier = ">=0.4.1" },- { name = "tavily-python", marker = "extra == 'tavily-python'", specifier = ">=0.5.4" },+ { name = "tavily-python", marker = "extra == 'tavily-python'", specifier = "~=0.7.14" },{ name = "tiktoken", specifier = ">=0.8.0,<0.13" },{ name = "unstructured", extras = ["all-docs", "local-inference"], marker = "extra == 'xml'", specifier = ">=0.17.2" },{ name = "weaviate-client", marker = "extra == 'weaviate-client'", specifier = ">=4.10.2" },