LangGraph.js: Stateful, Multi-Step Workflows

Just like its Python counterpart, LangGraph.js models a workflow as an explicit graph of typed state, nodes, and edges, instead of an implicit "loop until done." It's the tool to reach for once AgentExecutor's simple loop isn't enough, when you need branches, loops back to an earlier step, or several cooperating steps.

Defining typed state

import { Annotation } from '@langchain/langgraph';

const ResearchState = Annotation.Root({
  question: Annotation<string>,
  searchResults: Annotation<string>,
  answer: Annotation<string>,
});

Annotation.Root defines the shape of the state every node reads and updates, typed just like any other TypeScript object, at any point in the graph's execution, the current state is a plain, inspectable, fully-typed value.

Defining nodes

async function searchNode(state: typeof ResearchState.State) {
  const results = `(pretend search results for: ${state.question})`;
  return { searchResults: results };
}

async function answerNode(state: typeof ResearchState.State) {
  const promptText = `Question: ${state.question}
Research: ${state.searchResults}
Answer:`;
  return { answer: `(pretend model answer based on: ${promptText})` };
}

Each node is a plain async function that receives the current state and returns a partial object of updates to merge in, a real searchNode would call a search tool and answerNode would run an LCEL chain, kept as placeholders here since both need real API access.

Wiring the graph

import { StateGraph, END } from '@langchain/langgraph';

const graph = new StateGraph(ResearchState)
  .addNode('search', searchNode)
  .addNode('answer', answerNode)
  .addEdge('__start__', 'search')
  .addEdge('search', 'answer')
  .addEdge('answer', END);

const app = graph.compile();
const result = await app.invoke({ question: 'What is LangGraph.js?', searchResults: '', answer: '' });
console.log(result.answer);

addEdge('search', 'answer') is a fixed transition, addEdge('answer', END) marks answer as terminal, END is a special constant meaning "the graph is finished here."

Conditional edges

function needsMoreResearch(state: typeof ResearchState.State): 'search' | 'answer' {
  return state.searchResults.length < 20 ? 'search' : 'answer';
}

graph.addConditionalEdges('search', needsMoreResearch, { search: 'search', answer: 'answer' });

addConditionalEdges routes to a different next node based on a function of the current state, here looping back to search if results still look too thin, this explicit, typed branching is what a plain AgentExecutor loop doesn't give you directly.