crewAI/lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool

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:

uv add 'crewai[tools]' tavily-python

Environment Variables

Ensure your Tavily API key is set as an environment variable:

export TAVILY_API_KEY='your_tavily_api_key'

Example

Here's how to initialize and use the TavilyResearchTool within a CrewAI agent:

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.