README

Project 3: Multi-Agent Research Pipeline

Given a topic, three research agents fan out in parallel (each covering a different angle), then a writer agent synthesizes everything into a structured markdown report. The whole pipeline runs asynchronously so the three research phases complete concurrently.

---

What It Does

1. You provide a research topic on the command line.
2. An orchestrator calls Claude to generate three distinct research angles for that topic.
3. Three searcher agents run in parallel via asyncio.gather() — each agent is focused on one angle and produces structured findings.
4. A writer agent synthesizes all three sets of findings into a polished markdown report.
5. The report is saved to report_<timestamp>.md and timing is printed.

---

Architecture

python orchestrator.py "future of quantum computing"
          |
          v
    Orchestrator
    (generates 3 angles via Claude)
          |
    asyncio.gather()
    .-----+-----.
    |     |     |
   S1    S2    S3      <- parallel research agents (searcher.py)
   |     |     |
   `-----+-----'
          |
     Writer Agent     <- synthesizes all findings (writer.py)
          |
          v
    report_<ts>.md

Each searcher returns:

{
  "angle": "Technical state of the art",
  "findings": "Long-form prose ...",
  "key_points": ["point 1", "point 2", "point 3"],
  "confidence": 0.85
}

---

Skills Covered

Module	Concept
06 — Multi-Agent	Specialized sub-agents with distinct roles
07 — Workflows	Orchestrator pattern, fan-out / fan-in
08 — Evaluation	Confidence scoring per agent, synthesis quality
09 — Production	Async parallel execution, wall-clock timing, file output

---

Setup

1. Install dependencies

cd projects/03-multi-agent-researcher
pip install -r requirements.txt

2. Create a .env file

ANTHROPIC_API_KEY=sk-ant-...

That is the only required variable.

---

How to Run

python orchestrator.py "future of quantum computing"
python orchestrator.py "impact of remote work on software engineering"
python orchestrator.py "climate tech investment trends 2025"

Sample output

Generating research angles for: future of quantum computing
  Angle 1: Technical state of the art and recent breakthroughs
  Angle 2: Industry adoption and commercial applications
  Angle 3: Challenges, risks, and timeline to practical quantum advantage

Running 3 research agents in parallel...
  [S1] Technical state of the art and recent breakthroughs ... done (1.8s)
  [S2] Industry adoption and commercial applications ... done (2.1s)
  [S3] Challenges, risks, and timeline to practical quantum advantage ... done (1.9s)

Writing report...
  Report complete (1.4s)

Research completed in 3.6s (3 parallel agents)
Report saved to: report_20260114_143022.md

Sample report structure

# Future of Quantum Computing: Research Report
*Generated 2026-01-14 14:30*
 
## Executive Summary
...
 
## Technical State of the Art
...
 
## Industry Adoption and Commercial Applications
...
 
## Challenges, Risks, and Timeline
...
 
## Conclusion
...
 
## Key Takeaways
- ...
- ...

---

Customizing the Research Angles

By default, the orchestrator asks Claude to generate three angles automatically. To hard-code your own:

# In orchestrator.py, replace generate_angles() with:
angles = [
    "Environmental impact",
    "Economic implications",
    "Policy and regulation",
]

---

Extension Ideas

Idea	Effort	Description
Fact-checking agent	Medium	A fourth agent that cross-references claims across the three searchers
Citation extraction	Medium	Instruct searcher agents to return source URLs; embed as footnotes
Interactive refinement	Small	After the report, drop into a REPL for follow-up questions about it
Structured output	Medium	Replace markdown with JSON schema for downstream pipeline consumption
More angles	Small	Change N_ANGLES to 5 or 7 — asyncio.gather scales automatically
Report evaluation	Medium	Add an evaluator agent that scores the report on clarity and completeness
Web search	Large	Integrate a real search API (Brave, Tavily) for factual grounding

---

Interview Demo Script

1. Run with a topic relevant to your interviewer’s company or domain.
2. Point out the timing output — three agents ran in parallel, total wall time ~= one agent time.
3. Open the generated report_*.md and walk through the structure section by section.
4. Explain the architecture: why separate roles for searcher vs writer, why asyncio, what confidence scores represent.
5. Discuss the tradeoff: more agents = more coverage but more cost; how would you decide the right number?

---

File Reference

File	Purpose
orchestrator.py	Entry point; angle generation, parallel dispatch, timing
agents/searcher.py	Research agent; returns structured findings dict
agents/writer.py	Writer agent; synthesizes findings into markdown report
requirements.txt	Python dependencies
.env	API key (never commit this)
report_*.md	Generated reports (auto-created)