enuno/langchainjs

LangChain.js

LangChain.js is a comprehensive TypeScript framework for building applications powered by large language models. It provides standardized interfaces for connecting LLMs with diverse data sources, tools, and external systems through a modular architecture.

When to Use

• Building AI agents with tool-calling capabilities
• Creating chatbots with conversation memory
• Implementing Retrieval Augmented Generation (RAG) systems
• Connecting LLMs to external data sources and APIs
• Building chains of LLM operations
• Switching between AI providers without code changes
• Streaming LLM responses in real-time
• Implementing structured output from LLMs
• Creating document Q&A systems
• Building semantic search applications

Core Concepts

Agents

Autonomous entities that use LLMs to decide which actions to take. Agents can call tools, access memory, and orchestrate complex workflows.

Chains

Sequences of operations that process inputs through multiple steps. Chains can combine prompts, LLM calls, and post-processing.

Tools

Functions that agents can call to interact with external systems (APIs, databases, web search, etc.).

Memory

Short-term and long-term context management for maintaining conversation state and persistent information.

Retrieval

Integration with vector stores and retrievers for finding relevant documents and context.

Messages

Structured communication format for chat-based interactions (system, human, AI, tool messages).

Structured Output

Constraining LLM responses to specific formats and schemas using Zod or JSON Schema.

---

Installation

Core Packages

# Install core packages
npm install langchain @langchain/core

# Or with other package managers
pnpm install langchain @langchain/core
yarn add langchain @langchain/core
bun add langchain @langchain/core

Requirement: Node.js 20+

Provider Packages

Install provider-specific packages as needed:

# OpenAI
npm install @langchain/openai

# Anthropic
npm install @langchain/anthropic

# Google
npm install @langchain/google-genai

# AWS Bedrock
npm install @langchain/aws

# Azure OpenAI
npm install @langchain/azure-openai

# Mistral
npm install @langchain/mistralai

# Cohere
npm install @langchain/cohere

# Ollama (local models)
npm install @langchain/ollama

---

Package Structure

LangChain.js is organized as a monorepo with specialized packages:

| Package | Purpose | |---------|---------| | langchain | Main entry point, high-level abstractions | | @langchain/core | Base interfaces and foundational abstractions | | @langchain/community | Community-contributed integrations | | @langchain/textsplitters | Text chunking utilities | | @langchain/openai | OpenAI integration | | @langchain/anthropic | Anthropic Claude integration | | @langchain/google-genai | Google AI integration | | @langchain/mcp-adapters | Model Context Protocol adapters |

---

Supported Environments

• Node.js (ESM/CommonJS) - versions 20.x, 22.x, 24.x
• Cloudflare Workers
• Vercel/Next.js (all execution contexts)
• Supabase Edge Functions
• Modern browsers
• Deno
• Bun

---

Basic Usage

Chat Models

import { ChatOpenAI } from "@langchain/openai";

// Initialize chat model
const model = new ChatOpenAI({
  modelName: "gpt-4",
  temperature: 0.7,
});

// Simple invocation
const response = await model.invoke("What is the capital of France?");
console.log(response.content);

// With message array
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const messages = [
  new SystemMessage("You are a helpful assistant."),
  new HumanMessage("What is the capital of France?"),
];

const result = await model.invoke(messages);

Using Anthropic

import { ChatAnthropic } from "@langchain/anthropic";

const model = new ChatAnthropic({
  modelName: "claude-sonnet-4-20250514",
  temperature: 0,
});

const response = await model.invoke("Explain quantum computing in simple terms.");

Streaming Responses

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  modelName: "gpt-4",
  streaming: true,
});

// Stream tokens
const stream = await model.stream("Write a poem about coding.");

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

---

Prompt Templates

import { ChatPromptTemplate } from "@langchain/core/prompts";

// Create template
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a {role} expert."],
  ["human", "{question}"],
]);

// Format with variables
const formattedPrompt = await prompt.format({
  role: "Python",
  question: "How do I read a file?",
});

// Or chain with model
const chain = prompt.pipe(model);
const response = await chain.invoke({
  role: "Python",
  question: "How do I read a file?",
});

Template Variables

import { PromptTemplate } from "@langchain/core/prompts";

const template = PromptTemplate.fromTemplate(
  "Translate the following to {language}: {text}"
);

const result = await template.format({
  language: "Spanish",
  text: "Hello, world!",
});

---

Structured Output

With Zod Schema

import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

const model = new ChatOpenAI({
  modelName: "gpt-4",
});

// Define schema
const Person = z.object({
  name: z.string().describe("The person's name"),
  age: z.number().describe("The person's age"),
  occupation: z.string().describe("The person's job"),
});

// Use withStructuredOutput
const structuredModel = model.withStructuredOutput(Person);

const result = await structuredModel.invoke(
  "Extract info: John is a 30 year old software engineer."
);

console.log(result);
// { name: "John", age: 30, occupation: "software engineer" }

JSON Mode

const model = new ChatOpenAI({
  modelName: "gpt-4-turbo",
  modelKwargs: { response_format: { type: "json_object" } },
});

---

Tools and Function Calling

Defining Tools

import { tool } from "@langchain/core/tools";
import { z } from "zod";

// Define a tool with Zod schema
const weatherTool = tool(
  async ({ location }) => {
    // Actual API call would go here
    return `The weather in ${location} is sunny, 72°F`;
  },
  {
    name: "get_weather",
    description: "Get the current weather for a location",
    schema: z.object({
      location: z.string().describe("The city and state, e.g. San Francisco, CA"),
    }),
  }
);

// Bind tools to model
const modelWithTools = model.bindTools([weatherTool]);

Using Tools with Agents

import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const model = new ChatOpenAI({ modelName: "gpt-4" });

const tools = [weatherTool, searchTool, calculatorTool];

// Create ReAct agent
const agent = createReactAgent({
  llm: model,
  tools: tools,
});

// Run agent
const result = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in NYC?" }],
});

---

Building Agents

Simple Agent (Under 10 Lines)

import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { TavilySearchResults } from "@langchain/community/tools/tavily_search";

const model = new ChatOpenAI({ modelName: "gpt-4" });
const tools = [new TavilySearchResults()];

const agent = createReactAgent({ llm: model, tools });

const response = await agent.invoke({
  messages: [{ role: "user", content: "Search for LangChain news" }],
});

Agent with Memory

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

const memory = new MemorySaver();

const agent = createReactAgent({
  llm: model,
  tools: tools,
  checkpointSaver: memory,
});

// First conversation
const config = { configurable: { thread_id: "conversation-1" } };

await agent.invoke(
  { messages: [{ role: "user", content: "My name is Alice" }] },
  config
);

// Agent remembers context
await agent.invoke(
  { messages: [{ role: "user", content: "What's my name?" }] },
  config
);
// Response: "Your name is Alice"

---

Chains

Simple Chain

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

const model = new ChatOpenAI();
const prompt = ChatPromptTemplate.fromTemplate("Tell me a joke about {topic}");
const outputParser = new StringOutputParser();

// Create chain using pipe
const chain = prompt.pipe(model).pipe(outputParser);

const result = await chain.invoke({ topic: "programming" });

Runnable Sequence

import { RunnableSequence } from "@langchain/core/runnables";

const chain = RunnableSequence.from([
  {
    topic: (input) => input.topic,
    language: (input) => input.language,
  },
  prompt,
  model,
  outputParser,
]);

const result = await chain.invoke({
  topic: "cats",
  language: "French",
});

Parallel Execution

import { RunnableParallel } from "@langchain/core/runnables";

const parallel = RunnableParallel.from({
  joke: jokeChain,
  poem: poemChain,
  fact: factChain,
});

const results = await parallel.invoke({ topic: "space" });
// { joke: "...", poem: "...", fact: "..." }

---

RAG (Retrieval Augmented Generation)

Document Loading

import { TextLoader } from "langchain/document_loaders/fs/text";
import { PDFLoader } from "@langchain/community/document_loaders/fs/pdf";
import { WebLoader } from "langchain/document_loaders/web/cheerio";

// Load text file
const textLoader = new TextLoader("./document.txt");
const textDocs = await textLoader.load();

// Load PDF
const pdfLoader = new PDFLoader("./document.pdf");
const pdfDocs = await pdfLoader.load();

// Load web page
const webLoader = new WebLoader("https://example.com/article");
const webDocs = await webLoader.load();

Text Splitting

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200,
});

const chunks = await splitter.splitDocuments(docs);

Vector Store

import { OpenAIEmbeddings } from "@langchain/openai";
import { MemoryVectorStore } from "langchain/vectorstores/memory";

const embeddings = new OpenAIEmbeddings();

// Create vector store
const vectorStore = await MemoryVectorStore.fromDocuments(
  chunks,
  embeddings
);

// Search for similar documents
const results = await vectorStore.similaritySearch(
  "What is the main topic?",
  3  // Return top 3 results
);

RAG Chain

import { ChatOpenAI } from "@langchain/openai";
import { createStuffDocumentsChain } from "langchain/chains/combine_documents";
import { createRetrievalChain } from "langchain/chains/retrieval";

const model = new ChatOpenAI();

// Create retriever from vector store
const retriever = vectorStore.asRetriever();

// Create RAG prompt
const ragPrompt = ChatPromptTemplate.fromTemplate(`
Answer the question based on the following context:

Context: {context}

Question: {input}
`);

// Build RAG chain
const combineDocsChain = await createStuffDocumentsChain({
  llm: model,
  prompt: ragPrompt,
});

const ragChain = await createRetrievalChain({
  retriever,
  combineDocsChain,
});

// Query
const response = await ragChain.invoke({
  input: "What is discussed in the document?",
});

console.log(response.answer);

---

Memory

Conversation Buffer Memory

import { BufferMemory } from "langchain/memory";
import { ConversationChain } from "langchain/chains";

const memory = new BufferMemory();

const chain = new ConversationChain({
  llm: model,
  memory: memory,
});

await chain.call({ input: "Hi, I'm Bob" });
await chain.call({ input: "What's my name?" });
// Remembers: "Your name is Bob"

Message History

import { ChatMessageHistory } from "@langchain/community/stores/message/in_memory";

const messageHistory = new ChatMessageHistory();

await messageHistory.addUserMessage("Hello!");
await messageHistory.addAIMessage("Hi there! How can I help?");

const messages = await messageHistory.getMessages();

---

Callbacks and Streaming

Custom Callbacks

import { BaseCallbackHandler } from "@langchain/core/callbacks/base";

class MyHandler extends BaseCallbackHandler {
  name = "MyHandler";

  async handleLLMStart(llm, prompts) {
    console.log("LLM starting with prompts:", prompts);
  }

  async handleLLMEnd(output) {
    console.log("LLM finished:", output);
  }

  async handleLLMError(error) {
    console.error("LLM error:", error);
  }
}

const model = new ChatOpenAI({
  callbacks: [new MyHandler()],
});

Streaming with Callbacks

const model = new ChatOpenAI({
  streaming: true,
  callbacks: [
    {
      handleLLMNewToken(token) {
        process.stdout.write(token);
      },
    },
  ],
});

await model.invoke("Write a story about a robot.");

---

Output Parsers

String Parser

import { StringOutputParser } from "@langchain/core/output_parsers";

const parser = new StringOutputParser();
const chain = prompt.pipe(model).pipe(parser);

JSON Parser

import { JsonOutputParser } from "@langchain/core/output_parsers";

const parser = new JsonOutputParser();

List Parser

import { CommaSeparatedListOutputParser } from "@langchain/core/output_parsers";

const parser = new CommaSeparatedListOutputParser();
const chain = prompt.pipe(model).pipe(parser);

const result = await chain.invoke({ topic: "colors" });
// ["red", "blue", "green", ...]

---

LangGraph Integration

LangChain agents are built on top of LangGraph for advanced orchestration:

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

// Define state
interface AgentState {
  messages: BaseMessage[];
  next: string;
}

// Create graph
const graph = new StateGraph<AgentState>({
  channels: {
    messages: { value: (a, b) => [...a, ...b] },
    next: { value: (_, b) => b },
  },
});

// Add nodes
graph.addNode("agent", agentNode);
graph.addNode("tools", toolsNode);

// Add edges
graph.addEdge("agent", "tools");
graph.addConditionalEdges("tools", shouldContinue);

// Compile
const app = graph.compile();

---

LangSmith Integration

Monitor and debug LLM applications:

// Set environment variables
process.env.LANGCHAIN_TRACING_V2 = "true";
process.env.LANGCHAIN_API_KEY = "your-api-key";
process.env.LANGCHAIN_PROJECT = "my-project";

// All LangChain operations are now traced
const result = await chain.invoke({ input: "Hello" });
// View traces at smith.langchain.com

---

Common Integrations

Vector Stores

// Pinecone
import { Pinecone } from "@pinecone-database/pinecone";
import { PineconeStore } from "@langchain/pinecone";

// Chroma
import { Chroma } from "@langchain/community/vectorstores/chroma";

// Supabase
import { SupabaseVectorStore } from "@langchain/community/vectorstores/supabase";

// Weaviate
import { WeaviateStore } from "@langchain/weaviate";

// Qdrant
import { QdrantVectorStore } from "@langchain/qdrant";

Document Loaders

// File loaders
import { TextLoader } from "langchain/document_loaders/fs/text";
import { JSONLoader } from "langchain/document_loaders/fs/json";
import { CSVLoader } from "@langchain/community/document_loaders/fs/csv";

// Web loaders
import { CheerioWebBaseLoader } from "@langchain/community/document_loaders/web/cheerio";
import { PlaywrightWebBaseLoader } from "@langchain/community/document_loaders/web/playwright";

// API loaders
import { NotionLoader } from "@langchain/community/document_loaders/web/notion";
import { GitHubLoader } from "@langchain/community/document_loaders/web/github";

Tools

// Search
import { TavilySearchResults } from "@langchain/community/tools/tavily_search";
import { SerpAPI } from "@langchain/community/tools/serpapi";

// Code execution
import { PythonREPL } from "@langchain/community/tools/python";

// APIs
import { WikipediaQueryRun } from "@langchain/community/tools/wikipedia";
import { Calculator } from "@langchain/community/tools/calculator";

---

Environment Variables

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Google
GOOGLE_API_KEY=...

# LangSmith (tracing)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=...
LANGCHAIN_PROJECT=my-project

# Vector stores
PINECONE_API_KEY=...
PINECONE_ENVIRONMENT=...

---

Project Statistics

• 16.7k GitHub stars
• 3k forks
• 1,055 contributors
• 7,264 commits
• 548+ releases
• 48.9k dependent projects
• 95.6% TypeScript

---

Resources

• Repository: https://github.com/langchain-ai/langchainjs
• Documentation: https://docs.langchain.com/oss/javascript/langchain/overview
• LangSmith: https://smith.langchain.com
• LangGraph: https://langchain-ai.github.io/langgraphjs/
• Discord: https://discord.gg/langchain
• License: MIT

---

Best Practices

Model Selection

• Use gpt-4 or claude-sonnet-4-20250514 for complex reasoning
• Use gpt-3.5-turbo or claude-haiku for simple tasks (cost-effective)
• Use streaming for better UX in chat applications

Memory Management

• Use MemorySaver for conversation persistence
• Clear memory when starting new topics
• Consider token limits when storing history

RAG Optimization

• Chunk documents appropriately (1000-2000 chars)
• Use overlap (10-20% of chunk size)
• Rerank results for better relevance
• Consider hybrid search (semantic + keyword)

Error Handling

try {
  const result = await chain.invoke(input);
} catch (error) {
  if (error.message.includes("rate limit")) {
    // Implement retry with backoff
  } else if (error.message.includes("context length")) {
    // Reduce input size
  }
}

Testing

// Use LangSmith for evaluation
import { evaluate } from "langsmith/evaluation";

await evaluate(
  (input) => chain.invoke(input),
  {
    data: "my-dataset",
    evaluators: [accuracy, relevance],
  }
);

---

Troubleshooting

"API key not found"

export OPENAI_API_KEY=sk-...
# Or set in code
const model = new ChatOpenAI({ openAIApiKey: "sk-..." });

"Context length exceeded"

• Reduce input size
• Use text splitter for long documents
• Implement summarization for conversation history

"Rate limit exceeded"

• Implement exponential backoff
• Use caching for repeated queries
• Consider batch processing

"Module not found"

# Install specific provider package
npm install @langchain/openai

# Or community package
npm install @langchain/community