Sandbox::https://docs.langchain.com/oss/javascript/langgraph/use-graph-api

This guide walks through the decisions you make when building a graph. For install and an end-to-end agent example, see the LangGraph quickstart. For a design walkthrough, see Thinking in the Graph API. For concepts, see the Graph API overview.

Build your graph

Work through these decisions in order. Each step includes a short example and links to the how-to for full recipes.

Define shared state

Decide what data nodes share and how updates merge.

Pick a schema (TypedDict, dataclass, or StateSchema in TypeScript).
Add a reducer for any key that multiple nodes write (for example, appending messages).
Use private or input/output schemas when the graph should hide internal channels from callers.

import { StateSchema, ReducedValue } from "@langchain/langgraph";
import * as z from "zod";

const State = new StateSchema({
  foo: z.number(),
  bar: new ReducedValue(
    z.array(z.string()).default(() => []),
    { reducer: (left, right) => left.concat(right) }
  ),
});

Here foo overwrites. bar concatenates.For schemas, reducers, messages, and private state, see Define and update state.

Choose control flow

Decide how work moves between nodes.

Sequence: Fixed steps in order.
Branch: Conditional edges pick the next node from state.
Parallel: Fan-out to several nodes, then fan-in (often with reducers).
Loop: Cycle until a termination condition, or cap runs with a recursion limit.

This sequence checks whether a number is even, then formats a message:

import {
  END,
  START,
  StateGraph,
  StateSchema,
  type GraphNode,
} from "@langchain/langgraph";
import * as z from "zod";

const State = new StateSchema({
  number: z.number(),
  isEven: z.boolean().optional(),
  message: z.string().optional(),
});

const checkEven: GraphNode<typeof State> = (state) => ({
  isEven: state.number % 2 === 0,
});

const formatMessage: GraphNode<typeof State> = (state) => ({
  message: state.isEven ? "The number is even." : "The number is odd.",
});

const graph = new StateGraph(State)
  .addNode("checkEven", checkEven)
  .addNode("formatMessage", formatMessage)
  .addEdge(START, "checkEven")
  .addEdge("checkEven", "formatMessage")
  .addEdge("formatMessage", END)
  .compile();

await graph.invoke({ number: 7 });

For branches, parallel paths, and loops, see Build sequences, branches, and loops.

Decide if you need Send or Command

Most graphs only need nodes, edges, and conditional edges. Keep routing in edges unless you hit one of the cases below. For patterns and examples, see Use Send and Command.Reach for the extras when the default model is not enough:

Use Send when you must run the same node once per item, each with its own input, and the item count is only known at runtime (map-reduce / orchestrator-worker).
Use Command when one step must both update state and choose the next node, resume after an interrupt, or update state from a tool.

import { Command, Send } from "@langchain/langgraph";

// Send: fan out one worker per item
graph.addConditionalEdges("nodeA", (state) => {
  return state.subjects.map(
    (subject) => new Send("generateJoke", { subject })
  );
});

// Command: update state and route in one return
graph.addNode(
  "myNode",
  (state) => {
    return new Command({
      update: { foo: "bar" },
      goto: "myOtherNode",
    });
  },
  { ends: ["myOtherNode"] }
);

Configure nodes as needed

Add runtime options when reliability or cost matters:

Retries and timeouts for flaky or slow steps
Error handlers and graph-wide node defaults
Caching for expensive repeated work
Runtime context or config for dependencies that do not belong in state

const graph = new StateGraph(State)
  .addNode("nodeName", nodeFunction, { retryPolicy: {} })
  .compile();

See Configure nodes.

Visualize the graph

Render a Mermaid or PNG diagram to review topology and debug routing.

const drawableGraph = await graph.getGraphAsync();
console.log(drawableGraph.drawMermaid());

See Visualize your graph.

Next steps

Thinking in the Graph API: Design walkthrough with the email agent
Graph API overview: Concepts for state, nodes, edges, Send, and Command
Define and update state
Build sequences, branches, and loops
Use Send and Command
Configure nodes
Visualize your graph
LangGraph quickstart: End-to-end calculator agent

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Capabilities

Patterns

Build with the Graph API

Deployment

Frontend

Advanced

Build checklist for the Graph API

Build your graph

Next steps