How to use an AI agent to write a draft with endnotes (Research, version 4)?
The previous version used two tools:
search_internet brought back ten results, and
generate_draft kept seven of them. This version adds
a third tool that turns those seven results into a short draft, with one
numbered endnote for each sentence.
The important word is copied. The draft is not a summary written by the model. Each sentence in it is taken word for word from a page, and the endnote says which page it came from. That is a promise you can check.
A second place to keep results
The two earlier versions used one shared variable. This one needs a second, because the new tool works on the results that the filter kept, not on the ten that the search returned.
# Keeps the latest search response so generate_draft can use it
last_search = {}
# Keeps the results selected by generate_draft so write_draft can use them
selected_results = []
The reason is the same as before. Each tool is a separate function, and a variable made inside one function disappears when that function ends. Both variables sit outside the functions, so one tool can leave something there and the next tool can pick it up.
Tool three: write_draft
return_direct=True sits on the tool whose result
should be the final answer. Here that is the draft, so the run ends as soon
as write_draft is completed.
@tool(return_direct=True)
def write_draft(sentences: list[str]):
"""
Write a draft with endnotes from the results of generate_draft.
sentences: one sentence per result from generate_draft, in the same order.
Each sentence must be copied exactly from that result's content, and be
the sentence closest in meaning to the user's query.
Use an empty string "" for a result that has no complete sentence.
"""
Look at what the tool receives: sentences: list[str].
A list of text. The tool never opens a page
and never reads a search result. The model does that part, and hands over
only the sentences it chose.
That split is deliberate. Choosing the sentence closest in meaning to the question is a judgement, and a model is good at judgements. Joining text, numbering endnotes and skipping empty entries is exact work with no judgement in it, and Python never gets that wrong. Each side does what it does well.
The docstring is where the model learns the rules: one sentence per kept
result, in the same order, copied exactly, the one closest in meaning to the
question, and
"" when a page has no complete sentence to
offer.
Inside the tool
s = ""
endnotes = ""
endnote_num = 1
for sentence, r in zip(sentences, selected_results):
if sentence.strip() == "":
continue # skip results with no complete sentence
s = s + sentence + "[" + str(endnote_num) + "] "
endnotes = endnotes + f"[{endnote_num}] {r['url']}\n"
endnote_num = endnote_num + 1
s = s + "\n\nEndnotes:\n" + endnotes
return s
Three empty things are made first: the draft s,
the endnote list, and a counter that starts at 1.
zip walks the two lists side by side. On the
first pass it hands over the first sentence and the first kept result, on the
second pass the second of each, and so on. That is why the model was told to
keep the same order: the pairing is done by position, not by matching
anything.
The if catches the empty strings.
strip() removes spaces first, so a sentence
that is only a space also counts as empty. When it matches,
continue jumps to the next pair, and the rest
of the loop body is skipped, so no endnote number is wasted. That is why the
seven kept results can produce fewer than seven endnotes.
The next line builds one sentence of the draft: the text, then its number in
square brackets, then a space.
str() turns the counter into text, because a
number cannot be glued to a string. Only a space is added at the end, which
is why all the sentences appear on one long line in the output.
The endnote line uses an f-string, and
{r['url']} fills in the link of the matching
result. A line break is added at the end, so each endnote sits on its own
line.
The last step adds a blank line, the heading
Endnotes: and the whole endnote list after the
sentences, then returns the finished draft.
The AI Agent
agent = create_agent(
model=my_model,
tools=[search_internet, generate_draft, write_draft],
system_prompt=(
"You are a helpful assistant. "
"Always call search_internet, using the user's message exactly as the query. "
"Do not rephrase, shorten, translate, or add anything to it. "
"Then call generate_draft to select the useful results. "
"Then go through each sentence in each selected result, pick the one sentence "
"closest in meaning to the user's query, and copy it exactly. "
"A complete sentence has a subject and a verb and ends with a full stop; "
"table rows, headings, menus and fragments are not complete sentences. "
"If a result has no complete sentence, use an empty string \"\" for it. "
"Call write_draft with these sentences in the same order as the results."
),
)
The tools list now holds
search_internet,
generate_draft and
write_draft, and the prompt tells the model to do
the work.
Two of the new sentences deserve attention. "Copy it exactly" blocks paraphrasing: a rewritten sentence looks better and is harder to trace back to the page. And the definition of a complete sentence matters because web pages are full of things that are not sentences — headings, menu items, table rows, fragments that end in the middle.
What comes out
The screen prints three tool blocks:
search_internet,
generate_draft and
write_draft, in that order.
Tool: write_draft
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 United Nations data 1.[1] As of 2026, Hong Kong has a total population of 7,378,602, ranking as the 107th most populous nation inthe world.[2] The population of Hong Kong is 7.5 million.[3] Total current population for Hong Kong in 2026 is 7,500,962, a 0.02% increase from 2025.[4] In 2023, the estimated population of Hong Kong was 7.443 million.[5] Hong Kong's population was approximately 7.50 million in mid-2025.[6] The 2021 Population Census found (by way of self-identification) that there were about 619,568 non-Chinese people in Hong Kong, or about 8.4% of the population.[7]
Endnotes:
[1] https://www.worldometers.info/world-population/china-hong-kong-sar-population
[2] https://worldpopulationreview.com/countries/hong-kong
[3] https://study.com/academy/lesson/hong-kong-facts-population.html
[4] https://www.macrotrends.net/global-metrics/countries/hkg/hong-kong/population
[5] https://ourworldindata.org/profile/population-demography/hong-kong
[6] https://www.gov.hk/en/about/abouthk/facts.htm
[7] https://www.had.gov.hk/rru/en/info/demographics.htm
Seven sentences, seven endnotes, and every sentence can be traced back to a page. The numbers in them do not agree: 7,371,564, 7,378,602, 7.5 million, 7,500,962, 7.443 million and 7.50 million. That is not a bug. It is what the seven pages actually say, and the draft refuses to hide the disagreement by averaging them. The seventh sentence is the exception: it is about the non-Chinese share of the population, so it carries no total of its own.
One sentence is worth a second look. Endnote [5] is dated 2023, yet the printed preview of that result in the previous block showed nothing about 2023. The reason is that the program prints only the first 200 characters of each result, while the model read the whole page text. What you see on screen is a preview; what the model chose from is longer.
The whole program
import os
import json
from dotenv import load_dotenv
from tavily import TavilyClient
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
load_dotenv()
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
tavily_client = TavilyClient(api_key=TAVILY_API_KEY)
# Keeps the latest search response so generate_draft can use it
last_search = {}
# Keeps the results selected by generate_draft so write_draft can use them
selected_results = []
@tool
def search_internet(query: str):
"""
Search the internet for up-to-date information about the query
and return the full Tavily search response.
"""
global last_search
response = tavily_client.search(query, max_results=10)
last_search = response
return response
@tool
def generate_draft():
"""
Go through the results from the latest search_internet call.
Keep results with a score of 0.5 or higher, but never keep Wikipedia.
Return the selected results.
"""
global selected_results
selected = []
for r in last_search.get("results", []):
if r["score"] >= 0.5 and "wikipedia.org" not in r["url"]:
selected.append(r)
selected_results = selected
return {"query": last_search.get("query"), "results": selected}
@tool(return_direct=True)
def write_draft(sentences: list[str]):
"""
Write a draft with endnotes from the results of generate_draft.
sentences: one sentence per result from generate_draft, in the same order.
Each sentence must be copied exactly from that result's content, and be
the sentence closest in meaning to the user's query.
Use an empty string "" for a result that has no complete sentence.
"""
s = ""
endnotes = ""
endnote_num = 1
for sentence, r in zip(sentences, selected_results):
if sentence.strip() == "":
continue # skip results with no complete sentence
s = s + sentence + "[" + str(endnote_num) + "] "
endnotes = endnotes + f"[{endnote_num}] {r['url']}\n"
endnote_num = endnote_num + 1
s = s + "\n\nEndnotes:\n" + endnotes
return s
my_model = ChatOpenAI(
model="deepseek-flash",
api_key=DEEPSEEK_API_KEY,
base_url="https://api.deepseek.com",
temperature=0,
)
agent = create_agent(
model=my_model,
tools=[search_internet, generate_draft, write_draft],
system_prompt=(
"You are a helpful assistant. "
"Always call search_internet, using the user's message exactly as the query. "
"Do not rephrase, shorten, translate, or add anything to it. "
"Then call generate_draft to select the useful results. "
"Then go through each sentence in each selected result, pick the one sentence "
"closest in meaning to the user's query, and copy it exactly. "
"A complete sentence has a subject and a verb and ends with a full stop; "
"table rows, headings, menus and fragments are not complete sentences. "
"If a result has no complete sentence, use an empty string \"\" for it. "
"Call write_draft with these sentences in the same order as the results."
),
)
prompt = "What is the population of Hong Kong?"
result = agent.invoke({
"messages": [{"role": "user", "content": prompt}]
})
for message in result["messages"]:
if message.type == "tool" and message.name == "write_draft":
print(f"Tool: {message.name}\n")
print(message.content)
elif message.type == "tool":
response = json.loads(message.content)
print(f"Tool: {message.name}")
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")
Running it on your own computer
Download the demo program
(Folder-AI-Research04.zip). The zip holds three files:
research04.py (the full script), pyproject.toml and
README.md. This version calls a language model once, so it
needs both a Tavily key and a DeepSeek key.
- Open the folder in Visual Studio Code.
-
Create a file named
.envin the folder with two lines:
A Tavily key is available from the Tavily dashboard, and a DeepSeek key from the DeepSeek console. Usage is billed by each provider, so check the current pricing terms there before you run it.TAVILY_API_KEY=your-tavily-key DEEPSEEK_API_KEY=your-deepseek-key - In the Terminal, run these three lines, one at a time:
uv python pin 3.12.10uv syncuv run research04.py - You should see three tools printed in turn: ten results from the search,
seven from
generate_draft, then the draft fromwrite_draft. The run 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
- A draft, not a report. The result is a row of quoted sentences in the order of the results. Nothing connects one sentence to the next, and nothing says which number to trust.
- The numbers still disagree. Six of the seven sentences give a population figure, and they range from 7.371 million to 7.5 million. The draft is honest about that, but it cannot resolve it.
- Copying is not checking. A sentence copied exactly can still be out of date, and the model may choose a sentence that scores well for the question but says something misleading.
- Position decides the pairing. Sentences are matched to results by order. If the model skips one result and sends six sentences for seven results, every endnote after that point is attached to the wrong page.
- An empty string can hide a result. A page with useful figures but no complete sentence contributes nothing, and the draft does not say that it was dropped.
Further reading
- How to use an AI agent to select useful search results (Research, version 3)? — where the seven results come from.
- How to use an AI agent to search the web (Research, version 2)? — the tools that this version builds on.
- LangChain documentation — tools,
return_directandcreate_agent. - Tavily documentation — the
searchcall and its response fields.