Tavily is a big name in the emerging semantic search paradigm. When we use Tavily, we’re not confined to the age-old standards of keyword searching. We get results that make sense contextually. Follow along and build your own AI agent using Tavily.
By the time you’ve completed this tutorial, you’ll be able to do the following.
- Create and manage developer accounts with Tavily and OpenAI
- Connect your software to your developer accounts using an API key
- Configure an AI agent using Model Context Protocol (MCP)
- Create a basic runtime loop.
- Perform research and debug software using natural language
What exactly is Tavily?
Tavily is a semantic search engine that uses contextual understanding to run your queries. Old-fashioned keyword matching has its benefits but it also runs into issues. Sites often utilize things like keyword packing to influence search results. Search engines use ranking algorithms that reflect their own priorities — this can lead to bias in the results.
Take a look at the Google search below using the query “semantic search.” As you can see, Google Cloud’s results on semantic search are the first ones that appear. This isn’t inherently bad but Google documentation showing up at rank one in a Google search doesn’t exactly feel impartial. Our results don’t contain any harmful bias. They show that Google ranks itself number one for this query.
Tools like Tavily are built to address these issues. When we perform the same query using Tavily’s API playground, our first results come from Wikipedia and Zilliz. Tavily arranges our results based on how they best explain semantic search. Our result rankings are unique to our query.
If you continue to scroll, we receive other relevant results — none of them are top-ranking SEO results. Each page is contextually relevant to the query. Our next results come from ArcGIS and Slack — these rarely appear at the top of a Google search.
If you click the “JSON” tab in the playground, you’ll find something really interesting in the results. Each result is given a score based on how well it matches the query. In this case, Wikipedia gets a score of 0.99987566 (a 99.987566% match). Zilliz yields a 99.984527% match. As we continue down the line, the scores continue to decrease.
{
"query": "semantic search",
"follow_up_questions": null,
"answer": "Semantic search improves search accuracy by understanding intent and context, using AI and natural language processing for better results. It provides more relevant information than traditional keyword searches. It learns from data and feedback to enhance search precision.",
"images": [],
"results": [
{
"url": "https://en.wikipedia.org/wiki/Semantic_search",
"title": "Semantic search - Wikipedia",
"content": "Semantic search is an approach to information retrieval that seeks to improve search accuracy by understanding the searcher's intent and the contextual meaning",
"score": 0.99987566,
"raw_content": null,
"favicon": "https://en.wikipedia.org/static/apple-touch/wikipedia.png"
},
{
"url": "https://zilliz.com/glossary/semantic-search",
"title": "What Is Semantic Search? - Zilliz",
"content": "Semantic search is a search engine technology that interprets the meaning of words and phrases to provide more accurate and relevant search results.",
"score": 0.99984527,
"raw_content": null,
"favicon": "https://zilliz.com/favicon.svg"
},
...
],
"response_time": 2.27,
"request_id": "6b6c16e7-0557-4bac-a7cc-d80946a13ab2"
}
Tavily’s results are ranked based on how well they match the search query. Especially when dealing with AI agents, we can get trustworthy results without ads or sponsored content. The agent performs a search and gets usable results without burning through reasoning cycles.
Why MCP?
MCP is an emerging protocol standard for AI tooling. Tools get wrapped in a server and models use JSON-RPC to control them. This keeps generative models in charge of reasoning but away from precision style outputs.
Imagine you ask a model to solve a math problem. We’ll use 1+1 just to make things simple. Models are designed to produce unique output with each response.
A well trained model might respond with the following.
One plus one equals two. How else may I be of assistance?
A poorly trained model might repeat the age-old JavaScript problem.
1+1=11
By separating the calculation from the model, we don’t need to trust the model’s calculation. Think back to the prompt.
What's 1+1?
An intelligent model doesn’t autocomplete this problem. Instead it recognizes that the user wishes to solve a math problem. It calls the calculator and inputs the instructions to add “1+1”. When it receives “2” as a result, it simply gets piped back into the output.
When we use MCP for web access, we’re not reliant on the model’s training data. Instead, the model can fetch web pages in real-time. Since MCP runs using a server, it’s language and framework agnostic. You can plug your MCP tools into Python, Claude, n8n or anything else that supports MCP.
MCP servers unify and standardize AI agents the way that APIs unified and standardized software development.
Getting ready
Before we get started building, we need API keys for both Tavily and OpenAI. Follow the instructions below to get everything ready to go.
Creating an OpenAI developer account
For starters, you need an OpenAI developer account. Head on over to their API page, click “Start building” and follow the instructions to create your account. Once you’re done, you’ll be taken to the dashboard.
Click on the “API keys” tab to create and manage keys. Once you’ve got an API key, store it in a safe place.
Finally, we need to install OpenAI’s Python package. Like almost any other Python package, this is done using pip.
Install the OpenAI package
pip install openai
Creating your Tavily account
Go on over to https://www.tavily.com/ and click the “Sign Up” button. Once you’ve got an account, you’ll be taken to the dashboard. You can manage your API keys straight from the “Overview” tab.
Once again, store your API key in a safe place.
Building the AI agent
Now, it’s time to build our AI agent. First, we’ll create a chat interface to interact with the agent. Next, we’ll build a simple runtime loop.
Creating the agent
First, we import the OpenAI package and set up our credentials. We create a chat_interface() function. This function shoulders most of the load. Pay close attention to the keyword arguments passed into client.responses.create(). model tells OpenAI which model we’d like to use. tools holds a list of external tools for our AI agent to call. In this case, we only pass in one tool: The Tavily MCP server. When building your own agents, you might pass one or two or even ten tools into the agent.
from openai import OpenAI
client = OpenAI(api_key="sk-proj-your-openai-api-key")
API_TOKEN = "tvly-dev-your-tavily-api-key"
def chat_interface(prompt: str):
resp = client.responses.create(
model="gpt-5-mini",
tools=[
{
"type": "mcp",
"server_label": "tavily",
"server_url": f"https://mcp.tavily.com/mcp/?tavilyApiKey={API_TOKEN}",
"require_approval": "never",
},
],
input=prompt,)
return resp.output_text
Also, pay close attention to our MCP configuration. "type": "mcp" tells the model it’s using an MCP server. server_label just gives our tool a name within the agent. In this case, we name it "tavily" but you can name it whatever you want. server_url tells our AI agent where to send its messages to control the tool. You can view Tavily’s full MCP documentation here.
Basic runtime
Now, we’ll create our runtime. We create a variable, RUNNING and set it to True. While we’re running, users can input a prompt. If the user types exit, RUNNING gets set to False and we exit the loop. If the prompt includes make a report, we write the model output to a markdown file.
RUNNING = True
while RUNNING:
prompt = input("Input a prompt: ")
if prompt == "exit":
RUNNING = False
elif "make a report" in prompt:
with open("detailed-report.md", "w") as file:
file.write(chat_interface(prompt))
else:
print(chat_interface(prompt))
Using your AI agent in real-time
In this case, we named our file tavily-agent.py. To run the agent, we can use the following command. If you named your agent something different, remember to swap out the filename.
python tavily-agent.py
Prompting and debugging
From here, we control our agent using prompts from within the chat. We begin with a simple prompt telling the AI agent to perform deep research on the latest AI news. We also remind the agent to include citations.
Input a prompt: Please perform deep research using Tavily and make a report on the latest AI news. Remember to include citations.
If you’re on Linux, the agent should run without issue. If you’re on Windows, the agent should crash. If you look at the image below, our program throws a unicode error. The model is generating output that the Windows terminal simply can’t print.
The snippet below holds our issue. When we write the model output, we pipe it straight from the AI agent to the file. Before agentic AI, we would need to change the encoding on our response. AI agents allow us to fix this bug differently.
elif "make a report" in prompt:
with open("detailed-report.md", "w") as file:
file.write(chat_interface(prompt))
Rather than changing the code, we can simply adjust our prompt. In the prompt below, we tell the agent to use characters that are compatible with all operating systems.
Input a prompt: Please perform deep research using Tavily and make a report on the latest AI news. Remember to include citations. Use only characters that are compatible with all operating systems.
After adjusting our prompt, the code runs successfully. Our AI agent lets us fix bugs using natural language.
The actual report output
If you open the report, you should see a simple markdown file summarizing what the agent found. It’s not pretty but it’s readable.
There’s a reason we wrote this output to a markdown file. VSCode and most other editors give you the option to preview your markdown file by actually rendering it rather than just displaying the text. From your editor, open the preview.
When we look at the rendered content, we get neat, readable bullet points with clean text. To make the report even better, you can prompt the AI agent to include headers in the report.
As we scroll toward the bottom of the report, there’s a list of citations. Each story is cited with its date and the URL of the actual article.
Conclusion
Tavily lets agents perform efficient searches. With MCP, you get a platform agnostic way to build agents that can use external tools. MCP doesn’t care if you’re using Python, a desktop AI assistant or a no-code workflow. MCP works with any framework that supports the protocol.
Using the Tavily MCP, you can now build fully functional, intelligent software using minimal code. Once the code is running, you can debug your agent and make fixes using plain English.