Paper-Agent: A LangGraph Pipeline That Turns a Research Topic Into a Cited Survey

The gap Paper-Agent targets: retrieval, reading and drafting in one traceable run

A literature review is three jobs that most tools treat separately. You search several indexes, you decide which hits are worth reading, and you write something that reflects what you read. Paper-Agent's README frames the problem as a single chain: enter a research topic and receive a survey whose every stage is observable. The stated audience is researchers and students doing a first pass on an unfamiliar direction, plus anyone who has to keep notes on a long reading list. The README's comparison table is blunt about the alternative: manual searching across several sources, notes scattered across files, and drafts that get restructured halfway through. Whether the tool lives up to that is a separate question, and one the repository does not answer on its own. What is clear from the layout is the intended shape of the output. The pipeline ends at what the README calls session artefacts: survey body text plus citations, stored as local JSON, Markdown and vector files under data/. That is a different deliverable from a chat window that forgets the thread when you refresh.

Five agents, one TypedDict, and a save point when the network fails

The architecture is a LangGraph flow over a shared TypedDict state. SearchAgent takes the topic and produces keywords, sub-topics and retrieval constraints. A retrieval step fans out to three connectors, arXiv, OpenAlex and Semantic Scholar, and normalises results into a single PaperDocument type. ReadAgent then reads abstracts and judges relevance. Papers that pass go through full-text handling: download, PDF to Markdown via pypdf, chunking, extraction, and indexing into ChromaDB. AnalyseAgent works in two passes, per sub-topic first and then a global synthesis covering research status, consensus, disagreement, gaps, temporal evolution and outlook. WritingOutlineAgent produces a chapter outline with an evidence map, and WritingAgent writes section by section, retrieving more material when evidence is thin, then reviews and revises a limited number of times. The detail worth noting is the dotted edge in the README's own flowchart: when a dependency is unavailable, the flow writes a resumable checkpoint and, after you fix the configuration, continues from the reading stage rather than restarting. That is a design decision aimed at long runs, and it implies the run state is meaningful enough to persist. The README does not specify how the checkpoint is keyed or what happens if the retrieved corpus changes between the interruption and the resume.

Getting it running: uv, npm, and four keys that must line up in config/model.json

Setup assumes Python 3.12 or newer. From the project root the README gives: uv init, then uv venv --python 3.12, then uv sync, then npm run front:install. If you already have a working 3.12 virtual environment, the first two steps can be skipped. Model configuration lives in config/model.json, which the README says is not committed; config/settings.example.json is the template and config/system.yaml holds system defaults. Four things must be true before anything runs: a provider exists in providers with an api_base, an api_key or api_key_env supplies a credential, agents.default_agent is set, and embedding_profiles.default_embedding points at a working embedding provider. The provider entry takes a backend of openai, openai_compat, anthropic or anthropic_compat, and the README notes that a compatibility gateway usually needs backend, api_base and the model name filled in together. Agents are assigned tiers: SearchAgent defaults to luna_agent, AnalyseAgent to solar_agent, and ReadAgent, WritingOutlineAgent and WritingAgent to default_agent. Missing luna_agent or solar_agent falls back to default_agent; a missing default_agent breaks the configuration outright. Start the backend with uv run python main.py, which listens on 127.0.0.1:8000 with auto-reload in development, and the front end with npm run front:dev on port 5173, proxying /api and /webui to the backend. npm run front:dev:network exposes it to other devices on the LAN. config/system.yaml controls the reading node: cache directory, connect and download timeouts, maximum file size, chunking, vector store path and collection name.

Where the pipeline is most likely to disappoint you

Three constraints stand out from the material. First, the quality of the survey is bounded by abstract-level relevance decisions. ReadAgent judges papers from abstracts before anything is downloaded, so a paper whose abstract oversells its relevance enters the corpus and shapes the analysis. The evidence map produced by WritingOutlineAgent is the only stated safeguard, and the README describes it as a mapping rather than a verification step. Second, the full-text path has real dependencies: PDF download, pypdf conversion, chunking and Chroma indexing. The README's own flowchart admits this stage can fail on unavailable dependencies and only offers a checkpoint, not a fallback reader. If you are behind a paywall or a proxy that blocks bulk downloads, the pipeline degrades to abstract-only analysis, which is a materially weaker product. Third, the licence is listed as unknown in the repository metadata. For a tool that stores API keys in a local config file and writes your research notes to disk, an unverifiable licence is a genuine adoption blocker for institutional or commercial use, and nothing in the README resolves it. There are no releases retrieved either, so there is no versioned artefact to pin against; you are tracking the main branch.

How this differs from Elicit and from a plain RAG script over a PDF folder

Elicit is the obvious comparison for a researcher who wants literature review help. The difference is where the work happens. Elicit is a hosted product: you upload or search, it runs its own extraction models, and you get a table or a report in a browser with no local state to manage. Paper-Agent is self-hosted and model-agnostic. You bring the provider, you keep the SQLite database, the Chroma collection and the Markdown artefacts under data/, and you can point the agents at different models per stage. That buys you control over cost and data residency, and it costs you the operational work: a Python environment, a Node front end, a config file with credentials, and a pipeline you have to debug when a connector rate-limits. The other comparison is a hand-rolled RAG script over a folder of PDFs. That approach gives you retrieval and nothing else: no query planning, no relevance filtering, no outline, no section-level writing. Paper-Agent's value is the orchestration between those steps and the visible state at each one. If you already have a working RAG stack and only need answers over documents you chose yourself, the extra five-agent machinery is overhead.

Maintenance surface: three external APIs, one moving branch, and a config file you must not commit

The dependency list is not small. arXiv, OpenAlex and Semantic Scholar are three separate external services, each with its own availability and rate behaviour, and the README gives no retry policy beyond the connect and download timeouts in config/system.yaml. LangGraph, FastAPI, ChromaDB, pypdf, Vue 3, Vite and uv all move independently, and with no tagged releases you are pinning against commit hashes or nothing. The secrets story is at least explicit: config/model.json holds keys and is not committed, with config/settings.example.json as the template and api_key_env as the alternative to inline keys. That env-var route is the one to prefer if the repository is ever shared, since it keeps credentials out of a file that sits next to the data directory. On licence, the metadata says unknown, which means you cannot assume permission to modify, redistribute or use it commercially. Treat that as unresolved until the repository states otherwise, and do not read this as legal advice. The practical upgrade cost is the config schema: if a future version renames an agent tier or moves a key out of config/system.yaml, your local model.json will need editing by hand, and the settings page is the only documented way to test connectivity after such a change.

Editorial conclusion

Adopt Paper-Agent if you already pay for an OpenAI-compatible or Anthropic endpoint, you are comfortable running a FastAPI backend plus a Vite dev server locally, and you want the intermediate artefacts (retrieval plan, relevance notes, evidence map) rather than a finished PDF. Do not adopt it if you need a citable output you can trust without reading the sources, if you have no API budget, or if you need a licence you can verify before shipping. Before committing, run uv sync and npm run front:install, open the settings page and test connectivity for every provider named in config/model.json, then run one narrow topic end to end and read the evidence map against the retrieved abstracts.

Official sources

1. Issues
2. README
3. Tswoen/Paper-Agent on GitHub