Build a Multi-Agent Research Team · 25 min · Python · LangGraph · Pydantic

Shared State Design

When two parallel agents write to the same state field without a reducer, LangGraph doesn't pick a winner -- it raises InvalidUpdateError and your graph run dies before a report is ever produced.

Hiring signal: State reducer conflicts are the single most-cited real bug in production LangGraph systems -- understanding them before you hit one in your own research team is exactly the kind of hard-won lesson this course front-loads instead of letting you discover the hard way.

What you will learn

Design a TypedDict state schema covering every field all 5 agents need
Explain why parallel writes to the same field need an explicit reducer
Use Annotated types to specify how a field merges (append vs. overwrite)

Introduction

This is the lesson the SPEC's own hotspot list puts first: get this wrong and your graph crashes the moment 2 of your 3 parallel specialists finish in the same step — InvalidUpdateError: Can receive only one value per step. Older LangGraph releases failed silently here (last write wins, no error at all); current LangGraph (1.x) fails loudly instead. Loud is better than silent, but "my research team crashes every time it runs" isn't a fix either — you still need to tell LangGraph how to merge the field.

The naive state schema, and why it breaks under parallelism

from typing_extensions import TypedDict

class ResearchState(TypedDict):
    research_question: str
    sub_tasks: list
    web_findings: str
    technical_findings: str
    market_findings: str
    final_report: str
    citations: list        # looks reasonable... until 3 agents each append to it

Notice web_findings, technical_findings, and market_findings are separate fields -- each written by exactly ONE specialist, so no conflict there. citations, though, is different: all 3 specialists append their own sources to that SAME shared list in the SAME parallel step (Lesson 5's fan-out). A plain-typed field has no defined merge behavior for 2 simultaneous writes, and current LangGraph refuses to guess: it raises InvalidUpdateError the instant Web Researcher and Technical Analyst both return citation updates in the same step, and your graph run dies before a report is ever produced.

This is the exact bug the SPEC's hotspot list warns about
"Students who don't understand state reducers will get silent data loss" is not a hypothetical — it is the single most commonly cited real bug when people first build parallel LangGraph systems. The fix is one line per field, but you have to know to add it; LangGraph will not tell you it's missing.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers The fix: Annotated reducers, What You're Building — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.