CrewAI - Tavily Docs

Introduction

This guide shows you how to integrate Tavily with CrewAI to create sophisticated AI agents that can search the web and extract content. By combining CrewAI’s multi-agent framework with Tavily’s real-time web search capabilities, you can build AI systems that research, analyze, and process web information autonomously.

Prerequisites

Before you begin, make sure you have:

An OpenAI API key from OpenAI Platform
A Tavily API key from Tavily Dashboard

Installation

Install the required packages:

Note: The stable python versions to use with CrewAI are Python >=3.10 and Python <3.13 .

pip install 'crewai[tools]'
pip install pydantic

Setup

Set up your API keys:

import os

# Set your API keys
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["TAVILY_API_KEY"] = "your-tavily-api-key"

Using Tavily Search with CrewAI

CrewAI provides built-in Tavily tools that make it easy to integrate web search capabilities into your AI agents. The TavilySearchTool allows your agents to search the web for real-time information.

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilySearchTool

# Initialize the Tavily search tool
tavily_tool = TavilySearchTool()

# Create an agent that uses the tool
researcher = Agent(
    role='News Researcher',
    goal='Find trending information about AI agents',
    backstory='An expert News researcher specializing in technology, focused on AI.',
    tools=[tavily_tool],
    verbose=True
)

# Create a task for the agent
research_task = Task(
    description='Search for the top 3 Agentic AI trends in 2025.',
    expected_output='A JSON report summarizing the top 3 AI trends found.',
    agent=researcher
)

# Form the crew and execute the task
crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True
)

result = crew.kickoff()
print(result)

Customizing search tool parameters

Example:

from crewai_tools import TavilySearchTool

# You can configure the tool with specific parameters
tavily_search_tool = TavilySearchTool(
    search_depth="advanced",
    max_results=10,
    include_answer=True
)

You can customize the search tool by passing parameters to configure its behavior.Below are available parameters in crewai integration: Available Parameters:

query (str): Required. The search query string.
search_depth (Literal[“basic”, “advanced”], optional): The depth of the search. Defaults to “basic”.
topic (Literal[“general”, “news”, “finance”], optional): The topic to focus the search on. Defaults to “general”.
time_range (Literal[“day”, “week”, “month”, “year”], optional): The time range for the search. Defaults to None.
max_results (int, optional): The maximum number of search results to return. Defaults to 5.
include_domains (Sequence[str], optional): A list of domains to prioritize in the search. Defaults to None.
exclude_domains (Sequence[str], optional): A list of domains to exclude from the search. Defaults to None.
include_answer (Union[bool, Literal[“basic”, “advanced”]], optional): Whether to include a direct answer synthesized from the search results. Defaults to False.
include_raw_content (bool, optional): Whether to include the raw HTML content of the searched pages. Defaults to False.
include_images (bool, optional): Whether to include image results. Defaults to False.
timeout (int, optional): The request timeout in seconds. Defaults to 60.

Explore More Parameters: For a complete list of available parameters and their descriptions, visit our API documentation to discover all the customization options available for search operations.

Full Code Example - Search

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilySearchTool

# Set up environment variables
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["TAVILY_API_KEY"] = "your-tavily-api-key"

# Initialize the tool
tavily_tool = TavilySearchTool()

# Create an agent that uses the tool
researcher = Agent(
    role='News Researcher',
    goal='Find trending information about AI agents',
    backstory='An expert News researcher specializing in technology, focused on AI.',
    tools=[tavily_tool],
    verbose=True
)

# Create a task for the agent
research_task = Task(
    description='Search for the top 3 Agentic AI trends in 2025.',
    expected_output='A JSON report summarizing the top 3 AI trends found.',
    agent=researcher
)

# Form the crew and kick it off
crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True
)

result = crew.kickoff()
print(result)

Using Tavily Extract with CrewAI

The TavilyExtractorTool allows your CrewAI agents to extract and process content from specific web pages. This is particularly useful for content analysis, data collection, and research tasks.

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilyExtractorTool

# Initialize the Tavily extractor tool
tavily_tool = TavilyExtractorTool()

# Create an agent that uses the tool
extractor_agent = Agent(
    role='Web Page Content Extractor',
    goal='Extract key information from the given web pages',
    backstory='You are an expert at extracting relevant content from websites using the Tavily Extract.',
    tools=[tavily_tool],
    verbose=True
)

# Define a task for the agent
extract_task = Task(
    description='Extract the main content from the URL https://en.wikipedia.org/wiki/Lionel_Messi .',
    expected_output='A JSON string containing the extracted content from the URL.',
    agent=extractor_agent
)

# Create and run the crew
crew = Crew(
    agents=[extractor_agent],
    tasks=[extract_task],
    verbose=False
)

result = crew.kickoff()
print(result)

Customizing extract tool parameters

Example:

from crewai_tools import TavilyExtractorTool

# You can configure the tool with specific parameters
tavily_extract_tool = TavilyExtractorTool(
    extract_depth="advanced",
    include_images=True,
    timeout=45
)

You can customize the extract tool by passing parameters to configure its behavior. Below are available parameters in crewai integration: Available Parameters:

urls (Union[List[str], str]): Required. A single URL string or a list of URL strings to extract data from.
include_images (Optional[bool]): Whether to include images in the extraction results. Defaults to False.
extract_depth (Literal[“basic”, “advanced”]): The depth of extraction. Use “basic” for faster, surface-level extraction or “advanced” for more comprehensive extraction. Defaults to “basic”.
timeout (int): The maximum time in seconds to wait for the extraction request to complete. Defaults to 60.

Explore More Parameters: For a complete list of available parameters and their descriptions, visit our API documentation to discover all the customization options available for extract operations.

Full Code Example - Extract

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilyExtractorTool

# Set up environment variables
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["TAVILY_API_KEY"] = "your-tavily-api-key"

# Initialize the Tavily extractor tool
tavily_tool = TavilyExtractorTool()

# Create an agent that uses the tool
extractor_agent = Agent(
    role='Web Page Content Extractor',
    goal='Extract key information from the given web pages',
    backstory='You are an expert at extracting relevant content from websites using the Tavily Extract.',
    tools=[tavily_tool],
    verbose=True
)

# Define a task for the agent
extract_task = Task(
    description='Extract the main content from the URL https://en.wikipedia.org/wiki/Lionel_Messi .',
    expected_output='A JSON string containing the extracted content from the URL.',
    agent=extractor_agent
)

# Create and execute the crew
crew = Crew(
    agents=[extractor_agent],
    tasks=[extract_task],
    verbose=True
)

# Run the extraction
result = crew.kickoff()
print("Extraction Results:")
print(result)

Using Tavily Research with CrewAI

The TavilyResearchTool lets your 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.

Note: Using the TavilyResearchTool requires the tavily-python library in addition to crewai-tools. Install it alongside CrewAI tools:
uv add 'crewai[tools]' tavily-python

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilyResearchTool

# Initialize the Tavily research tool
tavily_tool = TavilyResearchTool()

# Create an agent that uses the tool
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,
)

# Create a task for the agent
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,
)

# Form the crew and execute the task
crew = Crew(agents=[researcher], tasks=[research_task])
print(crew.kickoff())

Customizing research tool parameters

Example:

from crewai_tools import TavilyResearchTool

# You can configure the tool with specific defaults for every call
tavily_research_tool = TavilyResearchTool(
    model="pro",                # use Tavily's most capable research model
    citation_format="apa",      # APA-style citations
)

You can customize the research tool by passing parameters to configure its behavior. Defaults set on the tool instance apply to every call, and any parameter can also be overridden per-call via the agent’s tool input. Below are available parameters in the crewai integration: Available Parameters:

input (str): Required. The research task or question to investigate.
model (Literal[“mini”, “pro”, “auto”], optional): The Tavily research model. "auto" lets Tavily pick; "mini" is faster and cheaper; "pro" is the most capable. Defaults to "auto".
output_schema (dict, optional): Optional JSON Schema that structures the research output. Useful when you want strictly typed results. Defaults to None.
stream (bool, optional): 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”], optional): Citation format for the report. Defaults to "numbered".

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:

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:

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)

Explore More Parameters: For a complete list of available parameters and their descriptions, visit our API documentation to discover all the customization options available for research operations.

Full Code Example - Research

import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilyResearchTool

# Set up environment variables
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
os.environ["TAVILY_API_KEY"] = "your-tavily-api-key"

# Initialize the Tavily research tool
tavily_tool = TavilyResearchTool()

# Create an agent that uses the tool
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,
)

# Create a task for the agent
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,
)

# Form the crew and execute the task
crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True,
)

result = crew.kickoff()
print("Research Results:")
print(result)

For more information about Tavily’s capabilities, check out our API documentation and best practices.

​Introduction

​Prerequisites

​Installation

​Setup

​Using Tavily Search with CrewAI

​Customizing search tool parameters

​Using Tavily Extract with CrewAI

​Customizing extract tool parameters

​Using Tavily Research with CrewAI

​Customizing research tool parameters

​Stream research progress

​Structured output via JSON Schema

Introduction

Prerequisites

Installation

Setup

Using Tavily Search with CrewAI

Customizing search tool parameters

Using Tavily Extract with CrewAI

Customizing extract tool parameters

Using Tavily Research with CrewAI

Customizing research tool parameters

Stream research progress

Structured output via JSON Schema