Web search gives an agent a way to look up information instead of relying on an LLM’s training data. This matters when an answer must be precise, current, or checked against a named source. If a user asks for a value on a particular web page, recalling a plausible value is not the same as looking it up. section 2.4.3
A minimal Python tool takes a query, calls Tavily’s search API, and returns its results. Install the Tavily client, put the API key in a .env file as TAVILY_API_KEY, load it with load_dotenv(), and create a TavilyClient. Starting with two results keeps development responses concise and limits API costs. section 3.3.1
Listing 3.12 Basic web search function using Tavily
import os
from tavily import TavilyClient
from dotenv import load_dotenv
load_dotenv()
tavily_client = TavilyClient(os.getenv("TAVILY_API_KEY"))
def search_web(query: str, max_results: int = 2) -> list:
response = tavily_client.search(query, max_results=max_results)
return response.get("results")
The basic search_web function exposes the essential data flow: query in, Tavily search call, results out. section 3.3.1
Check a search result
Searching for Kipchoge’s marathon record returns results with titles, URLs, snippets, and relevance scores. A Wikipedia result’s snippet reports his official marathon best as 2:01:09 at Berlin in 2022. The URL and snippet let the agent identify where that answer came from. section 3.3.1
Extend the wrapper only when the task needs more control:
- Use max_results to control how many results come back; use topic for general, news, or finance searches. section 3.3.1
- Pass time_range or country when a request calls for a time period or geographic focus. section 3.3.1
- Catch search exceptions and return an error message when the call fails. This changes the function’s possible return value from results alone to results or an error string, which callers must handle. section 3.3.1
In an agent loop, search is one tool among others. It cannot replace file reading when the needed information is in an attachment, and a model that recognizes it lacks information still needs the appropriate tool to obtain it. section 2.4.3 section 1.5.6
