Core Concepts of LangGraph: Nodes, Edges, and State

To construct cyclic agent workflows, we must understand the three building blocks of a LangGraph StateGraph: Nodes, Edges, and State.

1. The Core Taxonomy Architecture

graph LR
    subgraph StateGraph
        A[Node A: FetchData] -->|Normal Edge| B[Node B: MakeDecision]
        B -->|Conditional Edge| C[Node C: RunTool]
        B -->|Conditional Edge| D[__end__]
        C -->|Normal Edge| B
    end

• State: A shared database-like object representing the collective memory of the graph. Every node can read and update the state.
• Nodes: Standard JavaScript functions that perform a step of work (such as querying an LLM or database). They receive the current state and return a state update object.
• Edges: Rule lines defining the sequence of nodes.
  • Normal Edges: Straight connections (e.g. Node A always flows to Node B).
  • Conditional Edges: Decision pathways (e.g. If the model output contains tool requests, route to Node C; otherwise, route to __end__).

2. Declaring a Basic StateGraph

Here is a TypeScript structure defining a state graph:

// src/services/baseGraph.ts
import { StateGraph, Annotation } from "@langchain/langgraph";

// 1. Declare State schema using Annotation
const GraphStateAnnotation = Annotation.Root({
  userQuery: Annotation<string>(),
  executionLogs: Annotation<string[]>({
    // Reducer function: merges new log lines into the existing array
    reducer: (currentStateValue, updateValue) => currentStateValue.concat(updateValue),
    default: () => [],
  }),
});

// 2. Define Node functions
async function ingestQueryNode(state: typeof GraphStateAnnotation.State) {
  console.log("Ingesting:", state.userQuery);
  return {
    executionLogs: ["Query received by ingest node."],
  };
}

async function analyzeNode(state: typeof GraphStateAnnotation.State) {
  console.log("Analyzing log history length:", state.executionLogs.length);
  return {
    executionLogs: ["Analysis node complete."],
  };
}

// 3. Compose the StateGraph
const workflow = new StateGraph(GraphStateAnnotation)
  .addNode("ingest", ingestQueryNode)
  .addNode("analyze", analyzeNode)
  // Set start node entrypoint
  .setEntryPoint("ingest")
  // Connect nodes using normal edges
  .addEdge("ingest", "analyze")
  .addEdge("analyze", "__end__");

// 4. Compile the graph
export const compiledGraph = workflow.compile();

3. Running the Graph

Invoke the compiled graph passing the initial state object values:

const finalStateResult = await compiledGraph.invoke({
  userQuery: "Build database cluster",
});

console.log("Logs generated:", finalStateResult.executionLogs);