AI Engineering: Agents and Applications › AI Agents › Day 294
Hands-on lab — Day 294: Building a Research Agent
- ← Back to the Day 294 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/ai-engineering/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-agentwhen 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 skeletonexamples/research_agent.py: Verified reference implementationtests/test_research_agent.py: Test suiteexpected-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.
Navigation
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
- Empty NoteStore: Ensure query decomposition produces terms present in the knowledge database.
- Citation Mismatch: Check that citation indices in the report text map to corresponding indices in the bibliography.
Security notes
Security Considerations - Day 294
- SSRF Prevention: All simulated web lookups enforce strict domain allowlisting.
- Citation Grounding: Synthesizer only emits citations matching verified records in the NoteStore.