# Build a literature review agent

**Outcome:** a loop that takes a research question, searches at increasing depth, screens the papers,
and returns a cited summary your users can verify.

## What you need

Key with `search:write`, `papers:read`; credits for at least one `deep_review`.

## Approach

```mermaid
graph LR
  Q[Question] --> T[topic-searches: expand]
  T --> S[searches: standard]
  S --> J{enough<br/>evidence?}
  J -- no --> D[searches: deep_review]
  J -- yes --> R[render answer + citations]
  D --> R
```

Escalate depth only when the cheap pass is thin. That single decision dominates cost.

## Walkthrough

1. Expand the question into topics to catch vocabulary you would have missed
2. Run a `standard` search per topic
3. Screen: drop retracted papers, apply year and open-access filters
4. Escalate to `deep_review` only where evidence is thin
5. Render the answer with clickable citations

## Handling the hard parts

- Deep reviews take minutes — stream or webhook, never block a request thread (streaming-deep-review)
- Deduplicate papers across topic searches by `pap_` ID, not title
- Always surface `is_retracted`
- Never drop the citations to make the summary tidier — that is the product

## Cost

As written — one topic search plus three standard searches, escalating one to `deep_review` — the
walkthrough costs `4 + (3 × 5) + 60 = 79` credits. Without the escalation it is 19.

At 1,000 questions a day with a 10% escalation rate: roughly 10,500 credits a day, ~315,000 a month.
The escalation rate is the number to watch — see cost-control.

## Production checklist

Idempotency keys · webhooks over polling · cache paper metadata, not full text
(see content-licensing) · alert on `X-Credits-Remaining` · handle `402` gracefully

## Related

searches · topics · depth · cost-control