LangGraph Multi-Agent Orchestration

Single-agent systems hit a wall once the task surface area grows beyond what a single system prompt can handle cleanly. A monolithic agent that researches, writes code, reviews that code, runs tests, and summarizes results ends up with a sprawling prompt that confuses the LLM, burns excessive tokens re-reading irrelevant instructions, and makes failures hard to isolate. When a code-generation step fails, you have no clean way to retry just that step — you restart the entire chain.

Multi-agent architectures solve this by decomposing the workflow into specialized agents, each with a focused prompt and its own tool set. A Supervisor agent acts as the orchestrator: it reads the user request, decides which specialist to invoke next, and inspects each specialist's output before routing to the next step. This gives you three immediate wins: narrower prompts that produce better outputs, isolated failure domains with targeted retries, and the ability to swap or upgrade individual agents without touching the rest of the graph.

Consider multi-agent when you see these signals: your single prompt is over 2,000 tokens of instructions; you need different tools for different phases of the workflow; you want human review at specific checkpoints; or you need to parallelize independent sub-tasks for latency reduction. This blueprint addresses all four scenarios.

The system is built on a LangGraph StateGraph where each node is an agent or a utility function, and edges define the routing logic between them. At the center sits the Supervisor — a lightweight LLM call whose sole job is to read the current state and decide which agent should act next (or whether the task is complete). Each specialist agent (Research, Code, Review) runs its own tool-calling loop, writes results back to shared state, and returns control to the Supervisor. A PostgreSQL-backed checkpointer persists graph state at every step so long-running workflows can survive process restarts.

LangGraph models state as a Python TypedDict that flows through every node in the graph. Each node receives the current state, performs its work, and returns a partial update that gets merged back. The key design decision is choosing your state schema carefully — it is the contract between all agents. Fields that use the Annotated type with a reducer function (like operator.add for lists) allow multiple agents to append to the same field without overwriting each other's results. This is how you accumulate messages, research findings, and code artifacts across the graph.

Agents communicate through the shared state, not by calling each other directly. When the Research Agent finishes, it appends its findings to research_notes and adds an AIMessage to messages summarizing what it found. The Supervisor reads these updates on its next invocation and decides whether to send the task to the Code Agent, ask for more research, or finalize the response. This decoupled message-passing pattern means you can add, remove, or reorder agents without changing any agent's internal logic — they only need to read from and write to agreed-upon state fields.

LangGraph's add_conditional_edges method is how you implement the Supervisor's routing decisions. After the Supervisor node runs, a routing function inspects the state's next_agent field and returns the name of the node to invoke next. If the Supervisor sets next_agent to "FINISH", the routing function returns the special END constant which terminates the graph. This gives you deterministic, inspectable routing — unlike chain-of-thought routing where the LLM implicitly decides what to do next inside a single prompt.

Start by creating a clean project with pinned dependencies. We will use langgraph for the orchestration graph, langchain-anthropic for Claude LLM calls (you can swap in langchain-openai if you prefer GPT-4), langsmith for tracing, and pydantic for structured tool outputs. The psycopg driver is needed for the PostgreSQL checkpointer that makes your graph resumable.