Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Multi-Agent Research Assistant with LangGraph

Authored by Dr. Tiziana Ligorio for AI Agents - CSCI 395.32 taught at Hunter College of The City University of New York

In this tutorial we build a research assistant that answers comparison questions from the scientific literature on arXiv: questions that ask how several methods, techniques, or approaches compare. Each approach can be researched independently, which is one situation when splitting work across agents pays off. A single agent would run all the searches one after another, and every abstract it read would pile up in one context. Instead, our system:

  1. Plans: a lead step splits the question into one brief per approach.

  2. Researches in parallel: one research subagent per approach searches arXiv in its own context, at the same time as the others, and returns one row of a comparison table.

  3. Checks: plain code removes any citation that did not come from that researcher’s own searches, such as a paper the model made up or remembered from training. If an approach is left with no papers, its researcher tries again.

  4. Writes: one step reads all the rows and writes a short summary under the table.

We build the system with LangGraph (the focus of this tutorial), a framework for connecting agents and functions into a graph that shares state. LangGraph works together with LangChain, which we used in the ReAct tutorial. LangGraph runs the graph: its state, its steps, and which node runs next. LangChain provides the pieces that go inside the nodes: models, tools, structured output, middleware, and the ready-made ReAct agent create_agent. In fact, create_agent returns a small LangGraph graph, so the ReAct agents we built were already running on LangGraph. Here we write our own graph, and some of its nodes are create_agent agents.

What you will learn

  1. When a task justifies more than one agent, and how to measure what the split costs against a single-agent baseline.

  2. How to build a LangGraph graph: shared state, reducers, nodes, edges, conditional edges, and parallel branches with Send.

  3. How to use agents as nodes: research subagents built with create_agent, each with its own brief, tool, and isolated context.

  4. How to read the trace of a parallel run, and how to compare the system with a single agent.

1. Installs and Imports

%%capture hides the pip install output to keep the notebook clean. If you are running locally, skip this cell: uv sync installs the same packages from pyproject.toml (see SETUP.md).

2. Setup your API Key

Step 1 — Get an OpenRouter API key

OpenRouter provides access to models from different vendors through one API. This is the only key the tutorial needs.

  1. Go to https://openrouter.ai

  2. Sign in (or create an account if you don’t have one)

  3. Once logged in, navigate to https://openrouter.ai/settings/keys

  4. Click Create Key

  5. Give the key a name, e.g. colab-multiagent-langgraph

  6. Copy the key immediately (you won’t be able to see it again)

Important: Treat this key like a password. Do not share it, paste it into notebooks, or commit it to GitHub.

Step 2 — Store your API key

If running in Google Colab

  1. On the left sidebar, click 🔑 Secrets.

  2. Add a new secret named OPENROUTER_API_KEY with your key as the value.

  3. Toggle the switch to give the notebook access to the secret.

If running locally

Create a .env file in the project folder containing:

OPENROUTER_API_KEY=your_openrouter_key_here

Make sure .env is listed in .gitignore.

Load the API Key

In Colab:

Uncomment and run the cell below if you’re using Google Colab.

Locally:

Run the cell below if you’re running locally with a .env file.

Environment loaded from .env file
OPENROUTER_API_KEY is available.

Choose the model

We use openai/gpt-4.1-mini through OpenRouter: a small, inexpensive model that is reliable at tool calling and structured output. Every part of the system uses the same model, so the differences between agents come from their prompts, tools, and context, not from the model.

We set the temperature to 0 so the model makes nearly the same choices for the same input. That makes a run easier to debug and the baseline comparison fairer. (Outputs can still vary slightly from run to run.)

LangChain’s ChatOpenAI wrapper talks to any OpenAI-compatible API, so we point it at OpenRouter.

Model: openai/gpt-4.1-mini (temperature 0)

3. The Demo Question and the Search Tool

We demonstrate the system on one comparison question with five parts:

The arXiv search tool

Every agent in this tutorial finds papers through the same tool, search_arxiv. It queries arXiv, a free archive of scientific papers, through the arxiv Python package.

  • One shared client. arXiv asks clients to wait about 3 seconds between requests, and the client enforces that wait. If a request fails, the client retries it once.

  • A lock. Later, several agents will search at the same time. Without the lock their requests would reach arXiv at the same moment, and arXiv asks for one request at a time. The lock makes searches take turns. Agents that run in parallel still share their tools’ limits.

  • A cache. Every result is saved in arxiv_cache.json. A search that has run before returns its saved result instantly, without contacting arXiv. Reruns are fast, and the notebook keeps working when arXiv is limiting requests. If the file is missing, the cache starts empty.

  • Small results. The tool returns at most 5 compact records: title, year, URL, and the first 600 characters of the abstract. Every result a tool returns ends up in an agent’s context, so small results keep every context small.

  • Readable errors. If arXiv fails, the tool returns a short message with the reason (for example HTTP 429 when arXiv is limiting requests), which the model can read and react to, instead of crashing the run.

Abstracts are text written by people outside our system. The agents read them as data, but nothing guarantees they contain only what we expect.

33 searches in the cache

Test the tool directly before giving it to an agent:

2026 Transit Photometry and Ephemeris Refinement of WASP-12 b Using TESS Data
2023 Enabling Exoplanet Demographics Studies with Standardized Exoplanet Survey Meta-Data
2011 The CoRoT Exoplanet program : status & results
2015 Characterization of transiting exoplanets by way of differential photometry
2022 Photometry and transit modelling of exoplanet WASP-140b

4. A Single-Agent Baseline

Before building several agents, we build one. It gets the same model, the same tool, the same instructions, and the same answer format the multi-agent system will use. The baseline is what the multi-agent system has to beat: if one agent does the job as well, for less, we should keep one agent.

The answer format

The answer is a comparison table with one row per approach. Each row says how the approach works, its main strength, and its main limitation, each in one sentence, and cites up to three supporting papers from the searches.

In code, we describe the answer as Pydantic models (Recall, these are Python classes that declare named, typed fields: Pydantic checks that data has those fields and types, and LangChain uses them to tell the model the exact shape of its answer):

  • Comparison is the whole table: a list of rows.

  • ApproachFinding is one row: the approach, the three one-sentence fields, and its papers.

  • Paper is one citation: the paper’s title, year, and URL.

The Field descriptions are instructions the model reads. The multi-agent system reuses these models, and adds a short summary under the table (Section 6).

show_table displays the rows as a table. Each paper appears as a link labeled with its year, so the table stays short. Before using it, we test it on two sample rows.

Loading...

The baseline agent

The agent is a ReAct agent built with create_agent, as in the ReAct tutorial. create_agent builds it as a small LangGraph graph with two nodes. The model node calls the LLM. The tools node runs the tool calls the model asked for. The two nodes call each other in a loop until the model answers without asking for a tool. Section 5 explains LangGraph in detail; for this section, that loop is all you need. response_format=Comparison makes the agent return the table as a Comparison object.

Its instructions ask for depth: for each approach, three searches with different queries, then the three papers most specifically about that approach. ToolCallLimitMiddleware caps it at 15 searches: three for each of up to five approaches. The multi-agent system gets exactly the same instructions and budget, so the comparison is fair.

The prompt names the content; Comparison sets the format. The prompt’s last lines only say what each row should contain: how the approach works, its strength, its limitation, and its papers. They don’t describe the format: no JSON, no field names, no “return a list of…”.

The format comes from response_format=Comparison. create_agent sends the Comparison schema to the model. The schema covers its fields, their types, and their Field descriptions. When the agent finishes, Pydantic checks the answer against that schema. The answer must be a list of ApproachFinding rows. Each row needs its four text fields and a list of papers, and each paper needs a title, a whole-number year, and a URL. An answer that doesn’t fit never comes back as a Comparison: LangChain either asks the model to fix it or raises an error. The format is enforced in code, outside the prompt. We never describe it in words, and we never parse the model’s text ourselves. The answer arrives as a Comparison object in baseline_result["structured_response"].

Pydantic checks shape and types, not content. “One sentence” and “3 papers” are instructions the model reads, in the prompt and in the Field descriptions. Nothing in code checks them.

Run the baseline on the demo question and time it. (A new search waits about 3 seconds for arXiv; a search already in the cache returns instantly.)

LangGraph runs the graph in steps: here, each run of the model node or the tools node is one step. By default it stops a run after 25 steps, a guard against agents that loop forever. Each search round takes 2 steps (model, then tools), so 15 searches can need more than 30 steps. recursion_limit raises the limit to 60. The search budget itself still comes from ToolCallLimitMiddleware. Middleware limits what the agent does (model calls and tool calls); recursion_limit is LangGraph’s own limit on steps, and raising one does not raise the other. In the ReAct tutorial the agent made at most 8 model calls, about 16 steps, so the default limit was never reached.

Loading...

What did the baseline do?

We write three small helpers to read an agent’s messages:

  • search_queries lists the queries the agent searched for.

  • found_urls lists the URLs its searches returned.

  • usage_stats counts model calls, searches, distinct papers found, and tokens. It also reports the largest context: the most input tokens any single model call had to read.

     model calls: 2
        searches: 5
    papers found: 21
 largest context: 4393
    total tokens: 5949
         seconds: 9.5

Queries:
   transit method exoplanets
   radial velocity method exoplanets
   direct imaging exoplanets
   gravitational microlensing exoplanets
   astrometry exoplanets

Look at the largest context. Every search result stays in the agent’s conversation, so its last model calls read every abstract found so far, for all five approaches at once: transit papers are still in context while it writes the astrometry row. Also check whether it really ran three searches per approach. We keep baseline_stats and baseline_answer and compare them with the multi-agent system in Section 9.

5. LangGraph: State, Nodes, and Edges

LangGraph describes a system as a graph:

  • the state is a shared data structure that every node can read;

  • a reducer is a function attached to a state field that says how to combine updates. A plain field is replaced by each update. A field with a reducer combines the old value and the update, for example by adding them. We attach one with Annotated[type, reducer].

  • nodes are plain Python functions: each reads the state and returns the fields it wants to update;

  • edges say which node runs next. A conditional edge calls a function that decides, at run time, what runs next.

As we saw in Section 4, the baseline agent is already a LangGraph graph: create_agent built a small graph with a model node and a tools node that call each other in a loop.

CompiledStateGraph

How LangGraph runs a graph

LangGraph runs a graph in steps. In each step it runs every node scheduled for that step, merges their updates into the state, and then follows the edges out of those nodes to decide what runs in the next step. Nodes in the same step run in parallel. The run ends when an edge leads to END.

Before building the research system, here is a toy graph with no model and no tools. Given a list of numbers, it squares each one in parallel and adds up the squares: for [1, 2, 3] it computes 1 + 4 + 9 = 14.

The shared state of the toy graph

The toy graph’s shared state, and which node reads (white arrows) or writes (teal arrows) each field. fan_out is not a node: LangGraph calls it after split to create one Send per number.

What we write (plain Python):

  • ToyState, the state: two fields. numbers is a plain field holding the input list. total has a reducer, operator.add, so the squares are added together instead of replacing each other.

  • split, a node, and the first step. It receives the state, prints the list, and returns no update. It does no work itself; it only gives the graph a point to fan out from. In the research system its counterpart, plan, does real work: it writes the briefs.

  • fan_out, a routing function. It is not a node: it doesn’t run as a step and doesn’t update the state. LangGraph calls it right after split finishes, to decide what runs next. It returns one Send per number.

  • square, a node. Each run receives one number, {"n": ...}, and returns its square as an update to total.

What LangGraph provides:

  • StateGraph(ToyState) creates a graph builder. add_node registers each of our node functions under a name.

  • START and END mark where a run begins and ends. add_edge(START, "split") means the run begins with split. add_edge("square", END) means the run ends after square.

  • add_conditional_edges("split", fan_out, ["square"]) means: after split, call fan_out to decide what runs next. The third argument lists the nodes it may lead to.

  • Send(node, arg), a class from langgraph.types, means “run this node with this input”. fan_out returns [Send("square", {"n": 1}), Send("square", {"n": 2}), Send("square", {"n": 3})], so LangGraph runs square three times in the next step, in parallel.

  • compile() checks the graph and turns it into something you can run with invoke.

A node started by Send receives the Send input as its argument instead of the state: square receives {"n": 2}, not the whole ToyState. Its return value still updates the shared state. A routing function can return either the name of a node, to go to that node, or a list of Send objects, to run a node several times with different inputs.

Each node prints the step it runs in. It reads the step from config, LangGraph’s dict with information about the current run, which LangGraph passes to any node that has a parameter named config.

step 1: split   [1, 2, 3]
step 2: square  {'n': 1}
step 2: square  {'n': 2}
step 2: square  {'n': 3}
{'numbers': [1, 2, 3], 'total': 14}

Read the output:

  • split ran in step 1. The three runs of square all ran in step 2, in parallel, each with its own input from Send.

  • Each run returned {"total": n * n}. The reducer added the three updates to the starting 0: 1 + 4 + 9 = 14. Without the reducer, LangGraph would stop with an error, because three nodes updated the same plain field in the same step.

  • The graph ended after step 2, because the edge out of square leads to END.

The research system works the same way: plan plays the role of split, research plays the role of square with a research agent instead of arithmetic, and the reducers merge the researchers’ results.

Our multi-agent system is a bigger graph whose nodes call agents like that one:

START → plan → research ×5 (in parallel) → check → write → END
                    ↑                        │
                    └── retry once ──────────┘  (if an approach is left with no papers)
  1. plan splits the question into one brief per approach.

  2. research runs once per brief, all at the same time. Each run is a subagent with its own context: it sees only its own brief and its own search results.

  3. check is plain code. It removes any citation that did not come from that researcher’s own searches. If an approach is left with no papers, its researcher tries again, once.

  4. write reads all the rows and writes a short summary under the table.

The plan’s output: briefs

Delegating means writing a brief: the researcher will know nothing except what the brief tells it. Our brief names the approach and says, in one sentence, what to find out about it.

The shared state

ResearchState lists every field in the state. When a node returns {"field": value}, LangGraph merges that update into the state:

  • For a plain field, the new value replaces the old one.

  • For a field declared with Annotated[type, reducer], LangGraph combines the old and new values with the reducer.

Reducers matter because of parallelism. Five researchers finish in the same step, and each returns its own findings. With no reducer, LangGraph would not know which of the five updates to keep and would stop with an error. Our reducers:

  • operator.or_ merges dictionaries. findings and sources are keyed by approach, so each researcher adds its own entry, and a retry replaces only its own approach.

  • operator.add appends lists and adds numbers. Every node adds one record to trace, and removed counts the citations removed over the whole run.

The shared state of the research system

The shared state, and which node reads (white arrows) or writes (teal arrows) each field. The picture is simplified: write also reads question and briefs; after_check, the edge after check, reads retry and checks to decide whether to send an approach back (the dashed arrow); and removed and trace are left out, although check adds to removed and every node adds a record to trace. The researchers do not read the state directly: they receive the question and their brief as a task through Send.

6. The Nodes

Each node is a function (state, config) -> dict. Besides its real work, every node adds one trace record to the state: its name, the approach it worked on, when it started and ended, and what it used. config carries LangGraph’s run information, including the step number. Nodes that run in parallel share a step. When we call a node by hand to test it, there is no step, so the record shows -.

Node 1: plan

The lead step is one model call with structured output: with_structured_output(Plan) makes the model return a Plan object. With include_raw=True we also get the raw model message, which carries the token counts for the trace.

Test the node by hand, with a state that holds only the question:

plan: 5 briefs: transit, radial velocity, direct imaging, gravitational microlensing, astrometry
- transit: Determine how the transit method detects exoplanets by measuring the dip in a star's brightness as a planet passes in front of it.
- radial velocity: Understand how the radial velocity method detects exoplanets by observing the star's spectrum shifts caused by gravitational tugs from orbiting planets.
- direct imaging: Explore how direct imaging captures actual pictures of exoplanets by blocking out starlight to reveal faint planets nearby.
- gravitational microlensing: Investigate how gravitational microlensing detects exoplanets through the bending and magnification of light from a background star caused by a planet's gravity.
- astrometry: Examine how astrometry detects exoplanets by precisely measuring the star's position changes due to the gravitational influence of orbiting planets.

Node 2: research (the subagent)

The researcher is a ReAct agent built with create_agent, like the baseline, with the same tool and the same depth instructions, but for one approach: three searches, then one row. ToolCallLimitMiddleware caps it at three searches and response_format=ApproachFinding makes it return one row.

We define the agent once. Every call to research starts it with a fresh conversation that contains only the brief, so each researcher has its own isolated context: it never sees the other approaches’ searches.

The node receives a task rather than the whole state: a dict with the question, one brief, and, on a retry, a note. The routing functions in Section 7 create the tasks with Send. It returns three updates: its row, the URLs its searches returned (for check), and its trace record.

Test one researcher by hand on the first brief. This is everything the researcher saw from the outside:

Question: How do astronomers detect exoplanets? Compare the transit, radial velocity, direct imaging, gravitational microlensing, and astrometry methods.
Your approach: transit
What to find out: Determine how the transit method detects exoplanets by measuring the dip in a star's brightness as a planet passes in front of it.
research [transit]: 3 searches, 3 papers cited
Loading...
Queries: ['transit method exoplanets', 'transit photometry exoplanet detection', 'transit method challenges exoplanets']

Node 3: check

check follows a few practices for building reliable agent systems:

  • Verify model output with code wherever you can.

  • Ground claims in tool results.

  • Check at the handoff, before results are combined.

  • Fail safe, and retry with a reason, a bounded number of times.

  • Keep generating and checking separate.

It verifies where each citation came from, not whether the paper is relevant to the approach or whether the row’s claims are correct.

For each approach, it keeps only the cited papers that appeared in that researcher’s own search results, comparing arXiv ids (ignoring the version suffix, so 1105.1887v1 and 1105.1887 match). It removes the rest (fail safe) and lists the approaches left with no papers in `retry, updating checks so that each approach can be retried at most once.

A model can cite a paper it never found, especially when a search fails. A rule in the prompt asks it not to; the check makes sure.

Node 4: write

write is the only step that needs every approach at once, so it runs once, after all the research. Reading parallelizes well; writing a combined answer does not. It reads the rows (without the papers) and writes a short summary of at most three sentences.

7. Build the Graph

Parallel branches with Send

The research system uses Send exactly as the toy graph did.

fan_out is the conditional edge after plan:

  • It returns one Send("research", task) per brief, where task is {"question": ..., "brief": ...}.

  • LangGraph runs research once per brief, all in the same step, in parallel. Each run receives its own task, not the whole state; that is why research(task, config) reads task["brief"].

  • The number of researchers comes from the plan at run time: five briefs, five runs.

  • A run’s result reaches the state only through what research returns; the reducers on findings, sources, and trace merge the five updates.

  • The next node, check, runs only when every research run has finished.

after_check is the conditional edge after check, and it shows both things such a function can return:

  • if some approaches were left with no papers and we have not retried yet, a list of Send objects, one per approach to retry, each task with a note for the researcher;

  • otherwise the name of a node, "write".

Test check and after_check together, without any model. We take the row from the researcher test, then add a second row whose only paper was never found by a search:

check: removed 1 citations not found in the searches; retry: Made-up method
Next: ['research [Made-up method]']

check removed the made-up citation, and after_check sent only the made-up approach back to research. The real row passed untouched.

Now assemble the graph: add the nodes, then the edges. add_conditional_edges takes the node, the function that decides, and the nodes it may lead to.

LangGraph can draw the compiled graph. Dashed arrows are conditional edges. (Drawing the picture uses an online service; without internet access, the cell prints the graph’s Mermaid text instead.)

<IPython.core.display.Image object>

8. Run the System

The input is a state that holds only the question. Each node prints one line as it finishes.

plan: 5 briefs: transit, radial velocity, direct imaging, gravitational microlensing, astrometry
research [transit]: 3 searches, 3 papers cited
research [direct imaging]: 3 searches, 3 papers cited
research [radial velocity]: 3 searches, 3 papers cited
research [astrometry]: 3 searches, 3 papers cited
research [gravitational microlensing]: 3 searches, 3 papers cited
check: removed 0 citations not found in the searches
write: bottom line written
Loading...
Loading...

The trace

show_trace turns the trace records into a timeline. Times are seconds since the run started.

Loading...

Read the trace from top to bottom:

  • All the research rows share one step number and their times overlap: LangGraph ran them in parallel.

  • check starts only after the slowest researcher ends. In a parallel step, the slowest branch sets the pace.

  • The researchers end at different times because they share one tool: their arXiv searches took turns through the lock. On a rerun, with every search in the cache, they end close together.

  • Each researcher’s largest context holds only its own approach’s searches. Compare it with the baseline’s in Section 9.

  • If check sent an approach back, a second research row for it appears with a later step number.

What each researcher searched for:

transit: ['transit exoplanet detection', 'transit method exoplanet challenges', 'transit photometry exoplanets']
radial velocity: ['radial velocity exoplanets', 'Doppler shifts exoplanets', 'radial velocity method sensitivity limitations']
direct imaging: ['direct imaging exoplanets', 'coronagraph adaptive optics exoplanets', 'direct imaging exoplanets challenges']
gravitational microlensing: ['gravitational microlensing exoplanets', 'gravitational microlensing light bending', 'gravitational microlensing limitations exoplanets']
astrometry: ['astrometry exoplanets', 'astrometry precision exoplanet detection', 'astrometry challenges exoplanets']

9. One Agent or Several?

The same question, the same model, tool, instructions, and search budget. cited_in_several_rows counts papers that appear in more than one row: a paper cited for two different methods is usually a general exoplanet paper rather than one about a specific method. For the baseline, citations not from a search are counted against all of its searches; in the multi-agent system, check already removed them.

Loading...

Which papers were cited in more than one row?

One agent: "Keplerian Orbits and Dynamics of Exoplanets" is cited for Transit method, Radial velocity method, Astrometry
Multi-agent: no repeats

What to look for:

  • Depth. Both systems got the same instruction: three searches per approach. Check whether the single agent followed it. With five approaches on its to-do list, a single agent tends to cut corners. Each researcher has one approach and does the whole job.

  • Specific papers. A paper cited in more than one row is usually a general exoplanet paper, not one about that method. A researcher that searches only for its own method finds papers about that method.

  • Focus. Each researcher’s largest context holds only its own approach, even though it searched more. The single agent’s context mixes all five approaches; had it run all 15 searches, it would hold three times as many abstracts.

  • Cost. The multi-agent system spends more tokens: more searches, five system prompts, a plan, and a short summary. That is the price of the extra depth. Lecture 9’s numbers make the same point at a larger scale: compared with a chat, an agent uses about 4× the tokens, and a multi-agent system about 15×.

  • Time. On a first run, both systems mostly wait for arXiv: the lock makes searches take turns, and the multi-agent system runs more of them. Run Sections 4 and 8 again: every search now comes from the cache, so the seconds show the model calls alone, and in the trace the five researchers take about as long as one.

The split pays off when the parts are independent and each needs real depth. For a question with one part, or with parts that need each other’s results, one agent is the better choice.

10. Reflect and Your Turn

  1. A multi-agent system is a graph. LangGraph describes it with a shared state, nodes that return updates, and edges, some of them conditional. Agents built with create_agent are graphs too, so they can run inside a node.

  2. Reducers make parallel updates safe. Five researchers write findings in the same step; operator.or_ merges their entries by approach.

  3. Send creates parallel branches at run time. The number of researchers comes from the plan, not from the code.

  4. Each subagent has an isolated context. A researcher sees only its brief and its own results, which keeps its context small and focused. The brief is all it knows, so the brief has to be good.

  5. Plain code checks the agents’ work. check needs no model, and it can send work back through a conditional edge.

  6. Splitting has a cost. More tokens, more moving parts, and shared limits (the lock). Measure against a single agent before choosing.

Your turn

  • Change the question. Try a comparison with two approaches, and a question with only one. How many briefs does plan write? Run the baseline too: at what size does the split stop paying off?

  • Remove a reducer. Change findings to a plain dict[str, ApproachFinding] and run the graph. Read the error: what is LangGraph telling you?

  • Make check stricter. Also send back any approach left with fewer than two papers. Watch the retry in the trace.

  • Add a second source. Write a tool for another paper database (for example Semantic Scholar or OpenAlex) and give it to the researchers. How should duplicates across sources be handled?

  • Pause after the plan. Compile the graph with a checkpointer and interrupt_before=["research"], so a person can read and edit the briefs before the researchers start. See the LangGraph documentation on human-in-the-loop.