Tavily Search Parameters: Tuning Search, Extract, and Crawl

Tavily parameters in ChatAgents are configured inside WebAgent.build_graph() in backend/agent.py. Every call to build_graph() instantiates three Tavily tools — TavilySearch, TavilyExtract, and TavilyCrawl — whose parameters are derived from the mode argument ("fast" or "deep"). Two user-configurable overrides, topic and time_range, can be passed at request time to tailor search results without switching modes.

Fast vs. Deep Mode Parameters

The table below summarises how each parameter differs between the two agent modes.

Parameter	Fast Mode	Deep Thinking Mode	Description
`search_depth`	`basic`	`advanced`	Comprehensiveness of the Tavily search pass
`max_results`	`3`	`5`	Number of search result pages returned
`include_images`	`False`	`True`	Whether image URLs are included in results
`crawl_limit`	`5`	`15`	Maximum number of pages crawled per `TavilyCrawl` call
`extract_depth`	`basic`	`advanced`	Depth of content extraction for `TavilyExtract`
`topic`	`general`	`general`	Search topic filter — user-configurable
`time_range`	`None`	`None`	Temporal filter on results — user-configurable

TavilySearch Parameters

TavilySearch is the first tool the agent reaches for. It runs a web search and returns a ranked list of results with snippets, URLs, and favicons.

Fast Mode
Deep Thinking Mode

search = TavilySearch(
    max_results=3,
    tavily_api_key=api_key,
    include_favicon=True,
    search_depth="basic",
    include_answer=False,   # Agent generates its own answer
    topic="general",
    include_images=False,
    # time_range omitted when None
)

search = TavilySearch(
    max_results=5,
    tavily_api_key=api_key,
    include_favicon=True,
    search_depth="advanced",
    include_answer=False,   # Agent generates its own answer
    topic="general",
    include_images=True,
    # time_range omitted when None
)

Parameter Details

search_depth

string

default:"basic"

Controls how thoroughly Tavily crawls and indexes pages before returning results.

"basic" — Fast, lower cost. Suitable for simple factual queries.
"advanced" — Comprehensive multi-pass crawl. More accurate for complex or ambiguous queries but costs more credits.

max_results

number

default:"3"

The number of search result pages Tavily returns per query. More results give the agent more evidence to reason over but increase token consumption and cost.

topic

string

default:"general"

Instructs Tavily to prioritise sources from a particular domain:

"general" — Broad web search, no source type preference.
"news" — Prioritises news publishers and wire services. Best for current events.
"finance" — Prioritises financial data sources, market feeds, and business news.

time_range

string

Filters results to a specific recency window. Omitted entirely when None (no time restriction).

"day" — Last 24 hours
"week" — Last 7 days
"month" — Last 30 days
"year" — Last 12 months

include_images

boolean

default:"false"

When True, Tavily includes image URLs alongside each result. Enabled in Deep mode to support richer, visually-backed responses. Disabled in Fast mode to keep payloads small.

include_answer

boolean

default:"false"

Always False. Tavily can return a pre-generated answer snippet, but ChatAgents disables this so the LLM agent performs its own reasoning over the raw results rather than relying on Tavily’s summarisation.

include_favicon

boolean

default:"true"

Always True. Favicons are extracted from each result and surfaced in the Streamlit frontend alongside source citations.

TavilyExtract Parameters

TavilyExtract fetches and parses the full content of specific URLs. The agent calls it when a search result looks promising and deeper content is needed. Its output is passed through the summary_llm (Haiku) before being returned to the main agent, to keep token consumption manageable.

Fast Mode
Deep Thinking Mode

extract = TavilyExtract(
    extract_depth="basic",
    tavily_api_key=api_key,
    include_favicon=True,
    include_images=False,
)

extract = TavilyExtract(
    extract_depth="advanced",
    tavily_api_key=api_key,
    include_favicon=True,
    include_images=True,
)

extract_depth

string

default:"basic"

Mirrors search_depth in philosophy:

"basic" — Extracts the main text content of the page. Fast and inexpensive.
"advanced" — Performs a deeper extraction, capturing more structured data, tables, and secondary content blocks.

include_favicon

boolean

default:"true"

Always True. Favicons are passed through the summarizer and surfaced as source attribution icons in the UI.

include_images

boolean

default:"false"

Kept in sync with the corresponding TavilySearch setting. False in Fast mode, True in Deep mode.

TavilyCrawl Parameters

TavilyCrawl performs a full site crawl starting from a URL, following internal links up to limit pages. It gives the agent access to deeply nested content — documentation sites, wikis, long-form articles — that a single extract call might miss.

Fast Mode
Deep Thinking Mode

crawl = TavilyCrawl(
    tavily_api_key=api_key,
    include_favicon=True,
    limit=5,
)

crawl = TavilyCrawl(
    tavily_api_key=api_key,
    include_favicon=True,
    limit=15,
)

limit

number

default:"5"

Maximum number of pages to crawl from the starting URL.

5 (Fast) — Sufficient for simple pages; fast and low cost.
15 (Deep) — Covers large documentation sites, multi-page reports, or deep wikis.

include_favicon

boolean

default:"true"

Always True for consistent source attribution in the UI.

Advanced Usage Examples

The topic and time_range arguments to build_graph() let you tune Tavily’s focus without changing the mode. Pass them from the request layer or set them programmatically when you know the query type in advance.

# Breaking news: fast retrieval of the latest headlines
agent_graph = web_agent.build_graph(
    api_key=tavily_api_key,
    llm=llm,
    prompt=system_prompt,
    summary_llm=summary_llm,
    mode="fast",
    topic="news",
    time_range="day",
)

Cost Analysis

Tavily charges credits per API call. The totals below are estimates based on typical agent usage patterns across all three tools in a single query turn.

Mode	Estimated Credits	Search	Extract	Crawl
Fast	~15–25 credits	3 results × basic = ~6–9	basic, per call = ~3–5	5 pages = ~5–10
Deep	~50–80 credits	5 results × advanced = ~20–30	advanced, per call = ~10–15	15 pages = ~15–30

Credit consumption varies with query complexity. An agent that only calls TavilySearch (no extract or crawl) will sit at the lower end of each range. Deep mode with all three tools on a complex research query will approach the upper bound.

For breaking news queries, use topic="news" with time_range="day" — Tavily’s news index is highly optimised for recency and often returns the right result in a single search call, keeping costs at the Fast-mode floor. For market data, topic="finance" with time_range="week" narrows results to financial sources, reducing irrelevant crawl pages and improving accuracy.

Getting Started

Core Concepts

Configuration

Guides

Tavily Search Parameters: Tuning Search, Extract, and Crawl

Fast vs. Deep Mode Parameters

TavilySearch Parameters

Parameter Details

TavilyExtract Parameters

TavilyCrawl Parameters

Advanced Usage Examples

Cost Analysis

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Guides

Documentation Index

​Fast vs. Deep Mode Parameters

​TavilySearch Parameters

​Parameter Details

​TavilyExtract Parameters

​TavilyCrawl Parameters

​Advanced Usage Examples

​Cost Analysis

Build docs developers (and LLMs) love

Fast vs. Deep Mode Parameters

TavilySearch Parameters

Parameter Details

TavilyExtract Parameters

TavilyCrawl Parameters

Advanced Usage Examples

Cost Analysis