AI Engineering: Agents and Applications › AI Agents › Day 294

Hands-on lab — Day 294: Building a Research Agent

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/research_agent.py

Test

bash tests/run_tests.sh

File tree

examples/research_agent.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/research_agent.py
tests/run_tests.sh
tests/test_research_agent.py
troubleshooting.md

Lab README

Day 294 Lab: Building a Research Agent

Lesson

  • Lesson title: Building a Research Agent
  • Day number: 294 of 365
  • Lesson article: https://ai-roadmap-365.github.io/day-294-building-a-research-agent
  • Lab files: everything you need is in this directory — follow “How to run” below.
  • Browse the course locally: from the repository root, this lab also appears in the course website at /labs/day-294-building-a-research-agent when the site is running.

Purpose

Build an autonomous Deep Research Agent capable of multi-hop query decomposition, atomic fact extraction, structured note-taking, and cited Markdown brief synthesis.

Learning objectives

  • Implement query decomposition breaking broad topics into orthogonal sub-queries.
  • Extract atomic factual claims with verified source attribution into a Note Store.
  • Synthesize executive Markdown briefs with numbered inline citations.
  • Verify citation grounding and source deduplication.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/research_agent.py: Starter implementation skeleton
  • examples/research_agent.py: Verified reference implementation
  • tests/test_research_agent.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/research_agent.py

What the commands do

  • Executes agent runtime algorithms and logs state transitions to stdout.

Expected output

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Core state transitions and algorithm logic
  • Error observation handling and recovery
  • Edge cases and bounds enforcement

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Verify Python version is >= 3.10 and environment variables are set.

Security notes

Runs completely offline on local CPU without network calls or API keys.

Extension exercises

Implement async execution or enhanced caching strategies.

Day number: 294 of 365

Expected output

FIELDS.md

# Measured Values
- `notes_extracted`: 3
- `sub_queries`: 2

examples-run.txt


measured-values.txt

notes_extracted=3
sub_queries=2

run-output.txt


starter-run.txt

An untouched starter fails the suite. Captured from a real run:


self = <examples.research_agent.DeepResearchAgent object at 0x106da2520>
topic = 'Solid-State Batteries'

    def execute_research(self, topic: str) -> str:
>       raise NotImplementedError('TASK 6: implement execute_research.')
E       NotImplementedError: TASK 6: implement execute_research.

examples/research_agent.py:37: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_research_agent.py::test_note_store_deduplication - NotImple...
FAILED tests/test_research_agent.py::test_query_decomposition - NotImplemente...
FAILED tests/test_research_agent.py::test_end_to_end_research_synthesis - Not...
FAILED tests/test_research_agent.py::test_empty_search_fallback - NotImplemen...
FAILED tests/test_research_agent.py::test_note_citation_keys_match - NotImple...
============================== 5 failed in 0.04s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-294-building-a-research-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_research_agent.py::test_note_store_deduplication PASSED       [ 20%]
tests/test_research_agent.py::test_query_decomposition PASSED            [ 40%]
tests/test_research_agent.py::test_end_to_end_research_synthesis PASSED  [ 60%]
tests/test_research_agent.py::test_empty_search_fallback PASSED          [ 80%]
tests/test_research_agent.py::test_note_citation_keys_match PASSED       [100%]

============================== 5 passed in 0.01s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-294-building-a-research-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items

tests/test_research_agent.py::test_note_store_deduplication PASSED       [ 20%]
tests/test_research_agent.py::test_query_decomposition PASSED            [ 40%]
tests/test_research_agent.py::test_end_to_end_research_synthesis PASSED  [ 60%]
tests/test_research_agent.py::test_empty_search_fallback PASSED          [ 80%]
tests/test_research_agent.py::test_note_citation_keys_match PASSED       [100%]

============================== 5 passed in 0.01s ===============================

Source files

examples/research_agent.py (2953 bytes)
from typing import Dict, Any, List, Optional

class NoteStore:
    def __init__(self):
        self.notes: List[Dict[str, Any]] = []
        
    def add_note(self, claim: str, source_title: str, url: str) -> int:
        # Deduplication check
        for n in self.notes:
            if n["claim"] == claim and n["url"] == url:
                return n["id"]
        note_id = len(self.notes) + 1
        self.notes.append({
            "id": note_id,
            "claim": claim,
            "title": source_title,
            "url": url
        })
        return note_id
        
    def get_all(self) -> List[Dict[str, Any]]:
        return self.notes

class DeepResearchAgent:
    def __init__(self, search_kb: Optional[Dict[str, List[Dict[str, str]]]] = None):
        self.note_store = NoteStore()
        self.kb = search_kb or {
            "solid state energy density": [
                {"title": "Nature Energy 2025", "url": "https://nature.com/art1", "snippet": "Prototypes achieved 450 Wh/kg gravimetric density."},
                {"title": "Battery Journal", "url": "https://batteryj.org/art2", "snippet": "Cycle life reached 1200 cycles at C/3 charge rate."}
            ],
            "solid state manufacturing cost": [
                {"title": "BloombergNEF EV Report", "url": "https://bnef.com/ev2025", "snippet": "Cell-level costs projected at $95/kWh by 2028."}
            ]
        }
        
    def decompose_query(self, topic: str) -> List[str]:
        topic_lower = topic.lower()
        if "battery" in topic_lower or "solid-state" in topic_lower or "solid state" in topic_lower:
            return ["solid state energy density", "solid state manufacturing cost"]
        return [topic]
        
    def search_and_extract(self, query: str):
        results = self.kb.get(query, [])
        for r in results:
            self.note_store.add_note(r["snippet"], r["title"], r["url"])
            
    def synthesize_brief(self, topic: str) -> str:
        notes = self.note_store.get_all()
        if not notes:
            return f"# Research Brief: {topic}\n\nNo verified findings discovered."
            
        lines = [
            f"# Research Brief: {topic}",
            "",
            "## Executive Summary",
            f"This research investigation analyzed key findings regarding {topic}. The primary findings are detailed below:",
            ""
        ]
        
        for note in notes:
            lines.append(f"- {note['claim']} [{note['id']}]")
            
        lines.append("")
        lines.append("## Verified Sources")
        for note in notes:
            lines.append(f"[{note['id']}] [{note['title']}]({note['url']})")
            
        return "\n".join(lines)
        
    def execute_research(self, topic: str) -> str:
        sub_queries = self.decompose_query(topic)
        for q in sub_queries:
            self.search_and_extract(q)
        return self.synthesize_brief(topic)
metadata.yml (401 bytes)
lesson_id: D294
day: 294
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/research_agent.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/research_agent.py (1805 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

from typing import Dict, Any, List, Optional

class NoteStore:

    def __init__(self):
        self.notes: List[Dict[str, Any]] = []

    def add_note(self, claim: str, source_title: str, url: str) -> int:
        raise NotImplementedError('TASK 1: implement add_note.')

    def get_all(self) -> List[Dict[str, Any]]:
        raise NotImplementedError('TASK 2: implement get_all.')

class DeepResearchAgent:

    def __init__(self, search_kb: Optional[Dict[str, List[Dict[str, str]]]]=None):
        self.note_store = NoteStore()
        self.kb = search_kb or {'solid state energy density': [{'title': 'Nature Energy 2025', 'url': 'https://nature.com/art1', 'snippet': 'Prototypes achieved 450 Wh/kg gravimetric density.'}, {'title': 'Battery Journal', 'url': 'https://batteryj.org/art2', 'snippet': 'Cycle life reached 1200 cycles at C/3 charge rate.'}], 'solid state manufacturing cost': [{'title': 'BloombergNEF EV Report', 'url': 'https://bnef.com/ev2025', 'snippet': 'Cell-level costs projected at $95/kWh by 2028.'}]}

    def decompose_query(self, topic: str) -> List[str]:
        raise NotImplementedError('TASK 3: implement decompose_query.')

    def search_and_extract(self, query: str):
        raise NotImplementedError('TASK 4: implement search_and_extract.')

    def synthesize_brief(self, topic: str) -> str:
        raise NotImplementedError('TASK 5: implement synthesize_brief.')

    def execute_research(self, topic: str) -> str:
        raise NotImplementedError('TASK 6: implement execute_research.')
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_research_agent.py (1414 bytes)
import pytest
from examples.research_agent import NoteStore, DeepResearchAgent

def test_note_store_deduplication():
    store = NoteStore()
    id1 = store.add_note("Fact A", "Title 1", "https://url1.com")
    id2 = store.add_note("Fact A", "Title 1", "https://url1.com")
    assert id1 == 1
    assert id2 == 1
    assert len(store.get_all()) == 1

def test_query_decomposition():
    agent = DeepResearchAgent()
    queries = agent.decompose_query("Solid-state battery roadmap")
    assert len(queries) == 2
    assert "solid state energy density" in queries
    assert "solid state manufacturing cost" in queries

def test_end_to_end_research_synthesis():
    agent = DeepResearchAgent()
    brief = agent.execute_research("Solid-State Batteries")
    assert "# Research Brief: Solid-State Batteries" in brief
    assert "450 Wh/kg" in brief
    assert "$95/kWh" in brief
    assert "## Verified Sources" in brief
    assert "[1] [Nature Energy 2025](https://nature.com/art1)" in brief

def test_empty_search_fallback():
    agent = DeepResearchAgent()
    brief = agent.execute_research("Unknown Futuristic Technology")
    assert "No verified findings discovered." in brief

def test_note_citation_keys_match():
    agent = DeepResearchAgent()
    brief = agent.execute_research("Solid-State Batteries")
    notes = agent.note_store.get_all()
    for note in notes:
        assert f"[{note['id']}]" in brief

Troubleshooting

Troubleshooting - Day 294

  1. Empty NoteStore: Ensure query decomposition produces terms present in the knowledge database.
  2. Citation Mismatch: Check that citation indices in the report text map to corresponding indices in the bibliography.

Security notes

Security Considerations - Day 294

  1. SSRF Prevention: All simulated web lookups enforce strict domain allowlisting.
  2. Citation Grounding: Synthesizer only emits citations matching verified records in the NoteStore.