English 繁體中文 简体中文

How to use an AI agent to write a draft with endnotes (Research, version 4)?

Howard Pong Yuen Lam · AI Notes · November 9, 2026 · 5 min read

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.

  1. Open the folder in Visual Studio Code.
  2. Create a file named .env in the folder with two lines:
    TAVILY_API_KEY=your-tavily-key
    DEEPSEEK_API_KEY=your-deepseek-key
    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.
  3. In the Terminal, run these three lines, one at a time:
    uv python pin 3.12.10
    uv sync
    uv run research04.py
  4. You should see three tools printed in turn: ten results from the search, seven from generate_draft, then the draft from write_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

Further reading