Skip to content

Chapter 1: The Agentic Shift - Why Loops Matter

Theoretical Foundations

The fundamental shift from linear chains to dynamic, stateful loops represents a paradigm change in how we architect computational processes. To understand this, we must first look backward to a foundational concept introduced in our previous exploration of LangChain primitives: the Sequential Chain. In that model, the flow of data is deterministic and unidirectional. Output A from Node 1 becomes the input for Node 2, which produces Output B for Node 3, and so on, until the pipeline terminates. It is a rigid assembly line, efficient for simple transformations but brittle when facing ambiguity or the need for self-correction.

The Cyclical Graph Structure is the antidote to this rigidity. It transforms the assembly line into a dynamic feedback loop. Imagine a traditional software function that executes once and returns a value. Now, imagine a function that, upon returning, can inspect its own return value, decide that the result is insufficient, and recursively call itself with modified parameters until a specific condition is met. This is the essence of the agentic loop.

The Anatomy of the Agent: A Web Development Microservice Analogy

To ground this theoretically, let us draw a precise analogy to modern web development architecture, specifically Microservices. In a monolithic application, all logic resides in a single, tightly coupled codebase. A change in one module might inadvertently break another. This mirrors the linear chainā€”efficient for small tasks but difficult to scale or debug.

An Agent, in the context of LangGraph.js, functions like a sophisticated microservice cluster. It is not a single function call but a runtime environment composed of four distinct pillars:

  1. The Model (The Brain/Controller): This is the Large Language Model (LLM). In our analogy, this is the API Gateway or the central orchestrator (like an Express.js controller). It doesn't hold data itself; it receives a request, interprets the intent, and decides which downstream service to call.
  2. Tools (The Microservices): These are stateless functions that perform specific tasks (e.g., fetching data from a database, calling an external API, performing a calculation). In our analogy, these are the individual microservices (e.g., a UserService, PaymentService, SearchService). They are isolated, do not know about the broader workflow, and only return data.
  3. Memory (The Shared State/Database): In a microservice architecture, services often need a shared database or a cache (like Redis) to maintain context across requests. In LangGraph, this is the State. It is the mutable object that persists across the cyclical loop. Without state, the agent would suffer from amnesia, forgetting previous steps in every iteration.
  4. Orchestration (The Event Bus/Workflow Engine): This is the LangGraph runtime itself. It defines the edges (routes) between nodes (services). It decides: "The PaymentService failed; route this request back to the Controller (Model) for a retry with a different strategy."

The ReAct Pattern: Reasoning as a State Machine

The most common implementation of this cyclical structure is the ReAct (Reasoning and Acting) pattern. This is not merely a prompt template; it is a state machine defined by a cyclical graph.

The "Why" of Loops: In a linear chain, the model is forced to "reason" and "act" in a single monolithic output. If the model hallucinates a tool name or miscalculates an argument, the chain fails immediately. There is no mechanism for self-correction.

In a cyclical ReAct loop, the process is decomposed: 1. Reasoning (Thought): The Model analyzes the current state and formulates a plan. 2. Acting (Action): The Graph routes this to a Tool node. 3. Observation (Result): The Tool returns a result, which is appended to the State. 4. Loop: The Graph routes back to the Model node. The Model now sees the new State (including the Observation) and reasons again.

This loop continues until a termination condition is met (e.g., the Model determines the answer is sufficient).

Visualizing the Cyclical Flow

The following Graphviz DOT diagram illustrates the structural difference between a linear chain and a LangGraph cyclical agent. Notice the edge connecting the "Tool" node back to the "LLM" node. This is the feedback loop that enables iterative refinement.

This diagram illustrates an AI agent's iterative refinement process, where the LLM generates an initial output, the Tool executes a task based on that output, and the results are fed back into the LLM for further improvement.
Hold "Ctrl" to enable pan & zoom

This diagram illustrates an AI agent's iterative refinement process, where the LLM generates an initial output, the Tool executes a task based on that output, and the results are fed back into the LLM for further improvement.

State Persistence and TypeScript's Strict Type Discipline

The theoretical integrity of this system relies heavily on the StateGraph and the data flowing through it. In a web microservice, we define API contracts (e.g., using OpenAPI/Swagger) to ensure services communicate reliably. In LangGraph.js, we use TypeScript's type system.

This is where Strict Type Discipline becomes a philosophical necessity, not just a preference.

When building a cyclical graph, the State object evolves. It starts as one shape, and after a tool call, it grows. If we use implicit any or disable strictNullChecks, we introduce "silent failures" into our agentic loop. An agent might hallucinate a property that doesn't exist in the state, or a tool might return null when the graph expects a string.

By enforcing strict typing, we define the State Interface explicitly. For example, we might define a state that accumulates a conversation history and a set of facts.

// Theoretical Type Definition for Agent State
// This ensures that every node in the graph adheres to a strict contract.
interface AgentState {
  // The conversation history, accumulating over the loop
  messages: Array<{
    role: 'user' | 'assistant' | 'tool';
    content: string;
  }>;

  // Specific data extracted during the loop
  extractedFacts: string[]; 

  // A flag to determine if the loop should terminate
  // This is crucial for the cyclical graph's termination condition
  isFinal: boolean;
}

Under the hood, the StateGraph manages this object. When an edge points back to a previous node, the graph passes this mutated AgentState back into the Model. The Model does not see a blank slate; it sees the full history of the loop. This persistence is what allows the agent to "learn" from its previous attempts (e.g., realizing a tool call failed and trying a different approach).

The Value of Feedback Loops in Complex Problem Solving

Why endure the complexity of a cyclical graph? The answer lies in the nature of non-deterministic problem solving.

Consider a complex task: "Research the current stock price of Apple, summarize the latest news, and write a tweet about it." * Linear Chain Failure: If the "Research latest news" tool returns an error (e.g., API rate limit), the linear chain crashes. The user gets an error. * Cyclical Agent Success: The agent attempts the tool, hits the rate limit, observes the error in the State, and the cycle loops back to the Reasoning node. The Model now sees: "Tool X failed with rate limit error." It can then reason: "I should wait 60 seconds and retry" or "I should use a cached version of the news." It adapts.

This feedback loop mimics human cognition. We do not solve complex problems in a single linear thought; we iterate, we make mistakes, we correct, and we refine. The Cyclical Graph Structure is the computational manifestation of this iterative intelligence. It moves software from executing a pre-written script to dynamically navigating a problem space.

Basic Code Example

This example demonstrates a "Hello World" level agentic loop within a simulated SaaS context: a simple web application that uses an agent to classify customer support tickets. The agent will reason about the ticket's content and then act by assigning a priority level. We will use a simple cyclical loop to ensure the agent reflects on its decision before finalizing it, introducing the concept of StateGraph and a basic Max Iteration Policy.

The core of this example is the StateGraph, which manages a shared state object (GraphState) as it flows through different nodes (computational steps) connected by edges (transitions).

The Code

/**
 * @fileoverview A simple "Hello World" example of an agentic loop using LangGraph.js.
 * This simulates a SaaS web app feature for classifying customer support tickets.
 * It demonstrates StateGraph, a simple ReAct loop, and a Max Iteration Policy guardrail.
 */

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

// 1. DEFINE THE STATE
// The state is the shared memory for the graph. It's mutable and passed between nodes.
// In a real web app, this could be stored in a database or Redis cache.
const GraphState = Annotation.Root({
  // The raw text of the support ticket from the user.
  ticketText: Annotation<string>(),
  // The agent's current reasoning trace. This is the "thought" part of ReAct.
  reasoning: Annotation<string>({
    reducer: (state, update) => `${state}\n${update}`, // Append new reasoning to the history.
    default: () => "Initial analysis starting...",
  }),
  // The final, determined priority level (e.g., "Low", "Medium", "High", "Urgent").
  priority: Annotation<string>({
    default: () => "Unassigned",
  }),
  // A counter to enforce our Max Iteration Policy.
  iterationCount: Annotation<number>({
    reducer: (state, update) => state + update,
    default: () => 0,
  }),
});

// 2. DEFINE THE NODES (COMPUTATIONAL STEPS)
// Nodes are functions that accept the current state and return a partial state update.

/**
 * Node: `analyzeTicket`
 * Simulates an LLM call to reason about the ticket content.
 * This is the "Reasoning" step of the ReAct pattern.
 * @param {typeof GraphState.State} state - The current graph state.
 * @returns {Partial<typeof GraphState.State>} - An update to the state.
 */
const analyzeTicket = async (
  state: typeof GraphState.State
): Promise<Partial<typeof GraphState.State>> => {
  console.log("--- Node: analyzeTicket ---");

  // In a real app, you would call an LLM here (e.g., GPT-4).
  // For this example, we use simple logic to simulate the LLM's "thought".
  const text = state.ticketText.toLowerCase();
  let reasoning = "";

  if (text.includes("outage") || text.includes("down")) {
    reasoning = "This ticket mentions 'outage' or 'down', indicating a critical system issue. This requires immediate attention.";
  } else if (text.includes("billing") || text.includes("payment")) {
    reasoning = "This is a billing-related query. Financial issues are important but not typically urgent unless it's about a failed payment.";
  } else {
    reasoning = "This is a general inquiry. It can be handled during standard business hours.";
  }

  return {
    reasoning: `Analysis: ${reasoning}`,
    iterationCount: 1, // Increment the iteration counter on each loop.
  };
};

/**
 * Node: `assignPriority`
 * Simulates the "Acting" step of the ReAct pattern.
 * Based on the reasoning, it assigns a priority.
 * @param {typeof GraphState.State} state - The current graph state.
 * @returns {Partial<typeof GraphState.State>} - An update to the state.
 */
const assignPriority = async (
  state: typeof GraphState.State
): Promise<Partial<typeof GraphState.State>> => {
  console.log("--- Node: assignPriority ---");

  // This logic acts upon the previous analysis.
  const reasoning = state.reasoning.toLowerCase();
  let priority = "Low"; // Default

  if (reasoning.includes("critical") || reasoning.includes("immediate")) {
    priority = "Urgent";
  } else if (reasoning.includes("financial") || reasoning.includes("important")) {
    priority = "High";
  } else if (reasoning.includes("general inquiry")) {
    priority = "Medium";
  }

  return {
    priority: priority,
  };
};

/**
 * Node: `reflectOnPriority`
 * This node introduces the cyclical nature of an agent.
 * It checks if the assigned priority is correct. If not, it forces the graph
 * back to the analysis step. This simulates self-correction.
 * @param {typeof GraphState.State} state - The current graph state.
 * @returns {Partial<typeof GraphState.State>} | null - Returns state update or null to stop.
 */
const reflectOnPriority = async (
  state: typeof GraphState.State
): Promise<Partial<typeof GraphState.State> | null> => {
  console.log("--- Node: reflectOnPriority ---");

  // A simple rule: "Urgent" tickets must mention "outage".
  if (state.priority === "Urgent" && !state.ticketText.toLowerCase().includes("outage")) {
    console.log("Reflection: Priority 'Urgent' was assigned incorrectly. Re-analyzing...");
    // Add a reflection note to the reasoning trace.
    return {
      reasoning: "Reflection: Incorrect 'Urgent' assignment detected. Re-triggering analysis.",
      // We do NOT return a new priority here, letting the loop correct it.
    };
  }

  // If the priority is correct, we return null to signal the end of this specific path.
  // In LangGraph, a null return from a conditional edge function often means "don't take this edge".
  // For simplicity here, we'll handle the loop logic in the edges.
  console.log("Reflection: Priority seems correct. Proceeding to finalize.");
  return null;
};

// 3. DEFINE THE EDGES (TRANSITIONS)
// Edges determine which node runs next.

/**
 * Edge: `checkIterationLimit`
 * A conditional edge function that implements a Max Iteration Policy.
 * It prevents infinite loops by checking the iteration count.
 * @param {typeof GraphState.State} state - The current graph state.
 * @returns {string} - The name of the next node to call.
 */
const checkIterationLimit = (
  state: typeof GraphState.State
): string => {
  const MAX_ITERATIONS = 3;

  if (state.iterationCount >= MAX_ITERATIONS) {
    console.log(`--- Edge: Max Iterations (${MAX_ITERATIONS}) Reached. Aborting. ---`);
    return "__end__"; // Special node to terminate the graph.
  }

  // If limit not reached, continue the loop.
  return "analyzeTicket";
};

/**
 * Edge: `determineNextStep`
 * A conditional edge that decides the next action based on reflection.
 * @param {typeof GraphState.State} state - The current graph state.
 * @returns {string} - The name of the next node.
 */
const determineNextStep = (
  state: typeof GraphState.State
): string => {
  // If a reflection was added to reasoning, it means we need to re-analyze.
  if (state.reasoning.includes("Re-triggering analysis")) {
    return "analyzeTicket";
  }
  // Otherwise, proceed to finalize (which in this simple case is just ending).
  return "__end__";
};


// 4. BUILD THE GRAPH
// We use StateGraph to define the structure.

const workflow = new StateGraph(GraphState)
  // Add the nodes to the graph.
  .addNode("analyzeTicket", analyzeTicket)
  .addNode("assignPriority", assignPriority)
  .addNode("reflectOnPriority", reflectOnPriority)

  // Define the entry point of the graph.
  .addEdge("__start__", "analyzeTicket")

  // Define standard sequential edges.
  .addEdge("analyzeTicket", "assignPriority")
  .addEdge("assignPriority", "reflectOnPriority")

  // Add the conditional edges for our loop logic.
  // After reflecting, we check the iteration limit.
  .addConditionalEdges(
    "reflectOnPriority",
    checkIterationLimit,
    {
      "analyzeTicket": "analyzeTicket", // Map the return value to the node.
      "__end__": "__end__"
    }
  )

  // We also add a conditional edge from the analysis step to handle the loop directly.
  // This is a simplified way to create a cycle: analyze -> assign -> reflect -> (back to analyze or end).
  // Note: In a real LangGraph, you might structure this differently, but this illustrates the concept.
  .addConditionalEdges(
    "assignPriority",
    determineNextStep,
    {
      "analyzeTicket": "analyzeTicket",
      "__end__": "__end__"
    }
  );

// Compile the graph into an executable.
const app = workflow.compile();


// 5. RUN THE AGENT (SIMULATE A WEB APP REQUEST)
// This is the main execution block. In a real web app (e.g., Next.js API route),
// this would be an async function handler.

async function runAgent() {
  console.log("šŸš€ Starting Web App Agent: Support Ticket Classifier");

  // Initial inputs simulating a user submitting a form.
  const initialInputs = {
    ticketText: "The entire payment system is down and customers cannot checkout.",
    // iterationCount starts at 0 due to default.
  };

  console.log("\nšŸ“ Initial Ticket:", initialInputs.ticketText);
  console.log("-----------------------------------------\n");

  // Execute the graph.
  // The `stream` method returns an async iterator, perfect for real-time UI updates.
  const stream = await app.stream(initialInputs);

  // Process the stream of events.
  for await (const output of stream) {
    // `output` contains the node name and the state update.
    const nodeName = Object.keys(output)[0];
    const stateUpdate = output[nodeName];

    console.log(`\n--- Stream Output from Node: ${nodeName} ---`);

    if (stateUpdate.priority) {
      console.log(`   šŸ“Œ Priority Assigned: ${stateUpdate.priority}`);
    }
    if (stateUpdate.iterationCount) {
      console.log(`   šŸ” Iteration Count: ${stateUpdate.iterationCount}`);
    }
    if (stateUpdate.reasoning) {
      console.log(`   šŸ’­ Reasoning: ${stateUpdate.reasoning}`);
    }
  }

  // Get the final state after the stream completes.
  // In a real app, you would query the state store or use the final stream event.
  // For this example, we can infer the final state from the logic.
  console.log("\n-----------------------------------------");
  console.log("āœ… Agent Workflow Completed.");
  console.log("Final Output would be sent to the frontend.");
}

// Run the example.
runAgent().catch(console.error);

Visualizing the Graph Structure

The following Graphviz DOT diagram illustrates the flow of our simple agent. Notice the cyclical nature between analyzeTicket, assignPriority, and reflectOnPriority, guarded by the checkIterationLimit conditional edge.

This diagram visualizes the cyclical flow of an AI agent's decision-making process, where analyzeTicket, assignPriority, and reflectOnPriority repeatedly interact until the checkIterationLimit condition is met.
Hold "Ctrl" to enable pan & zoom

This diagram visualizes the cyclical flow of an AI agent's decision-making process, where `analyzeTicket`, `assignPriority`, and `reflectOnPriority` repeatedly interact until the `checkIterationLimit` condition is met.

Detailed, Line-by-Line Explanation

Here is the breakdown of the logic, numbered by the logical blocks in the code.

  1. State Definition (GraphState):

    • const GraphState = Annotation.Root({...}): This initializes the state schema. In LangGraph.js, Annotation is used to define the shape of the state object that gets passed around.
    • ticketText: Annotation<string>(): Defines a simple string property for the input data.
    • reasoning: Annotation<string>({ reducer: ..., default: ... }): This is crucial. It defines a property that accumulates data. The reducer function (state, update) => state + update ensures that every time a node returns a new reasoning string, it is appended to the existing history rather than overwriting it. This creates a "thought trace".
    • priority: Annotation<string>({ default: () => "Unassigned" }): Defines the output property. It has a default value so the graph doesn't crash if accessed before being set.
    • iterationCount: Annotation<number>({ reducer: (state, update) => state + update, default: () => 0 }): This is the implementation of our Max Iteration Policy. The reducer adds the incoming update (usually 1) to the current state, effectively counting the number of times the loop has run.

  2. Node 1: analyzeTicket:

    • const analyzeTicket = async (state) => {...}: Defines an asynchronous function. LangGraph nodes can be async to handle API calls (like LLMs).
    • console.log("--- Node: analyzeTicket ---"): Standard logging for debugging the execution flow.
    • const text = state.ticketText.toLowerCase(): Accesses the current state safely.
    • if/else block: Simulates an LLM's decision-making logic. In a real scenario, you would pass state.ticketText to a model like GPT-4 and parse the output.
    • return { reasoning: ..., iterationCount: 1 }: Returns a partial state object. LangGraph merges this into the global state. We increment iterationCount here to track the loop cycle.

  3. Node 2: assignPriority:

    • This node acts as the "Action" phase of the ReAct pattern.
    • It reads state.reasoning (which was just updated by analyzeTicket).
    • It uses simple string matching to determine the priority.
    • It returns { priority: priority }, updating the state.

  4. Node 3: reflectOnPriority:

    • This introduces the "Loop" concept. It checks the validity of the previous action.
    • if (state.priority === "Urgent" && !state.ticketText.includes("outage")): A specific validation rule.
    • If the validation fails, it returns a state update that modifies the reasoning string to include "Re-triggering analysis".
    • If validation passes, it returns null. In LangGraph's conditional edges, returning null or a value not mapped in the edge definition typically stops execution on that path.

  5. Edge Functions (checkIterationLimit & determineNextStep):

    • These are pure functions that take the state and return a string (the name of the next node).
    • checkIterationLimit: Implements the Max Iteration Policy. It checks state.iterationCount. If it exceeds the limit (set to 3 here), it returns "__end__", which is a special built-in node in LangGraph that terminates the graph execution. This prevents infinite loops in production code.
    • determineNextStep: Checks the content of the reasoning string. If it contains the reflection marker, it returns "analyzeTicket" to restart the loop. Otherwise, it returns "__end__".

  6. Graph Construction:

    • new StateGraph(GraphState): Instantiates the graph with our defined state schema.
    • .addNode("name", function): Registers the functions we defined as executable nodes.
    • .addEdge("__start__", "analyzeTicket"): Defines the entry point. When the graph starts, it immediately goes to analyzeTicket.
    • .addConditionalEdges(...): This is where the dynamic behavior is defined.
      • The first conditional edge is attached to reflectOnPriority. It uses checkIterationLimit to decide where to go next.
      • The second conditional edge is attached to assignPriority. It uses determineNextStep to see if we need to loop back based on the priority assignment logic.

  7. Execution (runAgent):

    • app.stream(initialInputs): This is the standard way to execute a LangGraph. It returns an async iterator.
    • for await (const output of stream): We iterate over the stream. Each output corresponds to a node finishing its execution.
    • This streaming approach is vital for web apps (like Next.js) because it allows the UI to update progressively as the agent "thinks", rather than waiting for the entire process to finish.

Common Pitfalls

When implementing agentic loops in a TypeScript/Node.js environment (especially in serverless deployments like Vercel), watch out for these specific issues:

  1. Async/Await Loops and Vercel Timeouts:

    • Issue: Vercel serverless functions have a default timeout (often 10 seconds for Hobby plans). An agentic loop involving multiple LLM calls can easily exceed this.
    • Warning: Do not use app.invoke() (which waits for the entire graph to finish) inside a serverless function if the loop is complex. Use app.stream() instead. Streaming allows you to send chunks of data (using res.write() in Node.js or StreamingTextResponse in Next.js) to keep the connection alive and show real-time progress to the user, effectively bypassing the "silent timeout" issue.
    • Fix: Always implement streaming for agent responses in web apps.

  2. State Mutation and Reference Errors:

    • Issue: In JavaScript, objects are passed by reference. If you accidentally mutate the state object directly inside a node (e.g., state.priority = "High" instead of returning a new object), you can cause race conditions or unpredictable behavior in concurrent requests.
    • Warning: LangGraph relies on immutability patterns. Always return a new partial state object from your nodes. Do not modify the input state argument.
    • Fix: Use the spread operator (...state) or the Annotation reducers provided by LangGraph to handle state updates safely.

  3. Infinite Loops (The "Hallucinated JSON" of Logic):

    • Issue: If your conditional edge logic is flawed (e.g., the reflectOnPriority node never returns a condition that leads to __end__), the agent will loop forever. In a serverless environment, this consumes compute time and racks up costs until the platform kills the process.
    • Warning: Never rely solely on the agent's "intelligence" to terminate a loop.
    • Fix: Always implement a Max Iteration Policy (as shown in the checkIterationLimit function). This is a hard-coded guardrail that forces termination regardless of the agent's logic.

  4. TypeScript Type Safety with State:

    • Issue: As graphs grow, the state object becomes complex. Accessing state.nonExistentProperty will return undefined without throwing a runtime error, leading to silent failures where the agent passes undefined to an LLM call.
    • Warning: Loose typing on the state object is dangerous.
    • Fix: Use strict TypeScript interfaces or the Annotation system provided by LangGraph. Ensure every node's return type is explicitly typed (e.g., Promise<Partial<typeof GraphState.State>>). This catches errors at compile time rather than runtime.

The chapter continues with advanced code, exercises and solutions with analysis, you can find them on the ebook on Leanpub.com or Amazon

Loading knowledge check...

Code License: All code examples are released under the MIT License. Github repo.

Content Copyright: Copyright © 2026 Edgar Milvus | Privacy & Cookie Policy. All rights reserved.

All textual explanations, original diagrams, and illustrations are the intellectual property of the author. To support the maintenance of this site via AdSense, please read this content exclusively online. Copying, redistribution, or reproduction is strictly prohibited.