🚀 Quick Start

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm
• OpenAI API key

Installation

# Clone the repository
git clone https://github.com/naoufalelh/cursor-langgraph-starter.git
cd cursor-langgraph-starter

# Install dependencies
pnpm install

# Set up environment variables
cp env.example .env
# Edit .env and add your OPENAI_API_KEY

Run the Demo

# Development mode with hot reload
pnpm dev

# Or build and run
pnpm build
pnpm start

Run Tests

pnpm test

🎯 Cursor Integration

This project is designed to work seamlessly with Cursor.

Rules

Cursor rules provide context-aware AI assistance. When you open this project in Cursor, the AI automatically understands:

• LangGraph patterns and best practices
• Project structure and conventions
• TypeScript coding standards

Rules are in .cursor/rules/ and are applied based on file patterns.

Commands

Use slash commands in Cursor Chat for common tasks:

📖 LangGraph Concepts

State

State is defined using Annotations. The AgentState extends MessagesAnnotation for chat history:

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

export const AgentState = Annotation.Root({
  ...MessagesAnnotation.spec,
  // Add custom fields here
});

Nodes

Nodes are async functions that receive state and return partial updates:

const myNode = async (state) => {
  return { messages: [response] }; // Partial update
};

Edges

Conditional edges route based on state:

const shouldContinue = (state) => {
  if (state.messages.at(-1)?.tool_calls?.length) {
    return "tools";
  }
  return END;
};

Workflow

Compose nodes and edges into a graph:

const workflow = new StateGraph(AgentState)
  .addNode("agent", callModel)
  .addNode("tools", toolNode)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", shouldContinue)
  .addEdge("tools", "agent");

export const graph = workflow.compile();

🔧 Extending the Project

Add a New Tool

1. Create tool in src/tools/
2. Export from src/tools/index.ts
3. Tool is automatically available to the agent

Add a New Node

1. Create node function in src/nodes/
2. Add to workflow: workflow.addNode("name", myNode)
3. Connect with edges

Add Memory

The project includes MemorySaver for conversation memory:

const result = await graph.invoke(
  { messages: [new HumanMessage("Hello")] },
  { configurable: { thread_id: "user-123" } }
);

🧪 Evaluations

This project includes a LangSmith-based evaluation framework for assessing agent performance.

Setup

1. Get a LangSmith API key
2. Add to your .env:

   LANGCHAIN_API_KEY=your-langsmith-api-key
   LANGCHAIN_TRACING_V2=true
   

Running Evaluations

# Create the evaluation dataset (first time only)
pnpm eval:create-dataset

# Run evaluations
pnpm eval

Built-in Evaluators

Adding Custom Evaluators

Create evaluators in src/evals/evaluators.ts:

export const myEvaluator = async ({ input, prediction, reference }) => {
  const score = /* 0 to 1 */;
  return { key: "my_metric", score, comment: "Explanation" };
};

View results at smith.langchain.com.

🌊 Streaming

LangGraph supports multiple streaming modes for real-time output.

Run the Streaming Example

pnpm example:streaming

Streaming Modes

Basic Usage

// Stream LLM tokens
for await (const [chunk, metadata] of await graph.stream(input, {
  streamMode: "messages",
})) {
  if (chunk.content) {
    process.stdout.write(chunk.content);
  }
}

🌐 HTTP Server

A ready-to-use HTTP server with REST API and Server-Sent Events (SSE) streaming.

Run the Server

pnpm example:server

Endpoints

Example Request

# Regular invocation
curl -X POST http://localhost:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{"message": "What is 2 + 2?"}'

# Streaming (SSE)
curl -X POST http://localhost:3000/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a poem about AI"}'

🎨 LangGraph Studio

This project is compatible with LangGraph Studio for visual debugging.

The langgraph.json file configures the graph for Studio:

{
  "graphs": {
    "agent": "./src/workflows/agent.ts:graph"
  }
}

🤖 createAgent (LangChain v1)

The new high-level createAgent API from LangChain v1 simplifies agent creation.

pnpm example:create-agent

import { createAgent } from "langchain";

const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools: [searchTool, calculatorTool],
  systemPrompt: "You are a helpful assistant.",
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Hello!" }],
});

This replaces the deprecated createReactAgent from @langchain/langgraph/prebuilt.

⏸️ Interrupts (Human-in-the-Loop)

LangGraph v1 supports typed interrupts for human-in-the-loop workflows.

pnpm example:interrupts

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

const requestApproval = async (state) => {
  // Pause execution and wait for human input
  const response = interrupt({
    task: state.task,
    reason: "Requires approval",
  });
  return { approved: response.approved };
};

// Resume with a Command
await graph.stream(
  new Command({ resume: { approved: true } }),
  config
);

📚 Resources

• LangGraph.js Documentation
• LangSmith Documentation
• Cursor Rules Documentation
• Cursor Commands Documentation
• LangChain.js

📄 License

MIT