Skip to main content

​
What You’ll Build

An interactive chatbot that uses Tavily tools to answer questions with real-time web data. It dynamically chooses between lightweight search (for simple factual questions) and deep research (for complex, multi-source analysis) — then synthesizes answers with numbered citations.

View Source on GitHub

​
Architecture

Key behavior:
  • The agent can call search_and_format multiple times until it has enough information
  • The agent can only call stream_research once per query (comprehensive but expensive)
  • All responses include numbered citations linking to sources

​
Tools Used

ToolWhen UsedDescription
search_and_formatSimple, factual questions (“What is the capital of France?”)Runs parallel web searches and returns formatted results
stream_researchComplex queries requiring analysis, comparisons, or trendsUses Tavily’s deep research endpoint for multi-source synthesis

​
Quick Start

Source File

pip install tavily-agent-toolkit anthropic tavily-python python-dotenv

export TAVILY_API_KEY="your-tavily-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

python chatbot.py

​
How It Works

The chatbot exposes two tools to the LLM. The agent decides which to call based on the query:
  • search_and_format — wraps tavily_agent_toolkit.search_and_format to run parallel web searches across one or more queries. Accepts an optional time_range filter.
  • stream_research — calls Tavily’s research API in streaming mode via tavily_agent_toolkit.handle_research_stream, returning a comprehensive report.
The system prompt instructs the agent to pick the right tool:
For simple questions, use search_and_format.
For complex questions, use stream_research.

You can call search_and_format multiple times.
You can only use stream_research ONCE.
This keeps costs low for quick lookups while enabling deep research when needed.
The chatbot runs a standard agent loop:
  1. Send the user message + tool definitions to the LLM
  2. If the LLM returns a tool call, execute it and feed the result back
  3. Repeat until the LLM returns a final text response
  4. Print the response with citations and continue the conversation
The system prompt enforces citation discipline:
Use numbered in-text citations [1], [2], etc.
At the end, include a "Sources:" section with only
the sources you actually cited.
Format: [number] Title - URL

​
Example Interaction

Chatbot ready! Type 'quit' to exit.

You: What are the latest developments in quantum computing?
[Using stream_research...]
Assistant: Recent developments in quantum computing include several
breakthroughs. Google's Willow chip demonstrated error correction
below the threshold needed for practical quantum computing [1].
Microsoft announced its Majorana 1 chip using topological qubits [2].
IBM continues to expand its quantum roadmap with plans for 100,000+
qubit systems by 2033 [3].

Sources:
[1] Google Quantum AI Blog - https://blog.google/technology/research/...
[2] Microsoft Research - https://www.microsoft.com/en-us/research/...
[3] IBM Research - https://research.ibm.com/blog/...

You: Who is the CEO of Apple?
[Using search_and_format...]
Assistant: Tim Cook is the CEO of Apple [1]. He has held the position
since August 2011, succeeding Steve Jobs.

Sources:
[1] Apple Leadership - https://www.apple.com/leadership/tim-cook/

​
Key Parameters to Tune

ParameterWhereEffect
modelAgent creationControls reasoning quality and cost
max_resultssearch_and_formatNumber of search results per query (default: 5)
modelresearch call"mini" for faster, "default" for more thorough
time_rangesearch_and_formatFilter results by recency ("day", "week", "month", "year")

​
Next Steps

Tools Reference

Full parameter docs for search_and_format and all other tools.

Company Intelligence

Add website crawling and extraction to your agent’s capabilities.