Multi-Agent Graphs

What you will be able to do

• ✓Explain what a multi-agent system is, using an everyday example
• ✓Say when several agents help, and when one agent is better
• ✓Build the supervisor pattern: workers around one supervisor node
• ✓Move between agents with Command(goto=...) and edges back to the supervisor
• ✓Share work through state, and keep private data inside a subgraph
• ✓Choose between routing rules in code and an LLM supervisor - and check what the LLM says
• ✓Stop a team that never finishes: your own limit first, recursion_limit as the safety net

The idea, in plain English

Until now, one agent did the whole job. It searched, it wrote, and it checked its own work. That works for small jobs. But when a job has several different parts, one agent with one long prompt starts to mix them up.

A multi-agent system splits the job. Each agent gets one small job and a short, clear prompt: a researcher finds facts, a writer writes, a reviewer checks. In LangGraph each agent is simply a node. Nothing new is needed - you already know nodes, state and edges.

Someone must decide who works next. That is the supervisor: a node that does no work itself. It looks at the state and sends the job to the right worker. When the worker finishes, it reports back to the supervisor, and the supervisor decides again. This shape - one supervisor in the middle, workers around it - is called the supervisor pattern.

In this lesson we build a three-agent team with llama3, run it, and look at what really happened - including two bugs we made while writing it. All code was run with LangGraph 1.2.14, langchain-core 1.6.9 and llama3 on Ollama.

Worked example: A researcher, a writer and a reviewer write a short paragraph about checkpoints. The reviewer sends the first draft back.

Words you will see in this lesson

A few new words. Each one is simple - most of them are names for things you already built in Lessons 3.2 to 3.5.

An everyday example: a newspaper office

Think of a small newspaper. A reporter collects facts. A writer turns the facts into an article. A checker reads the article and says "fine" or "fix this". And an editor decides who works next - the editor does not write anything.

Nobody does everything. Each person is good at one thing, and their notes go on a shared board so the next person can continue. If the checker says "too long", the editor gives the article back to the writer. That is exactly the graph in this lesson.

Why split the work - and what it costs

Small agents have real advantages. Each prompt is short and about one thing, so the model is less confused. Each agent can have its own tools - only the researcher needs search. You can test each agent alone. You can even give each agent a different model: a big one for writing, a small fast one for checking.

But a team is slower and more expensive. Every agent is at least one more model call. We gave the same task to one agent (one prompt that does everything) and to our three-agent team. The single agent was 3 times faster - but its paragraph had 69 words, over the 60-word limit, and nobody noticed. The team was slower, but its reviewer caught the long draft and got it fixed.

So: start with one agent. Split the job only when one agent clearly struggles, or when the parts really need different prompts, tools or checks.

Three common shapes

There are three common ways to connect agents. This lesson builds the supervisor, because it is the most flexible and the easiest to understand.

The pipeline is the simplest: fixed edges, A then B then C, like a chain. Use it when the order never changes. The supervisor adds a decision in the middle, so the order can change - for example, back to the writer after a bad review. In a network, agents hand the job directly to each other with no supervisor; it is powerful but hard to follow and hard to stop.

The shared state: the team’s whiteboard

The agents never call each other. They talk only through the state. The researcher writes notes, the writer reads notes and writes draft, the reviewer reads draft and writes review. The supervisor reads everything and decides.

Two fields are only for the team’s bookkeeping. revisions counts how many times we sent the draft back - this is how we stop. feedback carries the last review to the writer. history records who worked, so we can print the path at the end.

The supervisor and Command(goto=...)

The supervisor is a normal node. Instead of returning a dict, it returns Command(goto=next_worker, update={...}). goto says which node runs next. update changes the state at the same time - here it hands the review to the writer as feedback and counts the rewrite.

The return type Command[Literal["researcher", "writer", "reviewer", "__end__"]] is not only for reading. LangGraph uses it to know where the supervisor can go, so it can draw the graph. In the drawing below, dotted lines (-.->) are the supervisor’s possible choices, and solid lines (-->) are the fixed edges from each worker back to the supervisor.

Our supervisor uses plain rules, checked from top to bottom: no notes -> researcher; no draft -> writer; no review -> reviewer; REVISE and fewer than 2 rewrites -> writer; otherwise END. Rules like these are fast, free and predictable.

Example 1 - the whole team, line by line

Here is the complete program. Read the comments - every line that matters has one. Then look at the output: it is a real run, printed exactly as it came out.

Look closely: the reviewer approved a mistake

Read the final draft again. It starts with "Here is the revised paragraph:". That line is llama3 talking to us, not part of the paragraph. A reader would see it. Our reviewer agent still said APPROVE. This is normal: a reviewer made of an LLM misses things, just like the writer does. So we added one more check in code.

The new rule caught the line - and then something new went wrong. The writer removed the line but wrote 62 words again. Why? It only received the latest feedback ("no introduction line") and forgot the earlier one ("the limit is 60"). After 2 rewrites the supervisor stopped, and the run ended with a draft that was NOT approved.

The fix: give the writer every review so far, not only the last one. With that change the team needed 2 rewrites, and the final 52-word paragraph was clean and approved.

Two more lessons from this. First, decide what happens when the team runs out of rewrites - here the run ends with review = "REVISE: ...", so your app must check it and maybe ask a human (Lesson 3.7). Second, notice that the weather note was never used: the researcher only keeps notes whose topic appears in the task. Choosing what each agent sees is part of designing the team.

Rules in code, or an LLM supervisor?

Many tutorials let an LLM be the supervisor: you describe the team in a prompt and ask "who should work next?". We tried that with llama3 on the five moments of our job. It chose right three times and wrong two times.

The two mistakes are dangerous. After "REVISE" it picked the reviewer again - the same draft would be reviewed again and again. After "APPROVE" it picked the writer - the finished job would start again. Both are loops with no exit.

Use rules when the next step can be read from the state, as in our team. Use an LLM supervisor only when choosing really needs judgment - for example, which of six specialists fits a customer’s question. Then always check its answer: lowercase it, strip punctuation, accept only names from your list, and fall back to a safe rule when the answer is not allowed.

Watch out: llama3 answered "Researcher" with a capital R. Your node is called "researcher". Without the .lower() step, that answer is a name that does not exist - and the next section shows what LangGraph does with it.

A wrong name is ignored - quietly

What happens if the supervisor sends the job to a node that does not exist - a typo, a capital letter, or a name the LLM invented? We tested it. LangGraph did not raise an error. It printed a warning, ignored the goto, and the run simply ended. Nothing was written. Nothing failed.

This is why you must check the supervisor’s answer against your list of workers. A silent stop is harder to notice than a crash.

Our first version never stopped

Here is a real mistake we made while writing Example 1. In the first version, the supervisor cleared the review before sending the draft back - and the writer looked at the review to see if this was a rewrite. The review was already empty, so the writer never saw the feedback, and the rewrite counter never went up.

The result: writer, reviewer, writer, reviewer... forever. We stopped it by hand after 131 supervisor turns and about five minutes. LangGraph did not stop it, because the default recursion_limit is 10,007 steps.

Two lessons. First, your own limit (here: at most 2 rewrites) only works if the counter really changes - count in the supervisor, which always runs. Second, always pass a recursion_limit as a safety net. With recursion_limit=12, the same buggy graph stopped after 3 LLM calls with GraphRecursionError.

An agent can be a whole graph

Sometimes one agent needs several steps of its own. The researcher might search widely, then keep only the useful notes. You can build those steps as a small graph, compile it, and add the compiled graph as one node. A graph used like this is called a subgraph.

The two graphs share data through keys with the same name. Below, task and notes exist in both, so the parent sends task in and gets notes back. The key found exists only in the researcher’s graph: it is the researcher’s private scratch paper, and the parent never sees it.

To see the inside of a subgraph while it runs, stream with subgraphs=True. Each update comes with a namespace: an empty () means the parent graph; ("researcher:...",) means inside the researcher. Lesson 3.9 explains streaming in detail.

Tip: Our first keep_relevant dropped notes whose text contained the word "weather". The weather note says "It is sunny in Hyderabad today" - no word "weather" - so it slipped through. Filter on the topic you control, not on text you hope looks a certain way.

One agent or a team? A quick test

Before you build a team, answer these questions. If most answers are "no", one agent - maybe with a review step - is simpler, faster and cheaper.

Multi-agent graphs at a glance

builder.add_node("writer", writer)

builder.add_edge("writer", "supervisor")

return Command(goto="writer", update={...})

-> Command[Literal["writer", "__end__"]]

Command(goto=END)

builder.add_node("researcher", research_graph)

graph.stream(x, stream_mode="updates", subgraphs=True)

graph.invoke(x, {"recursion_limit": 20})

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

What usually goes wrong

✗ update = {"review": ""}        # writer never sees REVISE, revisions stays 0

✓ update = {"feedback": state["review"], "review": "",
          "revisions": state.get("revisions", 0) + 1}

✗ return Command(goto=llm.invoke(prompt).content)

✓ pick = raw.split()[0].strip(".,:").lower()
if pick not in ALLOWED: pick = rule_based_next(state)

✗ update = {"feedback": state["review"], ...}

✓ update = {"feedback": state.get("feedback", []) + [state["review"]], ...}

Quick check before you move on

1. 1.

   The supervisor returns Command(goto="Reviewer") but the node is named "reviewer". What happens?

   Show answer
2. 2.

   In our test, what did llama3 choose as supervisor after the review said APPROVE?

   Show answer
3. 3.

   A subgraph has the keys task, found and notes. The parent has task and notes. What does the parent see after the subgraph runs?

   Show answer
4. 4.

   Why does every worker have an edge back to the supervisor?

   Show answer
5. 5.

   The reviewer is an LLM. How do you make it more reliable?

   Show answer

Interview questions