How to search the web from Python (Research, version 1)?
The ReAct notes built an agent that thinks in a loop; these notes build an AI research assistant that searches, chooses, and writes a draft with its sources listed. Version 1 has no AI in it at all. It only searches, and shows you what a search returns.
That is deliberate. Before we let a model drive the search, we should know exactly what the search gives back — the titles, the links, and that number called the score. Everything later in this series works on this material.
Why start with no agent
A search service already reads the web for us. Tavily is built for programs: you send it a question, it sends back ten results, and each result arrives with a short piece of the page attached.
Step 1: read the key
import os
from dotenv import load_dotenv
load_dotenv()
TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
The search service needs to know who is asking, so it issues a key.
load_dotenv() reads that key from a file named
.env, and os.getenv puts it into a variable the
program can use. The key itself never appears in the code.
Step 2: one call to Tavily
from tavily import TavilyClient
tavily_client = TavilyClient(api_key=TAVILY_API_KEY)
response = tavily_client.search("What is the population of Hong Kong?")
Two lines do the work. The first connects to Tavily with our key. The
second sends the question, and the whole answer lands in
response.
Step 3: what comes back
response holds the question again, under the name
query, and a list called results. Each result is a
small package of four things:
title— the name of the page.url— where it lives, so a reader can check it later.content— a short piece of the page's text, not the whole page.score— how well the page matches the question, from 0 to 1.
The score is the one to watch. In the output below it runs from 0.94 down to 0.11, and the low scores are not junk: they are official pages that happen to say less about our exact question.
Step 4: print each result
print(f"Query: {response['query']}\n")
for i, r in enumerate(response["results"], start=1):
print(f"{i}. {r['title']} (score: {r['score']:.2f})")
print(f" {r['url']}")
print(f" {r['content'][:200].replace(chr(10), ' ')}...\n")
Four lines, one job each.
enumerate(..., start=1) numbers the results 1, 2, 3,
so we can point at one later.
{r['score']:.2f} shows the score with two decimal places,
which turns 0.9234 into 0.92.
{r['content'][:200]} keeps only the first 200
characters of the page text. [:200] is shorthand for
[0:200], which means characters 0 to 199: Python counts from 0
and leaves out the last number, so the cut stops at 199.
replace(chr(10), ' ') swaps line breaks for spaces, so a
result stays on three tidy lines instead of spilling down the screen.
...\n at the end will print ... and a new line
character.
What comes out
Query: What is the population of Hong Kong?
1. Hong Kong Population (2026) - Worldometer (score: 0.92)
https://www.worldometers.info/world-population/china-hong-kong-sar-population
The current population of the Hong Kong Special Administrative Region of the People's Republic of China is 7,371,564 as of Sunday, October 18, 2026, based on Worldometer's elaboration of the latest Un...
2. Hong Kong Population 2026 (score: 0.94)
https://worldpopulationreview.com/countries/hong-kong
### Request Data Please enter your email address to receive this data in your inbox. ## Hong Kong By the Numbers As of 2026, Hong Kong has a total populationof 7,378,602, ranking as the 107th most...
3. Hong Kong Map, History & Population | Study.com (score: 0.93)
https://study.com/academy/lesson/hong-kong-facts-population.html
The population of Hong Kong is 7.5 million. Two million people live in Kowloon, the southern part of the peninsula, and 1 million people live in the northern part of Hong Kong Island, called Victoria ...
...
Ten results, and already three different numbers: 7,371,564, 7,378,602 and 7.5 million. This is normal. Each page was written on a different day, and each rounds the figure differently. Nothing here decides which number is right — that is a job for later versions, and for you.
Notice too that the results are not sorted by score: result 1 scores 0.92 and result 2 scores 0.94. Tavily returns them in its own order, which mixes relevance with what it thinks a reader will find useful first.
The whole program
# RESEARCH, version 1: search the web from Python, with no AI agent.
# Before an agent can research, it needs material. This program gets that
# material: one question in, ten search results out.
import os
from dotenv import load_dotenv
load_dotenv()
TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
from tavily import TavilyClient
tavily_client = TavilyClient(api_key=TAVILY_API_KEY)
response = tavily_client.search("What is the population of Hong Kong?")
print(f"Query: {response['query']}\n")
for i, r in enumerate(response["results"], start=1):
print(f"{i}. {r['title']} (score: {r['score']:.2f})")
print(f" {r['url']}")
print(f" {r['content'][:200].replace(chr(10), ' ')}...\n")
# Try it: change the question, or the number of results:
# tavily_client.search("What is the population of Hong Kong?", max_results=3)
Running it on your own computer
Download the demo program
(Folder-AI-Research01.zip). The zip holds three files:
research01.py (the full script), pyproject.toml and
README.md. No language model is called, so this version needs
only a Tavily key.
- Open the folder in Visual Studio Code.
-
Create a file named
.envin the folder with one line:
A key is available from the Tavily dashboard. Usage is billed by the provider, so check the current pricing terms there before you run it.TAVILY_API_KEY=your-tavily-key - In the Terminal, run these three lines, one at a time:
uv python pin 3.12.10uv syncuv run research01.py - You should see the question and ten numbered results. It takes a few seconds.
If you have not set up uv yet, start with How to install Visual Studio Code? and then the uv note for Windows or Mac.
Limitations
- You do the reading. Without an agent, a search brings back many results and you read them yourself, deciding what each one is worth. With an agent, you can hand that reading to the AI, which finds what you are looking for — as the later versions in this series show.
- The preview is not the page. Two hundred characters are enough to judge relevance and not enough to quote. The full text is one click away, at the URL.
- Scores are relevance, not truth. A high score means the page matches the wording of the question. A page full of the same words can score well and still be out of date or wrong.
- Numbers disagree. As above: three pages, three population figures. Search finds sources; it does not settle them.
Further reading
- Tavily documentation — the
searchcall, its parameters and its response fields. - Tavily search API reference — what each field in a result contains.
- How does an AI agent research a question (ReAct, version 3, web search in a loop)? — the same idea wrapped inside an agent.
- How do multiple AI agents work under a supervisor (ReAct, version 10)? — where a team of agents ends up.