research-agent

AI Research Agent (template-first v1) — a full-stack playground for orchestrated web research: LangGraph (planner → parallel retrieve per subtask → merge → synthesize), template registry, SSE streaming, SQLite-versioned artifacts, and a Next.js “run room” UI (live observatory, subtask topology, markdown report, exports). Chat/planner calls go through OpenRouter; optional LangSmith tracing and LangGraph Studio are supported.

Repository: github.com/argahv/research-agent

Features

• Backend: FastAPI, LangGraph Send fan-out over planner subtasks, bounded retrieval concurrency, DuckDuckGo-style search + page fetch, heuristic synthesis, Markdown/JSON exports, admin run listing.
• Frontend: Clay Lab–style UI, / starter → /reports/{run_id} for the full session (streaming + report + inspector), history/datasets/templates routes, React Flow topology on the run page.
• Observability: SSE phases, correlation with LangSmith via LANGSMITH_* → LANGCHAIN_* bridge, langgraph dev for local graph inspection.

Prerequisites

• Python 3.11+ recommended
• Node.js 20+ (for Next.js 15)

Quick start

Backend (from backend/)

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill OPENROUTER_API_KEY (never commit secrets)
export STUB_LLM=true   # optional: skip remote LLM entirely
uvicorn app.main:app --reload --port 8000

Frontend (from frontend/)

npm install
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 npm run dev

Default dev URL is http://localhost:3005 (per app config).

Environment

See backend/.env.example: OpenRouter keys/models, embeddings, LangSmith tracing, SQLite URL.

Never paste API keys into chat or commits — rotate any key that was exposed.

LangSmith: “Waiting for traces… No traces detected yet.”

Likely causes:

• .env not applied to LANGSMITH_* — tracing calls python-dotenv load_dotenv() on startup (override=False). Put LangSmith vars in backend/.env and run commands from backend/, or export them before starting Python.
• LANGSMITH_API_KEY empty — logs show LANGCHAIN_API_KEY=unset; add a LangSmith API key matching the LangSmith workspace you opened.
• LANGSMITH_PROJECT mismatch — open Projects → the exact project named in .env (default sample: research-agent), not Personal / Tracing demos.
• STUB_LLM=true or no OPENROUTER_API_KEY — the planner skips ChatOpenAI; traces still appear as LangGraph runs (planner, retrieve_*, …) but not as planner “Chat Model” spans. Use a real key and STUB_LLM=false to verify LLM child runs.
• No traffic yet — run POST /v1/research or POST /v1/research/stream once, then refresh the LangSmith Runs / Tracing view.

Suggested order:

1. cp backend/.env.example backend/.env and set LANGSMITH_API_KEY + (OPENROUTER_API_KEY unless you intentionally use stub).
2. Start API from backend/ so .env is found: uvicorn app.main:app --reload --port 8000.
3. Watch startup log: LangSmith tracing: on with LANGCHAIN_API_KEY=set.
4. In LangSmith, select the LANGSMITH_PROJECT workspace and inspect recent runs after one API request.

LangGraph Studio (local graph / steps UI)

backend/langgraph.json registers compiled graph research from backend/app/graph/studio_entry.py.

From backend/:

pip install -r requirements.txt   # installs langgraph-cli
langgraph dev

Pick the research graph in Studio. Use cwd = backend/ so .env aligns with Studio.

API (summary)

Method	Path	Description
POST	/v1/research	Run pipeline, persist artifact, return JSON + Markdown
POST	/v1/research/stream	SSE stages + final complete
GET	/v1/research/{run_id}	Latest report version
GET	/v1/admin/runs	Recent runs + metrics JSON
GET	/v1/templates	Template definitions

Health: GET /health.

Frontend routing

• / — query + sync/stream run; navigates to /reports/{run_id} once run_id is known (first SSE event run_started).
• /reports/{run_id} — run room: observatory (timeline, trace, eval, topology), report canvas, source inspector, exports.
• /history, /datasets, /templates — history list and stubs.
• /observatory — redirects to /#observatory (scroll target on home); full observatory UI is on /reports/{run_id} when a run exists.
• /metrics — admin-style metrics view.

Tests

cd backend && source .venv/bin/activate
STUB_LLM=true pytest

Project layout

Path	Role
backend/app/graph/pipeline.py	LangGraph DAG
backend/app/graph/streaming.py	SSE + astream
backend/app/core/tracing.py	LangSmith env bridge
backend/app/services/llm_client.py	OpenRouter ChatOpenAI
backend/app/storage/	SQLAlchemy + SQLite (data/research.db)
frontend/app/	Next.js App Router pages
frontend/contexts/ResearchRunContext.tsx	Run state + SSE
frontend/components/observatory/	Timeline, trace, topology

MCP (optional — Stitch)

Stitch can be wired in Cursor MCP. Do not commit API keys — .cursor/ is gitignored locally.

1. Copy docs/stitch-mcp.example.json to .cursor/mcp.json in this repo (or merge into your user-level MCP config).
2. Replace YOUR_GOOGLE_OR_STITCH_API_KEY with a key from Google Cloud / Stitch, then reload Cursor.

If a key was ever pushed to GitHub, revoke it in GCP and create a new one before reusing MCP.

License

Specify your license in a LICENSE file (this repo does not ship one by default).