Back to Journal
•7 min read

LangGraph & Next.js App Router Tutorial: Stateful Multi-Agent Workflows

A practical guide to building stateful multi-agent LLM systems with LangGraph TypeScript, Next.js App Router, conditional routing, human-in-the-loop validation, and real-time SSE streaming.

LangGraphNext.jsTypeScriptMulti-Agent SystemsAI Architecture
LangGraph & Next.js App Router Tutorial: Stateful Multi-Agent Workflows

When building production AI applications beyond simple chat interfaces, single-prompt LLM chains quickly hit architectural limits. Complex engineering tasks—such as automated code reviews, multi-source research synthesis, or autonomous system refactoring—require delegation across specialized agents, iterative revision loops, and strict state persistence.

Linear chains (A -> B -> C) fail when agent B produces inaccurate output or when step C requires human verification before mutating production databases. To build resilient agent networks, systems must support cyclic state graphs, conditional routing, and deterministic checkpointing.

In this guide, we will implement a stateful multi-agent graph architecture using LangGraph (TypeScript) and integrate it into a Next.js App Router application with real-time SSE streaming.

The Architecture: Stateful Multi-Agent Graphs

Instead of forcing a single LLM to play every role, a multi-agent system decouples responsibilities into distinct nodes connected by a shared state context.

                  +-----------------------+
                  |     User Prompt       |
                  +-----------------------+
                              |
                              v
                  +-----------------------+
                  |    Supervisor Node    |
                  +-----------------------+
                     /        |        \
       (Research)   /         |         \  (Drafting)
                   v          |          v
          +------------+      |      +------------+
          | Researcher |      |      |   Writer   |
          |   Agent    |      |      |   Agent    |
          +------------+      |      +------------+
                   \          |          /
                    \         v         /
                  +-----------------------+
                  |     Reviewer Node     |
                  +-----------------------+
                              |
                     (Needs Revision?)
                     /                 \
             [YES / Retry]         [NO / Complete]
                  /                     \
                 v                       v
      +-------------------+    +-------------------+
      | Interrupt / Edit  |    |   Final Output    |
      +-------------------+    +-------------------+

Core Primitives in LangGraph:

  1. State Channels: Type-safe shared memory passed between nodes.
  2. Nodes: Isolated TypeScript functions representing individual agents or tool executors.
  3. Edges: Directed connections that transition execution between nodes.
  4. Conditional Edges: Dynamic routing logic based on evaluation criteria or error thresholds.
  5. Checkpointers: Persistent state stores enabling pause/resume and human-in-the-loop interrupts.

1. Defining Type-Safe State Channels

In LangGraph, state is defined using annotated channels. Each node receives the current graph state and returns a partial state update. Reducer functions determine how updates merge into existing state.

Create src/lib/agents/state.ts:

import { Annotation, BaseMessage } from "@langchain/core/messages";

export interface AgentTask {
  id: string;
  description: string;
  assignedTo: "researcher" | "writer" | "reviewer";
  status: "pending" | "in_progress" | "completed" | "failed";
  result?: string;
}

// Define the central state annotation schema
export const AgentGraphAnnotation = Annotation.Root({
  // Append new messages to conversation history
  messages: Annotation<BaseMessage[]>({
    reducer: (x, y) => x.concat(y),
    default: () => [],
  }),
  // Active task context
  tasks: Annotation<AgentTask[]>({
    reducer: (x, y) => y, // Overwrite with latest task list
    default: () => [],
  }),
  // Quality rating produced by the Reviewer Agent (0 to 10)
  reviewScore: Annotation<number>({
    reducer: (_, y) => y,
    default: () => 0,
  }),
  // Re-evaluation loop counter to prevent infinite recursion
  iterationCount: Annotation<number>({
    reducer: (x, y) => x + y,
    default: () => 0,
  }),
  // Flag indicating human approval requirement
  requiresApproval: Annotation<boolean>({
    reducer: (_, y) => y,
    default: () => false,
  }),
});

export type AgentGraphState = typeof AgentGraphAnnotation.State;

2. Implementing Specialized Agent Nodes

Nodes are asynchronous functions that execute domain-specific logic. Here we define three nodes: Researcher, Writer, and Reviewer.

Create src/lib/agents/nodes.ts:

import { SystemMessage, HumanMessage, AIMessage } from "@langchain/core/messages";
import { ChatOpenAI } from "@langchain/openai";
import type { AgentGraphState } from "./state";

const model = new ChatOpenAI({
  modelName: "gpt-4o-mini",
  temperature: 0.2,
});

// Node 1: Researcher Agent
export async function researcherNode(state: AgentGraphState) {
  const lastMessage = state.messages[state.messages.length - 1];
  
  const response = await model.invoke([
    new SystemMessage(
      "You are a Senior Technical Researcher. Gather structural facts, API constraints, and performance benchmarks."
    ),
    new HumanMessage(lastMessage.content as string),
  ]);

  return {
    messages: [new AIMessage({ content: `[Researcher]: ${response.content}` })],
    iterationCount: 1,
  };
}

// Node 2: Writer Agent
export async function writerNode(state: AgentGraphState) {
  const researchData = state.messages
    .filter((m) => typeof m.content === "string" && m.content.startsWith("[Researcher]"))
    .map((m) => m.content)
    .join("\n");

  const response = await model.invoke([
    new SystemMessage(
      "You are a Technical Writer. Synthesize research data into structured, concrete TypeScript guides."
    ),
    new HumanMessage(`Synthesize the following research:\n${researchData}`),
  ]);

  return {
    messages: [new AIMessage({ content: `[Writer]: ${response.content}` })],
  };
}

// Node 3: Reviewer Node (Evaluates output quality)
export async function reviewerNode(state: AgentGraphState) {
  const draftMessage = state.messages.find(
    (m) => typeof m.content === "string" && m.content.startsWith("[Writer]")
  );

  const evaluation = await model.invoke([
    new SystemMessage(
      "You are a Code Reviewer. Score the technical accuracy from 1 to 10. Respond ONLY with JSON: {\"score\": number, \"feedback\": string}"
    ),
    new HumanMessage((draftMessage?.content as string) || ""),
  ]);

  let score = 5;
  try {
    const parsed = JSON.parse(evaluation.content as string);
    score = parsed.score;
  } catch {
    score = 6;
  }

  return {
    reviewScore: score,
    requiresApproval: score >= 8,
  };
}

3. Constructing the StateGraph with Conditional Edges

We wire the nodes together into a cyclic graph, using a conditional edge function to decide whether to route back to the Writer for revisions or move toward completion.

Create src/lib/agents/graph.ts:

import { StateGraph, START, END, MemorySaver } from "@langchain/langgraph";
import { AgentGraphAnnotation } from "./state";
import { researcherNode, writerNode, reviewerNode } from "./nodes";

// Router function determining graph execution path
function routeReviewOutcome(state: typeof AgentGraphAnnotation.State) {
  // Prevent infinite iteration loops
  if (state.iterationCount >= 3) {
    return "finalize";
  }

  // If score meets threshold, proceed to human approval or completion
  if (state.reviewScore >= 8) {
    return "finalize";
  }

  // Otherwise, route back to Writer for revision
  return "revision";
}

export function buildAgentGraph() {
  const workflow = new StateGraph(AgentGraphAnnotation)
    .addNode("researcher", researcherNode)
    .addNode("writer", writerNode)
    .addNode("reviewer", reviewerNode)
    // Primary execution path
    .addEdge(START, "researcher")
    .addEdge("researcher", "writer")
    .addEdge("writer", "reviewer")
    // Conditional edge after evaluation
    .addConditionalEdges("reviewer", routeReviewOutcome, {
      revision: "writer",
      finalize: END,
    });

  // Attach memory checkpointer for state retention across HTTP requests
  const checkpointer = new MemorySaver();
  
  return workflow.compile({
    checkpointer,
  });
}

4. Next.js API Route Streaming with Server-Sent Events

To provide instant UI updates as agents execute, we stream state events from Next.js App Router using ReadableStream.

Create src/app/api/agent/stream/route.ts:

import { NextRequest, NextResponse } from "next/server";
import { HumanMessage } from "@langchain/core/messages";
import { buildAgentGraph } from "@/lib/agents/graph";

export const runtime = "nodejs";

export async function POST(req: NextRequest) {
  const { prompt, threadId } = await req.json();

  if (!prompt || !threadId) {
    return NextResponse.json({ error: "Missing prompt or threadId" }, { status: 400 });
  }

  const app = buildAgentGraph();
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      try {
        const eventStream = await app.streamEvents(
          {
            messages: [new HumanMessage(prompt)],
          },
          {
            version: "v2",
            configurable: { thread_id: threadId },
          }
        );

        for await (const event of eventStream) {
          if (event.event === "on_chain_start") {
            controller.enqueue(
              encoder.encode(`data: ${JSON.stringify({ type: "node_start", node: event.name })}\n\n`)
            );
          } else if (event.event === "on_chat_model_stream") {
            const chunk = event.data?.chunk?.content;
            if (chunk) {
              controller.enqueue(
                encoder.encode(`data: ${JSON.stringify({ type: "token", text: chunk })}\n\n`)
              );
            }
          } else if (event.event === "on_chain_end" && event.name === "LangGraph") {
            controller.enqueue(
              encoder.encode(`data: ${JSON.stringify({ type: "done", state: event.data?.output })}\n\n`)
            );
          }
        }
      } catch (err: any) {
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify({ type: "error", error: err.message })}\n\n`)
        );
      } finally {
        controller.close();
      }
    },
  });

  return new NextResponse(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

5. Trade-Offs and Architectural Considerations

While multi-agent graph topologies provide structure and resilience, engineering teams must account for key operational trade-offs:

Aspect Single LLM Chain Multi-Agent Graph
Latency Low (Single roundtrip) High (Multiple sequential/parallel calls)
Cost Minimal token usage Higher due to context duplication across nodes
Determinism Low (High variance on multi-step instructions) High (Strict state transitions & boundary checks)
Human-in-the-Loop Hard to pause state cleanly Built-in checkpointers (interrupt())

Production Engineering Checklist:

  1. Re-entrancy & Serialization: Ensure channel state object can be serialized to JSON without loss of symbol references when persisting to Redis or PostgreSQL checkpointers.
  2. Iteration Circuit Breakers: Always enforce maximum recursion counts (state.iterationCount >= N) in conditional edge functions to avoid unbounded token consumption during failed revision loops.
  3. Observability: Trace graph transitions using tools like LangSmith or OpenTelemetry to inspect node latency bottlenecks.

Conclusion

Multi-agent architectures move LLM engineering from unconstrained text generation into predictable distributed systems. By leveraging LangGraph with Next.js, teams can build stateful, self-correcting agent graphs that stream real-time progress while maintaining strict human-in-the-loop governance.

Share this article