Research systems: supervisor financial research, summarisation, full research system

What you'll build

• A one-shot planner that splits a topic into a fixed number of search queries and runs one search agent per query, in parallel.
• An analyst and a report writer that work from one shared, source-tagged findings list.
• A quality checker that scores each draft by its weakest criterion, with a draft cap enforced in code.
• Two smaller teams to compare against: a supervisor over a market researcher and a coder, and a typed router over web, RAG and plain-model specialists.

Lesson 3 of T11.3 merged parallel hotel agents into one reply. The research builds keep that fan-out and fan-in and change the question: who decides which agent works next, and when. The full pipeline is the mandatory build; the supervisor and the typed router are the optional builds it is compared against.

Outside a notebook, a research team fails in ways a single agent does not. Larkspur's support engineers want an answer that cites the handbook and the web, and three things go wrong in production: a search returns nothing useful, a forum post contradicts the handbook, or a provider call fails. The module's lab brief asks for exactly this team, built on the Larkspur handbook and tested on those three cases. This page covers the designs it draws on.

The three builds answer the "who decides next" question differently, and that choice sets how many model calls a request costs and what can go wrong:

Table 1: The three controllers compared, with the caps each build sets in code.

The supervisor is the most flexible and the hardest to bound. Its build proves the turn cap with a stub supervisor that never finishes. Its researcher also returns a validated market-data object, numbers only, and the coder sees just the user's request and that object. No web text reaches the agent that runs code.

The typed router is the fix for lesson 1 of T11.3's mention routing: the choice is a field, and there is no reply text to search. Its RAG specialist answers only from chunks whose relevance score reaches 0.2, out of the top 3. When nothing clears that floor, it skips the model call and says so.

The planner never sees a result, which is what separates it from a supervisor. It cannot adapt, but its cost is known before the first search runs. The choice comes down to two questions:

Figure 1: Choosing a controller. Adaptivity costs boundedness, so take the supervisor only when the next step really depends on what came back.

The planner wins for a broad topic with known angles. The rest of the page follows it.

The full pipeline has five roles. A planner splits the topic into search queries, search agents run them in parallel and append to one shared findings list, an analyst and a writer turn the findings into a report, and a quality checker sends the report back for revision until it passes or the cap is reached:

Figure 2: The research pipeline. The loop back to the writer ends on approval or at the draft cap, whichever comes first.

The settings live in one place, and code enforces each of them:

Table 2: The pipeline's settings and the code that enforces each one.

Table 3: The design details that make the loop safe, and what each reuses.

The four required sections are Executive Summary, Key Findings, Analysis and Recommendations. The reviewer is never asked to be lenient on a later pass; the cap does that job. Call the failure it prevents a runaway revision loop: a strict reviewer and a writer that cannot satisfy it, revising until the recursion limit stops the run with no report.

Proving the loop with stubs

The build proves the wiring before it spends a token. The graph factory accepts replacement nodes, and stub nodes plan four queries with two findings each. We ran the stub runs in the scratchpad:

Table 4: Stub runs of the research graph with no model calls.

All eight findings survive the parallel writes, every query contributes, the never-satisfied reviewer stops at 2 drafts, and the satisfied one stops at 1. The real run is then checked against its streamed updates: one search agent per planned query, every query represented in the findings, and as many drafts as reviews, never more than 2.

A Larkspur support engineer asks the team about the refund window for annual plans, and a community forum post quotes an older window than the handbook. Here is the order of calls (Illustrative, since a live run's searches change):

Table 5: One research request through the pipeline (illustrative).

The writer can only say which source is the policy because the findings kept their sources through the parallel fan-in.

Table 6: Choices from the three builds and the risk each one addresses.

The cap hides quality problems from the user: a run stopped at draft 2 still ships a report. Log whether each run ended approved or capped, and treat a rising share of capped runs as a sign that the writer or the sources got worse. URL verification only proves the search returned the link; it does not prove the page says what the finding claims. The supervisor build's market data comes from OpenBB and Tavily, and the research builds need an OpenAI key and web search access, so none of them run offline beyond their stub checks.

The code for this lesson is in these notebooks. Colab runs one in your browser: install the packages its first cell imports and set the API keys it reads. To run every notebook as written, clone the repository and use its uv environment.

• A supervisor sees results and can adapt but is hardest to bound. A typed router picks one specialist per question, and a one-shot planner fixes its queries up front, which makes its cost known before the first search.
• Tie every finding to its source and mark whether the URL is one the search returned. When a forum post and the handbook disagree, the writer can then cite both and say which is the policy.
• End a quality loop in code. Score each draft by its weakest criterion, check the required sections in code, stop at 2 drafts whatever the reviewer says, and prove the wiring with stub nodes first.