Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 32 ยท Projects and Practice

Project: A Research Assistant Agent

Build a research assistant agent step by step: tools for searching notes, calculating and saving findings, a planning loop, guardrails and tests. Real LangChain code plus runnable stand-in.

In this project you design a small research assistant. The user asks a question ("Which of our two plans is cheaper for 40 users, and what do the docs say about refunds?"). The agent searches a set of notes, does arithmetic with a calculator, saves a finding, and writes a short answer with sources. You will put together the pieces from the earlier lessons: tools, the agent loop, guardrails and evaluation.

LangChain and a model provider are not available on this site. The real LangChain version is shown read-only. The runnable version has the same structure with a scripted stand-in model, so it runs the whole agent end to end and you can test your tools and guardrails.

Requirements

  1. Search a small knowledge base and return passages with source names.
  2. Do arithmetic accurately (models are unreliable at math, so use a tool).
  3. Save findings to a notebook the final answer can cite.
  4. Stop after a fixed number of steps; never crash on a bad tool call.
  5. Answer only from what the tools returned, and say when nothing was found.
flowchart TD
    Q["Question"] --> M["Model"]
    M -->|"search_notes"| S["Notes search"]
    M -->|"calculate"| C["Calculator"]
    M -->|"save_finding"| N["Notebook"]
    S --> M
    C --> M
    N --> M
    M -->|"final answer"| A["Answer with sources"]

The research assistant: one model, three tools.

The real LangChain version

Python
# Real LangChain (read-only)
from langchain.agents import create_agent
from langchain.tools import tool

NOTES = {
    "plans.md": "Basic plan costs 12 dollars per user per month. Pro plan costs 20 dollars per user per month.",
    "refunds.md": "Refunds are available within 30 days of purchase for annual plans.",
}
notebook: list[str] = []

@tool
def search_notes(query: str) -> str:
    """Search the notes. Returns matching passages prefixed with their source file."""
    words = set(query.lower().split())
    hits = [f"[{name}] {text}" for name, text in NOTES.items() if words & set(text.lower().split())]
    return "\n".join(hits) or "No matching notes."

@tool
def calculate(expression: str) -> str:
    """Evaluate a basic arithmetic expression such as '40 * 12'. Use for all math."""
    allowed = set("0123456789+-*/(). ")
    if not set(expression) <= allowed:
        return "Error: only digits and + - * / ( ) are allowed."
    return str(eval(expression, {"__builtins__": {}}))

@tool
def save_finding(text: str) -> str:
    """Save a short finding, with its source, to the notebook."""
    notebook.append(text)
    return f"Saved finding #{len(notebook)}."

agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[search_notes, calculate, save_finding],
    system_prompt=(
        "You are a research assistant. Use search_notes for facts and calculate for math. "
        "Cite the source file in square brackets. If the notes do not contain the answer, say so."
    ),
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Cheapest plan for 40 users per month? Refund rules?"}]},
    config={"recursion_limit": 15},
)
print(result["messages"][-1].content)

Design notes: the system prompt names the tools and the citation rule; the calculator rejects anything but arithmetic characters; the recursion limit bounds the run. A production calculator should use a proper expression parser rather than eval, even a restricted one.

A runnable version

The tools below are real Python and run as written. Only the model is a scripted stand-in: a function that plays the part of the LLM by following a fixed plan. That is enough to test the loop, the tools and the guardrails.

Python Stand-in: the research assistant end to end

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last tool call tries to import a module through the calculator. The guard rejects it with a readable error, the loop continues, and the model still answers. That is the behavior you want from every tool.

Testing the assistant

Turn the behavior into tests. Each test asserts one property of tool use or of the final answer, using the evaluation ideas from Evaluating LLM Applications.

Python Stand-in: tests for tools and guardrails

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For the full agent, record a few questions with expected tool trajectories (search before calculate, no calls when the notes lack the answer) and run them against a fake model in CI and against the real model before releases.

Extensions to try

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why give the agent a calculator tool?

    Delegating arithmetic to code makes results exact.
  2. 2. What should the calculator do with input containing letters or function calls?

    Untrusted input must be validated; the error lets the model recover.
  3. 3. How is the answer kept honest?

    Grounding rules in the prompt plus tests on tool use keep answers tied to the notes.
  4. 4. What bounds the number of steps in the real agent?

    The recursion limit raises an error if the run takes too many steps.

Summary

  • The assistant is a model, three small tools and a bounded loop.
  • Validate tool input, cite sources, and say when nothing was found.
  • Test tools directly and test trajectories of the agent with a fake model.
  • Extend with vector search, approvals, persistence and tracing.

Next: Project: A Support Bot with Retrieval