Build a research agent you can trust

In this workshop

1. 1What changed since Day 2 Everyone
2. 2How the agent works Everyone
3. 3What our test runs showed Everyone
4. 4From notebook to project Developers
5. 5Build and run it: 8 steps Developers
6. 6Problems and fixes Developers
7. 710 POC ideas to build next Everyone
8. 8Practice and quiz Everyone

We ran the notebook version (Gemini + Tavily, no system prompt and no calculator) on two questions in October 2026. Both runs finished without errors. One answer was right, and one contradicted its own search results.

Test A: "What is the latest iPhone model and its price in USD?"

Test B: healthcare cost check

"List the top 3 Medicare providers. A 50-day joint replacement episode costs hospital $21,500, post-acute care $8,400 and readmission $3,200. The target price is $31,000. Are we above or below target?"

How the project fixes these

Rules reduce these mistakes but do not remove them. For anything important, compare the answer with the sources in the trace, or keep a person in the loop.

1. Create the environment and install

   PowerShellCopy

   # Windows PowerShell (macOS/Linux: python3, source .venv/bin/activate, cp)
   cd tavily_agent
   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements.txt
   copy .env.example .env      # open .env and paste your two keys

   requirements.txtCopy

   # Versions tested in the workshop notebook (Oct 2026). Pin them so the project keeps working.
   langchain==1.4.3
   langchain-core==1.6.7
   langgraph==1.2.14
   langchain-google-genai==4.4.0
   langchain-tavily==0.2.18
   python-dotenv==1.2.4
   pytest>=8

   Pinned versions are the ones the workshop notebook ran with. Pinning means the project still works in three months, even after the libraries change.

2. Add your two free keys

   .env.example → copy to .envCopy

   # Copy this file to ".env" and paste your real keys. Never commit .env to GitHub.
   GOOGLE_API_KEY=your_google_api_key        # https://aistudio.google.com/apikey
   TAVILY_API_KEY=your_tavily_api_key        # https://app.tavily.com  (free: 1,000 credits/month)
   
   # Optional settings
   GEMINI_MODEL=gemini-3.5-flash-lite
   SEARCH_MAX_RESULTS=5

   Get the Gemini key from Google AI Studio and the Tavily key from app.tavily.com. .gitignore already stops .env from being committed.

3. Keep all settings in one file

   config.pyCopy

   """All settings in one place. Change the model here or in .env, never inside the code."""
   import os
   from dataclasses import dataclass
   
   from dotenv import load_dotenv
   
   load_dotenv()
   
   REQUIRED_KEYS = ("GOOGLE_API_KEY", "TAVILY_API_KEY")
   
   
   @dataclass(frozen=True)
   class Settings:
       model: str = os.getenv("GEMINI_MODEL", "gemini-3.5-flash-lite")
       search_max_results: int = int(os.getenv("SEARCH_MAX_RESULTS", "5"))
       timeout_seconds: int = 60
       max_retries: int = 3
   
   
   def check_keys() -> None:
       """Stop early with a clear message instead of a long stack trace later."""
       missing = [key for key in REQUIRED_KEYS if not os.getenv(key)]
       if missing:
           raise SystemExit(
               f"Missing {', '.join(missing)}. Copy .env.example to .env and add your keys."
           )

   When a model name stops working (Day 2 hit two model-name errors), you change one line in .env, not code in five places. check_keys() stops early with a clear message.

4. Test search on its own first

   test_search.py (optional check)Copy

   from dotenv import load_dotenv
   from langchain_tavily import TavilySearch
   
   load_dotenv()
   search = TavilySearch(max_results=5)
   
   result = search.invoke({"query": "latest iPhone model and price in USD"})
   for item in result["results"]:
       print(f"{item['score']:.2f}  {item['title']}\n      {item['url']}")

   Results from our run:

   Output

   0.72  Apple - Explore the latest iPhone lineup, with prices...
         https://www.facebook.com/apple/posts/...
   0.64  Apple raises iPhone prices: Here's what each model costs now
         https://www.newsnationnow.com/business/your-money/apple-raises-iphone-prices
   0.48  Best iPhone in 2026: Apple's Phones Cost More, Here Are the Ones to Buy - CNET
         https://www.cnet.com/tech/mobile/best-iphone
   0.44  Apple's iPhone Pricing is a MESS
         https://www.youtube.com/watch?v=hSfpZKA6Pzg
   0.44  Which iPhone Should You Buy? - Consumer Reports
         https://www.consumerreports.org/electronics-computers/cell-phones/which-iphone-should-you-buy-a7028071026

   Testing a tool alone before adding it to an agent tells you whether a problem is in the search or in the model. Notice that the top-scored result was a social media post, so a high score doesn't always mean the best source.

5. Write the tools

   tools.pyCopy

   """Tools the agent may call. Each docstring is what Gemini reads to decide when to use it."""
   import ast
   import operator
   from datetime import date
   
   from langchain.tools import tool
   from langchain_tavily import TavilySearch
   
   _OPERATORS = {
       ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
       ast.Div: operator.truediv, ast.Pow: operator.pow, ast.Mod: operator.mod,
       ast.USub: operator.neg, ast.UAdd: operator.pos,
   }
   
   
   def _evaluate(node: ast.AST) -> float:
       if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
           return node.value
       if isinstance(node, ast.BinOp) and type(node.op) in _OPERATORS:
           return _OPERATORS[type(node.op)](_evaluate(node.left), _evaluate(node.right))
       if isinstance(node, ast.UnaryOp) and type(node.op) in _OPERATORS:
           return _OPERATORS[type(node.op)](_evaluate(node.operand))
       raise ValueError("Only numbers and + - * / % ** ( ) are allowed")
   
   
   def safe_calculate(expression: str) -> float:
       """Evaluate arithmetic without eval(), so the model cannot run arbitrary code."""
       return _evaluate(ast.parse(expression.replace(",", ""), mode="eval").body)
   
   
   @tool
   def calculator(expression: str) -> str:
       """Do exact arithmetic, e.g. '21500 + 8400 + 3200 - 31000'. Use this for every calculation."""
       try:
           return f"{expression} = {safe_calculate(expression):,.2f}"
       except (ValueError, SyntaxError, ZeroDivisionError) as err:
           return f"Could not calculate '{expression}': {err}"
   
   
   @tool
   def today() -> str:
       """Return today's date. Use it when the question depends on 'latest', 'current' or 'this year'."""
       return date.today().isoformat()
   
   
   def build_tools(max_results: int) -> list:
       web_search = TavilySearch(max_results=max_results)   # reads TAVILY_API_KEY from the environment
       return [web_search, calculator, today]

   The calculator parses the expression with Python's ast module and allows only numbers and operators. Never pass model output to eval(): a model, or a web page it read, could make it run any code on your laptop.

6. Build the agent with rules

   agent.pyCopy

   """Builds the agent: Gemini (the brain) + tools (the hands) + rules (the system prompt)."""
   from langchain.agents import create_agent
   from langchain_google_genai import ChatGoogleGenerativeAI
   
   from config import Settings
   from tools import build_tools
   
   SYSTEM_PROMPT = """You are a careful research assistant.
   Rules:
   1. For anything that changes over time (products, prices, rankings, news, laws), use web search. Do not answer from memory.
   2. Use only facts that appear in the search results. If sources disagree or a fact is missing, say so.
   3. Use the calculator tool for every calculation, even simple ones.
   4. End with a 'Sources:' list of the URLs you used.
   5. Write plain text with simple bullet points. Do not use LaTeX or math formatting."""
   
   
   def build_agent(settings: Settings | None = None):
       settings = settings or Settings()
       llm = ChatGoogleGenerativeAI(
           model=settings.model,
           timeout=settings.timeout_seconds,
           max_retries=settings.max_retries,
       )
       return create_agent(
           model=llm,
           tools=build_tools(settings.search_max_results),
           system_prompt=SYSTEM_PROMPT,
       )

   The system prompt turns what we learned in section 3 into instructions. Each rule fixes one problem we actually saw.

7. Run it from the terminal

   output.pyCopy

   """Helpers to turn the agent's raw response into readable text."""
   
   
   def text_of(content) -> str:
       """Gemini 3.x returns a list of content blocks; older models return a string."""
       if isinstance(content, list):
           return "".join(part.get("text", "") for part in content if isinstance(part, dict))
       return str(content)
   
   
   def print_trace(messages) -> None:
       """Show every step of the agent loop: question, tool calls, tool results, answer."""
       for msg in messages:
           kind = type(msg).__name__
           if kind == "HumanMessage":
               print(f"\n[You] {text_of(msg.content).strip()[:200]}")
           elif kind == "AIMessage" and msg.tool_calls:
               for call in msg.tool_calls:
                   print(f"[Gemini -> tool] {call['name']}({call['args']})")
           elif kind == "ToolMessage":
               print(f"[Tool result]    {text_of(msg.content)[:160].strip()}...")
           elif kind == "AIMessage":
               print("[Gemini] final answer written")

   main.pyCopy

   """Run the agent from the terminal.
   
       python main.py "What is the latest iPhone model and its price in USD?"
       python main.py --trace "Is a $33,100 episode above a $31,000 target?"
       python main.py            # interactive mode, type 'exit' to quit
   """
   import argparse
   
   from agent import build_agent
   from config import check_keys
   from output import print_trace, text_of
   
   
   def ask(agent, question: str, trace: bool) -> None:
       response = agent.invoke({"messages": [{"role": "user", "content": question}]})
       if trace:
           print_trace(response["messages"])
       print("\n" + "=" * 70)
       print(text_of(response["messages"][-1].content).strip())
       print("=" * 70)
   
   
   def main() -> None:
       parser = argparse.ArgumentParser(description="Gemini + Tavily research agent")
       parser.add_argument("question", nargs="*", help="Your question (leave empty for interactive mode)")
       parser.add_argument("--trace", action="store_true", help="Show each tool call the agent makes")
       args = parser.parse_args()
   
       check_keys()
       agent = build_agent()
   
       if args.question:
           ask(agent, " ".join(args.question), args.trace)
           return
   
       print("Research agent ready. Type a question, or 'exit' to quit.")
       while True:
           question = input("\nYou: ").strip()
           if question.lower() in {"exit", "quit", ""}:
               break
           ask(agent, question, args.trace)
   
   
   if __name__ == "__main__":
       main()

   Try theseCopy

   python main.py --trace "What is the latest iPhone model and its price in USD?"
   
   python main.py --trace "A 50-day joint replacement episode costs: hospital $21,500, post-acute care $8,400, readmission $3,200. The target price is $31,000. Are we above or below target, and by how much?"
   
   python main.py          # interactive mode

   What --trace prints (the format; your queries and results will differ):

   Example trace

   [You] What is the latest iPhone model and its price in USD?
   [Gemini -> tool] tavily_search({'query': 'latest iPhone model price USD'})
   [Tool result]    {"query": "latest iPhone model price USD", "results": [{"url": "https://www.newsnationnow.com/...
   [Gemini] final answer written

8. Run the tests

   tests/test_tools.pyCopy

   """Run with: pytest -q   (no API keys or internet needed)"""
   import sys
   from pathlib import Path
   
   import pytest
   
   sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
   
   from output import text_of  # noqa: E402
   from tools import calculator, safe_calculate  # noqa: E402
   
   
   def test_bundle_cost_from_workshop():
       assert safe_calculate("21500 + 8400 + 3200") == 33100
       assert safe_calculate("21500 + 8400 + 3200 - 31000") == 2100
   
   
   def test_commas_and_brackets():
       assert safe_calculate("(1,199 - 999) * 2") == 400
   
   
   def test_rejects_code():
       with pytest.raises(ValueError):
           safe_calculate("__import__('os').system('dir')")
   
   
   def test_calculator_tool_output():
       assert calculator.invoke({"expression": "10 / 4"}) == "10 / 4 = 2.50"
       assert "Could not calculate" in calculator.invoke({"expression": "1/0"})
   
   
   def test_text_of_handles_gemini_blocks():
       assert text_of([{"type": "text", "text": "Hello"}]) == "Hello"
       assert text_of("Hello") == "Hello"

   Expected result

   pytest -q
   .....                                                                    [100%]
   5 passed

   These tests need no keys or internet, so they run in a second. They check the exact cost case from Test B, and that the calculator refuses code. Add a test every time you add a tool.

# tools.py - example: add a currency converter in 3 steps
@tool
def convert_currency(amount: float, rate: float, from_code: str, to_code: str) -> str:
    """Convert an amount between currencies. Search for today's exchange rate first."""
    return f"{amount:,.2f} {from_code} = {amount * rate:,.2f} {to_code} (rate {rate})"

def build_tools(max_results: int) -> list:
    web_search = TavilySearch(max_results=max_results)
    return [web_search, calculator, today, convert_currency]   # step 2: register it

Each idea reuses this project. You keep agent.py and change the tools and the rules. They're ordered from easiest to hardest, and each one makes a good portfolio or interview project.

Practice tasks

1. Run Test A with --trace. Does the agent's price now match the search results? Note which URLs it cites.
2. Change SEARCH_MAX_RESULTS to 2 and to 8. How do the answer quality and the number of credits used change?
3. Add the convert_currency tool and ask for the iPhone 18 Pro price in GBP and INR.
4. Pick one POC from section 7 and build the first version in under an hour.

Quick quiz

Summary