Terug naar Journal
•7 min leestijd

Autonome Multi-Agent Workflows Bouwen met LangGraph en Next.js

Architectuur van meervoudige stateful LLM-grafieken met aangepaste state-kanalen, voorwaardelijke routing, menselijke goedkeuring en streaming in Next.js.

LangGraphNext.jsTypeScriptMulti-Agent SystemsAI Architecture
Autonome Multi-Agent Workflows Bouwen met LangGraph en Next.js

Bij het bouwen van productie-AI-toepassingen die verder gaan dan eenvoudige chat-interfaces, lopen LLM-ketens met één prompt snel tegen hun architectonische grenzen aan. Complexe engineeringtaken — zoals geautomatiseerde code-reviews, onderzoekssynthese uit meerdere bronnen of autonome systeemrefactoring — vereisen delegatie over gespecialiseerde agents, iteratieve revisielussen en strikte state-persistentie.

Lineaire ketens (A -> B -> C) mislukken wanneer agent B onnauwkeurige resultaten oplevert of wanneer stap C menselijke verificatie vereist voordat productiedatabases worden gewijzigd. Om veerkrachtige agentnetwerken te bouwen, moeten systemen cyclische state-grafieken, voorwaardelijke routing en deterministische checkpointing ondersteunen.

In deze gids implementeren we een meervoudige stateful agent-grafiekarchitectuur met LangGraph (TypeScript) en integreren we deze in een Next.js App Router-applicatie met realtime SSE-streaming.

De Architectuur: Stateful Multi-Agent Grafieken

In plaats van één LLM te dwingen elke rol te vervullen, ontkoppelt een multi-agent systeem de verantwoordelijkheden in afzonderlijke knooppunten die verbonden zijn via een gedeelde 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    |
      +-------------------+    +-------------------+

Kern-Primitieven in LangGraph:

  1. State-Kanalen (State Channels): Typeveilig gedeeld geheugen dat tussen knooppunten wordt doorgegeven.
  2. Knooppunten (Nodes): Geïsoleerde TypeScript-functies die individuele agents of tool-executors vertegenwoordigen.
  3. Kanten (Edges): Gerichte verbindingen die de uitvoering tussen knooppunten overdragen.
  4. Voorwaardelijke Kanten (Conditional Edges): Dynamische routinglogica gebaseerd op evaluatiecriteria of foutdrempels.
  5. Checkpointers: Permanente state-opslag die pauzeren, hervatten en menselijke onderbrekingen mogelijk maakt.

1. Definiëren van Typeveilige State-Kanalen

In LangGraph wordt de state gedefinieerd met behulp van geannoteerde kanalen. Elk knooppunt ontvangt de huidige grafiek-state en retourneert een partiële state-update. Reducer-functies bepalen hoe updates worden samengevoegd met de bestaande state.

Maak 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. Implementeren van Gespecialiseerde Agent-Knooppunten

Knooppunten zijn asynchrone functies die domeinspecifieke logica uitvoeren. Hier definiëren we drie knooppunten: Researcher, Writer en Reviewer.

Maak 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. Bouwen van de StateGraph met Voorwaardelijke Kanten

We verbinden de knooppunten in een cyclische grafiek met behulp van een voorwaardelijke kant-functie om te beslissen of we terugkeren naar de Writer voor revisies of de uitvoering voltooien.

Maak 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 met Server-Sent Events

Om directe UI-updates te bieden tijdens de uitvoering van agents, streamen we state-gebeurtenissen vanuit Next.js App Router met behulp van ReadableStream.

Maak 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. Afwegingen en Architectonische Overwegingen

Hoewel multi-agent grafiektopologieën structuur en veerkracht bieden, moeten engineeringteams rekening houden met belangrijke operationele afwegingen:

Aspect Enkele LLM-Keten Multi-Agent Grafiek
Latentie Laag (Enkele aanroep) Hoger (Meerdere sequentiële / parallelle aanroepen)
Kosten Minimaal tokenverbruik Hoger door contextduplicatie tussen knooppunten
Determinisme Laag (Hoge variantie bij complexe instructies) Hoog (Strikte state-overgangen en drempelcontroles)
Menselijke Goedkeuring Moeilijk schoon te pauzeren Ingebouwde checkpointers (interrupt())

Checklist voor Productie:

  1. Re-entrancy en Serialisatie: Zorg ervoor dat het kanaal-state object naar JSON geserialiseerd kan worden zonder verlies van symboolreferenties bij opslag in Redis of PostgreSQL.
  2. Lusse-Onderbrekers: Dwing altijd maximale iteratiegrenzen af (state.iterationCount >= N) in voorwaardelijke kanten om onbeperkt tokenverbruik bij mislukte revisielussen te voorkomen.
  3. Observabiliteit: Volg grafiekovergangen met tools zoals LangSmith of OpenTelemetry om vertragingsknelpunten bij knooppunten op te sporen.

Conclusie

Multi-agent architecturen verplaatsen LLM-engineering van onbeperkte tekstgeneratie naar voorspelbare gedistribueerde systemen. Door LangGraph te combineren met Next.js, kunnen teams stateful, zelfcorrigerende agent-grafieken bouwen die de voortgang in realtime streamen met behoud van strikte menselijke controle.

Share this article