developing-langgraph-js-agents

How LangGraph.js Agents Work

LangGraph decomposes agents into discrete nodes (functions) connected through shared state. Execution flows through a graph where nodes do work and edges determine what runs next.

1. State-First Design

State is the shared memory accessible to all nodes. Design state before nodes:

import { Annotation, MessagesAnnotation } from "@langchain/langgraph";

const AgentState = Annotation.Root({
  ...MessagesAnnotation.spec,
  // Add custom fields with reducers
  context: Annotation<string[]>({
    reducer: (x, y) => x.concat(y),
    default: () => [],
  }),
});

Critical rules:

• Store raw data, not formatted text (format in nodes)
• Use reducers for fields that accumulate (messages, lists)
• Keep state minimal - only persist what's needed across steps

2. Nodes Do Work, Edges Route

// Node: receives state, returns partial update
async function callModel(state: typeof AgentState.State) {
  const response = await model.invoke(state.messages);
  return { messages: [response] };
}

// Edge: determines next node
function shouldContinue(state: typeof AgentState.State) {
  const lastMessage = state.messages.at(-1);
  if (lastMessage?.tool_calls?.length) return "tools";
  return END;
}

3. Always Compile Before Use

const graph = new StateGraph(AgentState)
  .addNode("agent", callModel)
  .addNode("tools", toolNode)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", shouldContinue)
  .addEdge("tools", "agent")
  .compile(); // Required!

4. Checkpointers Enable Persistence

For conversation memory, human-in-the-loop, or fault tolerance:

import { MemorySaver } from "@langchain/langgraph";

const graph = workflow.compile({
  checkpointer: new MemorySaver()
});

// Invoke with thread_id
await graph.invoke(input, {
  configurable: { thread_id: "user-123" }
});