agentic-research-assistant

Production-ready multi-agent research system with LangGraph orchestration, real-time SSE traces, guardrails, and operational monitoring.

Implemented Scope

1. Searcher, Summarizer, and Critic agents with structured trace events.
2. LangGraph orchestration with single-run streaming and synchronous execution paths.
3. FastAPI endpoints for health, SSE streaming, synchronous research run, and metrics.
4. Input guardrails, request IDs, rate limiting, CORS allowlist, and security headers.
5. React frontend for streaming trace cards and final source-grounded answer rendering.
6. Integration and unit tests for API and agent behavior.
7. Execution budget modes with small, medium, and large source budgets.
8. Deterministic evaluation harness for quality and citation-faithfulness checks.
9. Governance baseline: contributing, security, architecture, API, deployment, testing, changelog, prompt guide, templates, ownership.

Repository Layout

1. api/main.py - API service, SSE stream endpoint, and operational controls.
2. agents/ - Searcher, Summarizer, Critic, and LangGraph workflow.
3. frontend/ - React research console and trace visualization UI.
4. prompts/ - role instructions for each agent.
5. tests/ - backend API and agent unit/integration coverage.
6. docs/ - architecture, API, deployment, testing, and prompt governance.

Quick Start

# backend
pip install -r requirements.txt
uvicorn api.main:app --reload --port 8002

# frontend
cd frontend
npm ci
npm run dev -- --host 0.0.0.0 --port 4175

Then open:

1. API health: http://127.0.0.1:8002/health
2. Frontend console: http://127.0.0.1:4175

Run Backend

pip install -r requirements.txt
uvicorn api.main:app --reload --port 8002

Optional backend security env vars:

RESEARCH_API_KEY=
RATE_LIMIT_PER_MINUTE=90
APP_ENV=development
CORS_ORIGINS=http://127.0.0.1:4175,http://localhost:4175
ALLOWED_HOSTS=127.0.0.1,localhost,api,frontend
DEFAULT_EXECUTION_TIER=medium

Execution budget tiers:

1. small: source budget cap 3
2. medium: source budget cap 5
3. large: source budget cap 8

Run Frontend

cd frontend
npm ci
npm run dev -- --host 0.0.0.0 --port 4175

Run Production Stack

cp .env.example .env
# Edit .env and set APP_ENV=production plus RESEARCH_API_KEY before first deploy
docker compose -f docker-compose.prod.yml up -d --build

Production endpoints:

1. Frontend: http://127.0.0.1:4175
2. API via frontend proxy: http://127.0.0.1:4175/api/health

Optional monitoring profile:

docker compose -f docker-compose.prod.yml --profile monitoring up -d

Visual Evidence

Agent trace demo:

Architecture overview:

Trace console preview:

API Endpoints

1. GET /health
2. GET /research (SSE stream, protected when API key is configured)
3. POST /research/run (sync execution, protected when API key is configured)
4. GET /metrics

Week 4 Reliability Additions

1. Deterministic eval scenarios in eval/scenarios/deterministic_eval.json.
2. Evaluation harness in tools/evaluate_research.py.
3. Tool access boundary guidance in docs/GUARDRAILS.md.
4. Trace walkthrough in docs/TRACE_WALKTHROUGH.md.
5. Sequence diagram in docs/SEQUENCE_DIAGRAM.md.

Run deterministic evaluation:

python tools/evaluate_research.py --scenario-file eval/scenarios/deterministic_eval.json --output-json eval/results/deterministic_eval_results.json

Week 11 Measured Outcomes

1. Before and after outcomes are documented in docs/WEEK11_MEASURED_OUTCOMES.md.
2. Reliability evidence includes checklist retention, docs growth, workflow expansion, and test-surface growth.
3. Cost-aware execution evidence includes source-budget tier charting (small, medium, large).

Validation Commands

# backend tests
pytest -q

# frontend production build
cd frontend && npm run build

Testing

1. Run backend tests: pytest -q.
2. Run frontend production build validation: cd frontend && npm run build.
3. Run extended release checks in the Production Verification section before semantic tags.

Production Verification

Run before creating release tags:

# backend
python -m pip install --upgrade pip
pip install -r requirements.txt
python -m compileall -q api agents tests tools
python -m pip check
pytest -q --maxfail=1
pip-audit -r requirements.txt --progress-spinner off

# frontend
cd frontend
npm ci
npm run build
npm audit --omit=dev --audit-level=high

# container images
docker build -f Dockerfile -t agentic-research-assistant-api:local .
docker build -f frontend/Dockerfile --build-arg VITE_API_URL=/api -t agentic-research-assistant-frontend:local frontend

Expected outcome:

1. Backend compile, tests, and dependency checks pass.
2. Frontend production build completes successfully.
3. Dependency audits show no high-severity blockers.

Local Service Endpoints

1. API: http://127.0.0.1:8002
2. Frontend: http://127.0.0.1:4175

Production Documents

1. docs/ARCHITECTURE.md
2. docs/API.md
3. docs/DEPLOYMENT.md
4. docs/TESTING.md
5. docs/PROMPT_GUIDE.md
6. docs/GUARDRAILS.md
7. docs/TRACE_WALKTHROUGH.md
8. docs/SEQUENCE_DIAGRAM.md
9. .claude/CLAUDE.md
10. .github/workflows/release.yml

Deployment Artifacts

1. Dockerfile (backend production image)
2. frontend/Dockerfile (frontend production image)
3. frontend/nginx/default.conf (SPA serving, API proxy, SSE-safe settings)
4. docker-compose.prod.yml (production stack with health checks)

Limitations

1. Current orchestration executes a fixed three-agent sequence.
2. Live external search quality depends on provider API availability and quotas.

Roadmap

1. Add retrieval provider abstraction with ranked source fusion.
2. Add policy-driven redaction for sensitive snippets in traces.
3. Add latency-budget controls and adaptive source count selection.