Related Pages

Related topics: Getting Started, Package Architecture

Introduction to LangChain.js

LangChain.js is a JavaScript/TypeScript framework designed for building applications with Large Language Models (LLMs) through composability. It provides a standardized interface for working with different LLM providers, offers tools for prompt management, and enables the creation of complex chains and agents that can interact with external data sources and APIs.

Architecture Overview

LangChain.js is organized into a modular monorepo structure with multiple packages that serve different purposes. Each package focuses on specific functionality while maintaining interoperability through shared dependencies.

graph TD
    A[Application Layer] --> B[libs/langchain]
    A --> C[@langchain/classic]
    B --> D[@langchain/core]
    C --> D
    E[Provider Integrations] --> F[libs/providers/*]
    F --> D
    G[Utility Packages] --> H[@langchain/textsplitters]
    H --> D
    
    style A fill:#e1f5fe
    style D fill:#f3e5f5
    style F fill:#fff3e0

Core Packages

@langchain/core

The foundational package containing essential abstractions and schemas used throughout the LangChain.js ecosystem.

Key Dependencies:

• @cfworker/json-schema - JSON schema validation
• @standard-schema/spec - Standard schema support
• js-tiktoken - Token counting
• langsmith - Tracing and evaluation (>= 0.5.0 < 1.0.0)
• mustache - Template rendering
• p-queue - Promise queue management
• zod - Schema validation

Sources: libs/langchain-core/package.json:1-35

libs/langchain

The main LangChain package that provides the primary API surface for building LLM applications. This package focuses on the essential building blocks for modern agent development, including the createAgent API.

@langchain/classic

A backward-compatibility package containing functionality migrated from LangChain v0.x. This package exists to support existing applications while the core langchain package focuses on modern agent development.

When to use @langchain/classic:

• Existing code using legacy chains (LLMChain, ConversationalRetrievalQAChain, RetrievalQAChain)
• Using the indexing API with RecordManager
• Depending on community integrations previously re-exported from langchain
• Maintaining existing applications not yet ready for the new createAgent API

Sources: libs/langchain-classic/README.md:1-45

Provider Integrations

LangChain.js provides integration packages for various LLM providers through the libs/providers directory.

Available Provider Packages

Each integration package follows a consistent template structure and includes:

• TypeScript source code
• ESLint linting configuration
• Vitest testing framework
• TypeScript build compilation via tsdown

Sources: libs/providers/langchain-tavily/package.json:1-35 Sources: libs/providers/langchain-qdrant/package.json:1-35

Text Processing

@langchain/textsplitters

A dedicated package for splitting text into chunks, commonly used in retrieval-augmented generation (RAG) pipelines.

Supported Splitting Strategies:

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

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);

Sources: libs/langchain-textsplitters/README.md:1-40 Sources: examples/src/langchain-classic/indexes/html_text_splitter.ts:1-20

Testing Infrastructure

LangChain.js includes custom Jest/Vitest matchers for testing chains, agents, and messages.

export const langchainMatchers = {
  toBeHumanMessage,
  toBeAIMessage,
  toBeSystemMessage,
  toBeToolMessage,
  toHaveToolCalls,
  toHaveToolCallCount,
  toContainToolCall,
  toHaveToolMessages,
  toHaveBeenInterrupted,
  toHaveStructuredResponse,
};

Matcher Usage:

expect(someMessage).toBeHumanMessage();
expect(someMessage).toBeAIMessage();
expect(someChain).toHaveToolCalls([
  { name: "calculator", args: { expression: "2+2" } }
]);

Sources: libs/langchain-core/src/testing/matchers.ts:80-95

Agent Middleware

Human-in-the-Loop (HITL) Middleware

The framework supports human-in-the-loop workflows through configurable interrupt mechanisms.

const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription
};

Configuration Schema:

Sources: libs/langchain/src/agents/middleware/hitl.ts:60-80

Message Block Translators

LangChain.js provides standardized message translation between different API formats, particularly for OpenAI and Anthropic.

const BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletionsChunk(message);
    }
    return convertToV1FromResponsesChunk(message);
  },
};

Sources: libs/langchain-core/src/messages/block_translators/openai.ts:1-15

Namespace System

LangChain.js uses a namespace utility for tracking and identifying LangChain-specific objects.

export const ns = createNamespace("langchain");

Namespaces provide:

• Hierarchical path organization (ns.sub("component"))
• Instance type checking (ns.isInstance(obj))
• Branded type creation for type safety

Sources: libs/langchain-core/src/utils/namespace.ts:1-45

Legacy Chains (Deprecated)

The @langchain/classic package includes deprecated chain implementations:

Sources: libs/langchain-classic/README.md:15-30

Development Workflow

Repository Structure

langchainjs/
├── libs/
│   ├── langchain/              # Main LangChain package
│   ├── langchain-core/         # Core abstractions
│   ├── langchain-classic/      # Legacy v0.x functionality
│   ├── langchain-textsplitters/ # Text splitting utilities
│   └── providers/              # Provider integrations
├── examples/                   # Usage examples
└── libs/create-langchain-integration/  # Package template

Building Packages

pnpm install
pnpm build

Running Examples

cp .env.example .env
# Edit .env with API keys
pnpm run start ./src/path/to/example.ts

Sources: examples/src/README.md:1-25

Migration Guide

From langchain v0.x to v1.0

For new projects: Use the langchain v1.0 package with createAgent API.

For existing projects: Install @langchain/classic for backward compatibility:

npm install @langchain/classic @langchain/core

The new APIs provide:

• Cleaner, more powerful agent building
• Middleware support
• Better performance for modern workflows
• Focused API surface with less complexity
• Active development on v1.0 features

Sources: libs/langchain-classic/README.md:30-55

Version Compatibility

When using multiple LangChain packages, ensure they share the same @langchain/core instance:

{
  "dependencies": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}

Sources: libs/create-langchain-integration/template/README.md:20-35

Related Pages

Related topics: Introduction to LangChain.js

Getting Started

LangChain.js is a comprehensive framework for building LLM-powered applications. It enables developers to chain together interoperable components and third-party integrations, simplifying AI application development while future-proofing decisions as underlying technology evolves.

Sources: README.md:1-15

Prerequisites

System Requirements

Environment Setup

Before installing LangChain.js packages, ensure your environment is properly configured. Most integrations require API keys from respective service providers.

# Example API key environment variables
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
export COHERE_API_KEY="your-key-here"
export TOGETHER_AI_API_KEY="your-key-here"
export BEDROCK_AWS_REGION="us-east-1"

Sources: libs/providers/langchain-anthropic/README.md:1-30

Installation

LangChain.js follows a modular architecture with packages organized by functionality. Understanding the package structure is essential for proper installation.

Package Architecture Overview

graph TD
    A[Application] --> B[langchain v1.0]
    A --> C[@langchain/classic]
    B --> D[@langchain/core]
    C --> D
    B --> E[@langchain/textsplitters]
    B --> F[Provider Packages]
    F --> G[@langchain/anthropic]
    F --> H[@langchain/openai]
    F --> I[@langchain/cohere]
    F --> J[@langchain/aws]
    F --> K[@langchain/google-common]

Sources: libs/langchain-classic/README.md:1-50

Core Packages

#### @langchain/core

The foundational package that all other LangChain packages depend on. It provides base classes, interfaces, and utilities used across the ecosystem.

npm install @langchain/core

Sources: libs/providers/langchain-anthropic/README.md:1-15

#### langchain (v1.0)

The main package for building agents with modern APIs, including the createAgent function with middleware support.

npm install langchain

#### @langchain/textsplitters

Specialized package for splitting documents into chunks, commonly used in retrieval-augmented generation (RAG) pipelines.

npm install @langchain/textsplitters @langchain/core

Sources: libs/langchain-textsplitters/README.md:1-25

Provider Packages

LangChain.js provides official integrations for various LLM providers:

npm install @langchain/anthropic @langchain/core
npm install @langchain/openai @langchain/core
npm install @langchain/cohere @langchain/core

Sources: libs/providers/langchain-anthropic/README.md:1-25

@langchain/classic (Legacy)

For existing applications using LangChain v0.x, the @langchain/classic package provides backward compatibility with legacy chains and functionality.

npm install @langchain/classic

This package requires @langchain/core as a peer dependency:

npm install @langchain/core

Sources: libs/langchain-classic/README.md:1-60

Core Dependency Management

When using multiple LangChain packages together, ensure all packages resolve to the same instance of @langchain/core to avoid conflicts.

Add the following configuration to your package.json:

{
  "name": "your-project",
  "version": "0.0.0",
  "dependencies": {
    "@langchain/anthropic": "^0.0.9",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  },
  "pnpm": {
    "overrides": {
      "@langchain/core": "^0.3.0"
    }
  }
}

Sources: libs/providers/langchain-cohere/README.md:15-45

Development Setup

Building from Source

To develop with LangChain.js locally or run examples:

# Install dependencies from repository root
pnpm install

# Build all packages
pnpm build

Sources: examples/src/README.md:1-20

Running Examples

Most examples require API keys. Configure your environment by copying the example environment file:

cp .env.example .env

Then edit .env with your API keys. Run examples using the provided script:

# From the examples/ directory
pnpm run start <path to example>

# Example
pnpm run start ./src/prompts/few_shot.ts

To run examples with transpiled JavaScript:

pnpm run start:dist <path to example>

# Example
pnpm run start:dist ./dist/prompts/few_shot.js

Sources: examples/src/README.md:1-45

Testing

Test files follow naming conventions:

• Unit tests: *.test.ts
• Integration tests: *.int.test.ts

# Run all tests
pnpm test

# Run integration tests specifically
pnpm test:int

For individual packages:

# Build a specific package
pnpm build --filter @langchain/textsplitters

# Run tests for a specific package
cd libs/langchain-textsplitters
pnpm test

Sources: libs/langchain-textsplitters/README.md:25-50

Quick Start Example

Basic Chat Model Usage

import { ChatAnthropic } from "@langchain/anthropic";
import { HumanMessage } from "@langchain/core/messages";

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

const response = await model.invoke([
  new HumanMessage("Translate "I love programming" into French.")
]);

console.log(response.content);
// Output: J'adore la programmation.

Sources: libs/providers/langchain-anthropic/README.md:1-50

Document Splitting for RAG

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

const text = `<!DOCTYPE html>
<html>
  <head>
    <title>LangChain</title>
  </head>
  <body>
    <h1>Welcome</h1>
    <p>Building applications with LLMs</p>
  </body>
</html>`;

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});

const output = await splitter.createDocuments([text]);
console.log(output);

Sources: examples/src/langchain-classic/indexes/html_text_splitter.ts:1-30

Choosing the Right Package

For New Projects

Use langchain v1.0 for new projects. It provides:

• createAgent: A cleaner, more powerful way to build agents with middleware support
• Better performance: Optimized for modern agent workflows
• Focused API surface: Less complexity, easier to learn
• Active development: New features and improvements focus on v1.0 APIs

For Legacy Projects

Use @langchain/classic if you:

• Have existing code using legacy chains (e.g., LLMChain, ConversationalRetrievalQAChain)
• Use the indexing API
• Depend on functionality from @langchain/community previously re-exported from langchain
• Are maintaining an existing application and not yet ready to migrate

Package Decision Flow

graph TD
    A[New Project?] -->|Yes| B[Use langchain v1.0]
    A -->|No| C[Maintaining Existing Code?]
    C -->|Yes| D[Using Legacy Chains?]
    C -->|No| E[Use langchain v1.0]
    D -->|Yes| F[Use @langchain/classic]
    D -->|No| E

Sources: libs/langchain-classic/README.md:40-80

Additional Resources

Sources: README.md:15-30

Related Pages

Related topics: Introduction to LangChain.js, Core Abstractions

Package Architecture

Overview

The LangChain.js repository employs a sophisticated monorepo architecture built on pnpm workspaces and Turbo. This design enables modular development, shared tooling, and independent versioning across multiple packages. The monorepo structure separates concerns into distinct layers: core abstractions, main integration packages, provider-specific SDKs, and community contributions. This architectural approach allows developers to install only the dependencies they need while maintaining a coherent ecosystem where packages can reference and compose with each other seamlessly.

Monorepo Structure

Workspace Organization

The repository uses pnpm workspaces to manage multiple packages under a single repository. This enables efficient dependency management, shared node_modules, and unified versioning strategies across the ecosystem.

graph TD
    A[Root: langchainjs] --> B[libs/]
    A --> C[examples/]
    A --> D[docs/]
    B --> E[langchain-core/]
    B --> F[langchain/]
    B --> G[langchain-classic/]
    B --> H[providers/]
    B --> I[langchain-textsplitters/]
    B --> J[community/]
    H --> K[langchain-openai/]
    H --> L[langchain-anthropic/]
    H --> M[langchain-google/]
    H --> N[langchain-pinecone/]
    H --> O[langchain-qdrant/]

Build Pipeline with Turbo

The build system uses Turbo to orchestrate builds, tests, and linting across packages. Turbo's caching mechanism significantly improves build times by only rebuilding packages that have changed since the last build.

graph LR
    A[pnpm install] --> B[turbo build]
    B --> C[langchain-core]
    C --> D[langchain]
    C --> E[providers]
    C --> F[community]
    D --> G[langchain-classic]
    G --> H[examples]

Core Packages

@langchain/core

The foundational package that contains all core abstractions, interfaces, and utilities. This package is a peer dependency for all other LangChain packages and must be kept synchronized across the ecosystem.

graph TD
    A[@langchain/core] --> B[Messages & Chat Models]
    A --> C[Tools & Toolkits]
    A --> D[Vector Stores]
    A --> E[Document Loaders]
    A --> F[Output Parsers]
    A --> G[Retrievers]
    A --> H[Callbacks]
    A --> I[Memory]

Key Responsibilities:

• Defines base classes for all major abstractions (BaseLanguageModel, BaseRetriever, BaseChatModel)
• Provides TypeScript utilities and type guards for common patterns
• Exports core message types (AIMessage, HumanMessage, SystemMessage, ToolMessage)
• Implements hash utilities and data transformation functions

@langchain/langchain

The main package that re-exports functionality from core and community packages. This serves as a convenient entry point for users who want access to all integrations without managing individual package dependencies.

@langchain/classic

Contains legacy chain implementations from v0.x that have been deprecated or replaced in v1.0. This package provides migration paths for existing users while maintaining backward compatibility.

Text Processing Packages

@langchain/textsplitters

Provides various implementations of text splitters commonly used in retrieval-augmented generation (RAG) pipelines. Text splitters break large documents into smaller chunks for embedding and retrieval.

Supported Languages:

Example Usage:

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

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);

Provider Integration Packages

The provider packages in libs/providers/ contain integrations for specific third-party services. Each package follows a consistent structure and can be used independently or alongside other LangChain packages.

Package Naming Convention

Provider packages follow the naming pattern @langchain/[provider-name], where the provider name typically corresponds to the service being integrated. All provider packages depend on @langchain/core and may optionally depend on the provider's official SDK.

Provider Packages

Common Package Structure

Each provider package follows a standardized structure:

graph TD
    A[Package Root] --> B[README.md]
    A --> C[package.json]
    A --> D[src/index.ts]
    A --> E[src/chat_models/]
    A --> F[src/output_parsers/]
    A --> G[tests/]
    E --> H[index.ts]
    G --> I[*.test.ts]
    G --> J[*.int.test.ts]

Dependency Management

Core Dependency Synchronization

When using multiple LangChain packages in a project, it is critical to ensure all packages depend on the same instance of @langchain/core. Package managers may resolve different versions of @langchain/core as separate instances, causing runtime errors.

Recommended Configuration (package.json):

{
  "name": "your-project",
  "version": "0.0.0",
  "dependencies": {
    "@langchain/openai": "^0.0.0",
    "@langchain/anthropic": "^0.0.0",
    "@langchain/core": "^0.3.0"
  },
  "resolutions": {
    "@langchain/core": "^0.3.0"
  },
  "overrides": {
    "@langchain/core": "^0.3.0"
  }
}

Different package managers require specific configuration fields:

Entry Points and Exports

Export Strategy

Packages can export functionality through two mechanisms: re-exports from src/index.ts or explicit entry points defined in the exports field of package.json. The exports field enables conditional imports and tree-shaking optimization.

Deprecation Warnings

When importing from deprecated entry points, packages emit console warnings directing users to the new import paths. These warnings can be suppressed by setting the environment variable LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS to "true".

// Deprecated warning format
if (getEnvironmentVariable("LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS") !== "true") {
  console.warn(warningText);
}

Development Workflow

Installing Dependencies

pnpm install

Building Packages

Individual packages can be built using the Turbo filter:

pnpm build --filter @langchain/core

Running Tests

Test files should be located in a tests/ directory within the src/ folder.

Linting and Formatting

pnpm lint && pnpm format

Migration Path

From langchain v0.x to v1.0

The v1.0 release introduces significant architectural changes. Legacy functionality has been moved to @langchain/classic, while new abstractions live in @langchain/core and provider-specific packages. Users upgrading from v0.x should:

1. Install @langchain/classic for backward compatibility
2. Install new provider packages as needed
3. Update import statements to use new package paths
4. Remove imports from deprecated langchain/ subpaths

npm install @langchain/classic
npm install @langchain/anthropic @langchain/core

Summary

The LangChain.js package architecture reflects a commitment to modularity, performance, and developer experience. By separating concerns across well-defined packages, the ecosystem enables efficient development while maintaining interoperability. The monorepo structure, powered by pnpm workspaces and Turbo, provides the foundation for managing this complexity at scale.

Related Pages

Related topics: Package Architecture, Chat Models and LLM Providers

Core Abstractions

The Core Abstractions in LangChain.js form the foundational building blocks that enable interoperability between different components in LLM-powered applications. These abstractions define standardized interfaces for language models, embeddings, vector stores, prompts, output parsers, and runnable components, allowing developers to swap implementations without changing application logic.

Overview

LangChain.js implements a set of abstract base classes in @langchain/core that establish contracts for:

• Runnable components that can be composed into processing pipelines
• Language models (chat and completion models)
• Embedding models for vector representations
• Vector stores for semantic search and retrieval
• Callback systems for observability and event handling
• Prompt templates for structured input formatting
• Output parsers for structured response extraction

This abstraction layer enables loose coupling between components, making it straightforward to migrate between different model providers, vector stores, or embedding implementations while maintaining the same application code.

Runnable Architecture

BaseRunnable

The BaseRunnable class is the central abstraction that all runnable components extend. It provides a unified interface for invoking, batching, streaming, and composing operations.

graph TD
    A[BaseRunnable] --> B[invoke input]
    A --> C[batch inputs]
    A --> D[stream output]
    A --> E[async operations]
    
    B --> F[Runnable Sequence]
    B --> G[Runnable Branch]
    B --> H[Runnable Map]
    
    style A fill:#e1f5fe
    style F fill:#fff3e0
    style G fill:#fff3e0
    style H fill:#fff3e0

The BaseRunnable interface defines the following core methods:

Sources: libs/langchain-core/src/runnables/base.ts

RunnableConfig

Configuration options passed to runnable operations:

interface RunnableConfig {
  tags?: string[];
  metadata?: Record<string, unknown>;
  callbacks?: CallbackManager | CallbackHandler | Array<CallbackManager | CallbackHandler>;
  maxConcurrency?: number;
  maxTokens?: number;
  recursionLimit?: number;
  runName?: string;
}

Sources: libs/langchain-core/src/runnables/base.ts

Language Model Abstractions

BaseChatModel

The BaseChatModel abstract class defines the contract for chat-oriented language models that process messages and return chat results.

graph LR
    A[HumanMessage] --> B[BaseChatModel]
    C[SystemMessage] --> B
    D[AIMessage] --> B
    
    B --> E[invoke]
    B --> F[batch]
    B --> G[stream]
    
    E --> H[BaseMessageChunk]
    F --> I[BaseMessage[]]
    G --> J[Generator of chunks]
    
    style B fill:#e8f5e9

Key properties and methods:

Sources: libs/langchain-core/src/language_models/chat_models.ts

BaseLLM

The BaseLLM class provides the abstraction for traditional completion-based language models:

Sources: libs/langchain-core/src/language_models/llms.ts

Message Types

LangChain.js uses a structured message system:

Embedding Abstractions

BaseEmbeddings

The BaseEmbeddings abstract class provides a standardized interface for generating vector embeddings from text:

graph TD
    A[BaseEmbeddings] --> B[embedQuery text]
    A --> C[embedDocuments texts]
    
    B --> D[float array]
    C --> E[float array[]]
    
    style A fill:#fce4ec

Both methods return Promise<number[][]> representing the embedding vectors.

Sources: libs/langchain-core/src/embeddings.ts

Vector Store Abstractions

VectorStore

The VectorStore class provides an abstraction for storing and querying vector embeddings:

graph TD
    A[VectorStore] --> B[addDocuments]
    A --> C[similaritySearch]
    A --> D[similaritySearchVectorWithScore]
    A --> E[maxMarginalRelevanceSearch]
    
    B --> F[Document[]]
    C --> G[Document[] by query]
    D --> H[Document[] with scores]
    E --> I[Diverse results]
    
    style A fill:#fff8e1

Core methods:

Sources: libs/langchain-core/src/vectorstores.ts

Document Structure

Documents are the fundamental unit stored in vector stores:

interface Document {
  pageContent: string;  // The text content
  metadata: Record<string, unknown>;  // Associated metadata
}

Callback System

BaseCallbackHandler

The BaseCallbackHandler provides a hook system for observing and logging LangChain operations:

graph LR
    A[LangChain Event] --> B[CallbackManager]
    B --> C[onChainStart]
    B --> D[onChainEnd]
    B --> E[onChainError]
    B --> F[onLLMStart]
    B --> G[onLLMEnd]
    B --> H[onToolStart]
    B --> I[onToolEnd]
    
    style B fill:#e3f2fd

Event handlers:

Sources: libs/langchain-core/src/callbacks/base.ts

Prompt Abstractions

BasePromptTemplate

The BasePromptTemplate abstract class standardizes prompt creation and formatting:

graph TD
    A[BasePromptTemplate] --> B[merge]
    A --> C[partial]
    A --> D[invoke]
    
    E[Input Values] --> C
    F[Partial Values] --> B
    G[Runtime Input] --> D
    
    B --> H[PromptTemplate]
    C --> I[PromptTemplate]
    D --> J[Formatted String]
    
    style A fill:#f3e5f5

Key methods:

Sources: libs/langchain-core/src/prompts/index.ts

PromptValue

Prompt values represent the formatted input to language models:

interface PromptValue {
  toChatMessages(): BaseMessage[];
  toString(): string;
}

Output Parser Abstractions

BaseOutputParser

The BaseOutputParser class provides a standardized interface for parsing and validating model outputs:

graph TD
    A[BaseOutputParser] --> B[parse text]
    A --> C[parseWithPrompt]
    A --> D[getFormatInstructions]
    
    E[Raw Output] --> B
    F[Prompt + Output] --> C
    
    B --> G[Structured Result]
    C --> G
    D --> H[Format Instructions]
    
    style A fill:#e0f7fa

Required methods:

Optional methods:

Sources: libs/langchain-core/src/output_parsers/index.ts

Component Composition

LangChain.js enables powerful composition through the pipe operator:

graph LR
    A[PromptTemplate] -->|"pipe"| B[ChatModel]
    B -->|"pipe"| C[OutputParser]
    
    style A fill:#fff8e1
    style B fill:#e8f5e9
    style C fill:#e0f7fa

Example composition:

const chain = prompt.pipe(chatModel).pipe(outputParser);
const result = await chain.invoke({ input: "your question" });

This composition model allows:

• Sequential processing through pipe()
• Parallel execution with RunnableParallel
• Conditional branching with RunnableBranch
• Error handling and fallbacks

Configuration and Initialization

All core abstractions accept configuration through constructor options:

interface BaseLanguageModelParams {
  callbacks?: CallbackManager;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

interface BaseChatModel extends BaseLanguageModelParams {
  temperature?: number;
  topP?: number;
  maxTokens?: number;
  modelName?: string;
}

Extension Pattern

To implement a custom component, extend the base class and implement required abstract methods:

import { BaseLLM } from "@langchain/core/language_models/llms";

class MyCustomLLM extends BaseLLM {
  _llmType() {
    return "my_custom_llm";
  }

  async _call(prompt: string): Promise<string> {
    // Implementation
    return response;
  }
}

Summary

The Core Abstractions in LangChain.js provide:

These abstractions enable portable, testable, and composable LLM applications while maintaining flexibility to swap implementations as requirements evolve.

Related Pages

Related topics: Embeddings Integration, Agent Framework

Chat Models and LLM Providers

LangChain.js provides a unified abstraction layer for interacting with various Large Language Model (LLM) providers through a standardized chat model interface. This system enables developers to seamlessly switch between different providers (OpenAI, Anthropic, Google, Mistral AI, Ollama, Deepseek, Groq, xAI) while maintaining consistent API patterns for invocation, streaming, and tool usage.

Architecture Overview

The chat model architecture follows a provider-specific implementation pattern where each LLM provider package contains its own chat model class that extends common base abstractions from @langchain/core.

graph TD
    A[Application Code] --> B[Chat Model Interface]
    B --> C[Provider Implementations]
    C --> D[OpenAI ChatModels]
    C --> E[Anthropic ChatModels]
    C --> F[Google ChatModels]
    C --> G[MistralAI ChatModels]
    C --> H[Ollama ChatModels]
    C --> I[Deepseek ChatModels]
    C --> J[Groq ChatModels]
    C --> K[xAI ChatModels]
    B --> L[Tool Calling Abstraction]
    B --> M[Streaming Abstraction]

Core Message Types

LangChain.js defines standardized message types that form the foundation of the chat model system. All providers return variations of these message types with provider-specific metadata.

AIMessage

The primary return type from chat model invocations, containing the model's response along with usage and response metadata.

AIMessage {
  "id": "msg_01QDpd78JUHpRP6bRRNyzbW3",
  "content": "Here's the translation to French:\n\nJ'adore la programmation.",
  "response_metadata": {
    "id": "msg_01QDpd78JUHpRP6bRRNyzbW3",
    "model": "claude-sonnet-4-5-20250929",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 25,
      "output_tokens": 19
    },
    "type": "message",
    "role": "assistant"
  },
  "usage_metadata": {
    "input_tokens": 25,
    "output_tokens": 19,
    "total_tokens": 44
  }
}

Sources: libs/providers/langchain-anthropic/src/chat_models.ts:1-100

AIMessageChunk

Used for streaming responses, representing incremental pieces of the complete response. Each chunk contains partial content that accumulates to form the full message.

AIMessageChunk {
  "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
  "content": "Here",
  "additional_kwargs": {
    "id": "msg_01N8MwoYxiKo9w4chE4gXUs4",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-5-20250929"
  },
  "usage_metadata": {
    "input_tokens": 25,
    "output_tokens": 1,
    "total_tokens": 26
  }
}

Sources: libs/providers/langchain-anthropic/src/chat_models.ts:1-100

Message Structure Types

The core message system defines flexible structures for tools and tool calls:

Sources: libs/langchain-core/src/messages/message.ts:1-100

Invocation Patterns

Single Invocation

The primary method for synchronous chat completion, accepting various input formats:

const input = `Translate "I love programming" into French.`;

// Models accept string, list of messages, or formatted prompt
const result = await llm.invoke(input);
console.log(result);

Sources: libs/providers/langchain-openai/src/chat_models/index.ts:1-100

Streaming

All chat models support streaming for real-time response generation:

for await (const chunk of await llm.stream(input)) {
  console.log(chunk);
}

Sources: libs/providers/langchain-anthropic/src/chat_models.ts:1-100

Tool Calling System

LangChain.js provides a unified tool calling abstraction that works across providers with provider-specific translations.

Tool Format Translation

The OpenAI provider demonstrates how tools are translated to provider-specific formats:

function convertToCustomTool(tool: FunctionDef & {
  description?: string;
  parameters?: JsonSchema;
}): IClient.Chat.ChatCompletionCustomTool {
  const getFormat = () => {
    if (!tool.format) {
      return undefined;
    }
    if (tool.format.type === "grammar") {
      return {
        type: "grammar" as const,
        grammar: {
          definition: tool.format.definition,
          syntax: tool.format.syntax,
        },
      };
    }
    if (tool.format.type === "text") {
      return {
        type: "text" as const,
      };
    }
    return undefined;
  };
  return {
    type: "custom",
    custom: {
      name: tool.name,
      description: tool.description,
      format: getFormat(),
    },
  };
}

Sources: libs/providers/langchain-openai/src/utils/tools.ts:1-50

Block Translators

Each provider implements block translators for converting between internal message formats and provider-specific APIs:

BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
  translateContentChunk: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletionsChunk(message);
    }
    return convertToV1FromResponsesChunk(message);
  },
};

Sources: libs/langchain-core/src/messages/block_translators/openai.ts:1-30

Provider Implementations

OpenAI

OpenAI's chat models use the Chat Completions API with comprehensive token usage tracking:

AIMessage {
  "id": "chatcmpl-9u4Mpu44CbPjwYFkTbeoZgvzB00Tz",
  "content": "J'adore la programmation.",
  "response_metadata": {
    "tokenUsage": {
      "completionTokens": 5,
      "promptTokens": 28,
      "totalTokens": 33
    },
    "finish_reason": "stop",
    "system_fingerprint": "fp_3aa7262c27"
  },
  "usage_metadata": {
    "input_tokens": 28,
    "output_tokens": 5,
    "total_tokens": 33
  }
}

Sources: libs/providers/langchain-openai/src/chat_models/index.ts:1-100

Anthropic

Anthropic's implementation includes cache control and extended reasoning features:

// System messages support array content for cache control
const systemMessage = new SystemMessage([
  { type: "text", text: "You are a helpful assistant." },
  { type: "cache_control", ... }
]);

Sources: libs/providers/langchain-anthropic/src/chat_models.ts:1-100

Ollama

Ollama provides local model hosting integration:

import { ChatOllama } from "@langchain/ollama";

const model = new ChatOllama({
  model: "llama3", // Default value.
});

const result = await model.invoke(["human", "Hello, how are you?"]);

Sources: libs/providers/langchain-ollama/README.md:1-50

Usage Metadata

All chat models track token usage consistently across providers:

Message Content Utilities

Standard Message Casting

The language models utility provides helpers for message handling:

function castStandardMessageContent<T extends BaseMessage>(message: T) {
  const Cls = message.constructor as Constructor<T>;
  return new Cls({
    ...message,
    content: message.contentBlocks,
    response_metadata: {
      ...message.response_metadata,
      output_version: "v1",
    },
  });
}

Sources: libs/langchain-core/src/language_models/utils.ts:1-30

Workflow: Stream Aggregation

For applications requiring the complete response after streaming:

import { AIMessageChunk } from '@langchain/core/messages';
import { concat } from '@langchain/core/utils';

// Stream and accumulate chunks
const stream = await llm.stream(input);
let fullResponse = new AIMessageChunk({ content: "" });

for await (const chunk of stream) {
  fullResponse = concat(fullResponse, chunk);
}

Sources: libs/providers/langchain-openai/src/chat_models/index.ts:1-100

Testing with Matchers

LangChain provides custom Jest matchers for testing chat model outputs:

import { langchainMatchers } from '@langchain/core/testing/matchers';

expect.extend(langchainMatchers);

// Common matchers
expect(message).toBeAIMessage();
expect(message).toBeHumanMessage();
expect(message).toHaveToolCalls([{ name: 'calculator' }]);
expect(response).toHaveStructuredResponse({ type: 'json' });

Sources: libs/langchain-core/src/testing/matchers.ts:1-100

Summary Table: Provider Capabilities

Common Configuration Parameters

See Also

• Base Chat Models Documentation
• Tool Calling Guide
• Streaming Guide
• Message Types Reference

Related Pages

Related topics: Vector Stores, Chat Models and LLM Providers

Embeddings Integration

Overview

Embeddings integration in LangChain.js provides a standardized interface for converting text into dense vector representations suitable for machine learning tasks. These embeddings enable semantic search, similarity comparison, and retrieval-augmented generation (RAG) pipelines.

LangChain.js supports multiple embedding providers through a unified Embeddings base class, allowing developers to swap between providers like OpenAI, AWS Bedrock, Cohere, Google Gemini, and Mistral without changing application code.

Sources: README.md:1-15

Architecture

Class Hierarchy

graph TD
    A[Embeddings Base Class] --> B[OpenAIEmbeddings]
    A --> C[AWS Embeddings]
    A --> D[Cohere Embeddings]
    A --> E[Google GenAI Embeddings]
    A --> F[Google VertexAI Embeddings]
    A --> G[Fireworks Embeddings]
    A --> H[MistralAI Embeddings]
    
    B --> I[Vector Store Integration]
    C --> I
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

Data Flow

graph LR
    A[Text Input] --> B[Embeddings.embedQuery]
    C[Document List] --> D[Embeddings.embedDocuments]
    B --> E[Vector Representation]
    D --> F[Batch Vector Output]
    E --> G[Vector Store]
    F --> G
    G --> H[Similarity Search]
    H --> I[Retrieved Results]

OpenAI Embeddings

Class Definition

The OpenAIEmbeddings class extends the base Embeddings class and implements the Partial<OpenAIEmbeddingsParams> interface. It provides access to OpenAI's embedding models including text-embedding-ada-002 and the newer text-embedding-3 series.

Sources: libs/providers/langchain-openai/src/embeddings.ts:1-50

Configuration Parameters

Sources: libs/providers/langchain-openai/src/embeddings.ts:30-60

Constructor Options

constructor(
  fields?: Partial<OpenAIEmbeddingsParams> & {
    verbose?: boolean;
    openAIApiKey?: OpenAIApiKey;
    apiKey?: OpenAIApiKey;
    configuration?: ClientOptions;
  }
)

The constructor accepts API keys through openAIApiKey or apiKey properties, and allows custom client configuration for advanced use cases like proxy settings or custom endpoints.

Sources: libs/providers/langchain-openai/src/embeddings.ts:50-70

Base Embeddings Interface

The Embeddings base class defines the contract that all embedding implementations must follow. It provides:

• embedQuery(text: string): Embed a single text string
• embedDocuments(texts: string[]): Embed multiple documents in batches

The base implementation handles batching logic, ensuring that large document sets are processed efficiently within the configured batchSize limits.

Integration with Vector Stores

MemoryVectorStore Example

The MemoryVectorStore class demonstrates typical embeddings integration patterns. It stores documents and performs similarity search using embedded vectors.

Sources: libs/langchain-classic/src/vectorstores/memory.ts:1-60

Usage Pattern

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

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vectorStore = new MemoryVectorStore(embeddings);

// Add documents
const documents = [
  { pageContent: "foo", metadata: { baz: "bar" } },
  { pageContent: "thud", metadata: { bar: "baz" } },
];

await vectorStore.addDocuments(documents);

// Search
const results = await vectorStore.similaritySearch("thud", 1);

Sources: libs/langchain-classic/src/vectorstores/memory.ts:30-55

Provider Implementations

Available Providers

Common Features

All embedding providers support:

• Single text embedding via embedQuery()
• Batch embedding via embedDocuments() with automatic batching
• Custom dimensions for supported models
• Configurable timeouts and API keys
• Streaming-compatible response handling

Batch Processing

Automatic Batching

The embeddings system automatically handles batching when processing large document sets. The default batch size is 512 documents, but this can be configured per instance.

const embeddings = new OpenAIEmbeddings({
  batchSize: 256, // Reduce for lower memory usage
});

Batch Size Considerations

Output Formats

Float Arrays

The default output format returns embeddings as float32 arrays:

const embedding = await embeddings.embedQuery("Hello world");
// Returns: number[]

Base64 Encoding

For reduced payload sizes, use base64 encoding:

const embeddings = new OpenAIEmbeddings({
  encodingFormat: "base64",
});

Sources: libs/providers/langchain-openai/src/embeddings.ts:45

Error Handling

Common Errors

Best Practices

Performance Optimization

1. Batch Operations: Always use embedDocuments() for multiple texts instead of calling embedQuery() in a loop
2. Dimension Selection: Use lower dimensions (256/512) when full precision isn't required
3. Connection Pooling: Reuse embedding instances across requests

Security Considerations

1. Store API keys in environment variables, never in source code
2. Use .env files with appropriate access controls
3. Set up API key restrictions in provider dashboards

Production Deployment

// Recommended production configuration
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
  batchSize: 512,
  dimensions: 1536,
  timeout: 60000,
});

Related Components

Text Splitters

Before embedding documents, use text splitters to break large texts into manageable chunks:

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

const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
  chunkSize: 175,
  chunkOverlap: 20,
});

const docs = await splitter.createDocuments([htmlContent]);
const embeddings = await embeddings.embedDocuments(docs.map(d => d.pageContent));

Sources: examples/src/langchain-classic/indexes/html_text_splitter.ts:1-25 Sources: libs/langchain-textsplitters/README.md:1-30

Message Translation

LangChain.js includes block translators for handling OpenAI message formats when working with embeddings in chat contexts:

BlockTranslator = {
  translateContent: (message) => {
    if (typeof message.content === "string") {
      return convertToV1FromChatCompletions(message);
    }
    return convertToV1FromResponses(message);
  },
};

Sources: libs/langchain-core/src/messages/block_translators/openai.ts:1-20

API Reference Summary

OpenAIEmbeddings Constructor

new OpenAIEmbeddings(fields?: Partial<OpenAIEmbeddingsParams>)

Methods

Environment Variables

Related Pages

Related topics: Tools and Toolkits, Chat Models and LLM Providers

Agent Framework

The LangChain.js Agent Framework provides a comprehensive, modular system for building autonomous and semi-autonomous agents that can reason about tasks, utilize tools, and interact with external environments. The framework is designed around the concept of agents as stateful, middleware-extensible runtime systems that coordinate between large language models (LLMs), tools, and human interventions.

Architecture Overview

The Agent Framework follows a layered architecture that separates concerns between agent definition, runtime execution, and middleware extension. At the core, agents are implemented as state machines that manage a series of steps, each potentially involving LLM calls, tool executions, and middleware hooks.

The architecture is built on several foundational components that work together to create a flexible agent system. The runtime layer manages the execution context, state transitions, and tool invocations, while the middleware layer provides hooks for observability, intervention, and customization at key points in the agent lifecycle.

The agent types themselves are modular, with different implementations optimized for various use cases—from classic ReAct-style reasoning agents to modern function-calling agents that leverage structured output capabilities from providers like OpenAI and Anthropic.

Core Components

Runtime System

The runtime system is the execution engine that orchestrates agent behavior. It maintains the agent state, manages step-by-step execution, handles tool calls, and integrates middleware for extensibility. The runtime provides a clean interface for starting, pausing, resuming, and terminating agent executions.

The runtime is responsible for managing the agent's internal memory and context across multiple steps, ensuring that observations from previous tool executions are properly passed back to the LLM for the next reasoning cycle. This cyclical pattern of reasoning, action, and observation forms the fundamental loop of agent execution.

graph TD
    A[User Input] --> B[Runtime Engine]
    B --> C[LLM Reasoning]
    C --> D{Tool Call?}
    D -->|Yes| E[Execute Tool]
    E --> F[Get Observation]
    F --> B
    D -->|No| G[Final Response]
    B --> H[Middleware Hooks]
    H --> I[Logging/Observability]
    H --> J[Human-in-the-Loop]
    H --> K[Custom Logic]

Action Interface

Actions represent the fundamental unit of work that an agent can perform. The Action interface defines what an agent can request, including the action name and associated arguments:

export interface Action {
  /**
   * The type or name of action being requested (e.g., "add_numbers").
   */
  name: string;
  /**
   * Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2}).
   */
  args: Record<string, any>;
}

This abstraction allows the framework to treat all agent actions uniformly, whether they represent tool invocations, control flow operations, or communication with external systems. The args field uses a flexible Record structure to accommodate any argument types required by different tools.

Agent Nodes

The agent node system provides a structured way to define the behavior and capabilities of agents. Node types define the available operations, their parameters, and how they should be executed within the agent's runtime context.

The node type definitions establish a contract for what actions an agent can perform, ensuring type safety and providing documentation for available capabilities. Each node type can define its own schema for arguments, return types, and execution behavior.

Middleware System

Middleware in the Agent Framework operates as a plugin system that intercepts and can modify agent behavior at defined points in the execution lifecycle. This pattern enables cross-cutting concerns like logging, monitoring, security, and human oversight without coupling these concerns to the core agent logic.

Middleware Architecture

The middleware system follows a chain-of-responsibility pattern where each middleware component can inspect, modify, or terminate agent operations. Middleware is applied at key lifecycle points including before and after LLM calls, before and after tool executions, and at state transitions.

Middleware components receive context about the current operation, including the agent's state, the action being performed, and any intermediate results. This rich context enables sophisticated decision-making within middleware handlers.

Human-in-the-Loop (HITL) Middleware

The HITL middleware provides a mechanism for human oversight and intervention in agent execution. This is particularly valuable for production systems where agent actions need validation before execution, or where humans should have the ability to redirect agent behavior.

The HITL middleware is configured through the InterruptOnConfig interface:

export const InterruptOnConfigSchema = z.object({
  /**
   * When true, interrupts execution before the action runs.
   * When false, interrupts after the action runs.
   */
  interruptBefore: z.boolean().optional(),
  /**
   * When true, waits for human approval before continuing.
   * When false, triggers the interrupt but allows automatic continuation.
   */
  waitForApproval: z.boolean().optional(),
  /**
   * List of action names that should trigger interrupts.
   * If undefined, all actions trigger interrupts.
   */
  allowedDecisions: z.array(z.string()).optional(),
  /**
   * Dynamic callable description
   */
  description: z.union([z.string(), DescriptionFunctionSchema]).optional(),
  /**
   * JSON schema for the arguments associated with the action, if edits are allowed.
   */
  argsSchema: z.record(z.any()).optional(),
});

The configuration supports several operation modes. When interruptBefore is true, execution pauses before the action runs, allowing review of the planned action. When false, the action executes first and then interrupts, enabling review of both the action and its results. The allowedDecisions array restricts which actions trigger interrupts, allowing fine-grained control over when human oversight is required.

The description field accepts either a static string or a dynamic function that generates descriptions at runtime. This is useful for providing contextual information about actions:

const formatToolDescription: DescriptionFactory = (
  toolCall: ToolCall,
  state: AgentBuiltInState,
  runtime: Runtime<unknown>
) => {
  return `Tool: ${toolCall.name}\nArguments:\n${JSON.stringify(toolCall.args, null, 2)}`;
};

const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription
};

Agent Types

The Agent Framework supports multiple agent implementations, each optimized for different reasoning patterns and use cases.

ReAct Agent

The ReAct (Reasoning + Acting) agent implements the classic ReAct pattern where the agent alternates between reasoning steps and action execution. This agent type is particularly effective for tasks requiring multi-step reasoning with tool usage.

The ReAct agent formats its reasoning in a structured scratchpad that combines observations, thoughts, and actions. The XML formatter provides a standardized way to represent this reasoning trace:

export function formatXml(intermediateSteps: AgentStep[]) {
  let log = "";
  for (const step of intermediateSteps) {
    const { action, observation } = step;
    log += `<tool>${action.tool}</tool><tool_input>${action.toolInput}\n</tool_input><observation>${observation}</observation>`;
  }
  return log;
}

This XML format enables the LLM to easily parse and reason about previous actions and their outcomes, maintaining a clear trace of the agent's reasoning chain.

OpenAI Functions Agent

The OpenAI Functions agent leverages OpenAI's function calling capability to constrain agent outputs to a specific set of tool definitions. This approach provides more reliable tool selection compared to open-ended generation, as the LLM must choose from the provided function schemas.

The agent passes tool definitions directly to the OpenAI API, which returns structured function calls. This eliminates the need for parsing unstructured text and reduces the likelihood of malformed tool invocations.

OpenAI Tools Agent

The OpenAI Tools agent is an evolution of the functions agent that uses a more flexible tool definition format. It supports both the traditional function calling interface and newer tool-use patterns, providing compatibility across different OpenAI model versions.

This agent type is recommended for new projects using OpenAI models, as it supports the latest tool-use capabilities and provides better compatibility with models that have tool-use fine-tuning.

Structured Chat Agent

The Structured Chat agent uses structured output parsing to extract tool calls from LLM responses. This approach works with any LLM that supports structured output, not just providers with native function calling support.

The agent defines a JSON schema for valid actions and uses parsing techniques to extract tool calls from the text response. This provides flexibility in model choice while maintaining reliable tool usage.

Event System

The agent framework includes a comprehensive event system for monitoring and debugging agent execution. Events are emitted at key points in the agent lifecycle, allowing external systems to observe and respond to agent behavior.

The event system is designed to work seamlessly with streaming responses, where content may arrive incrementally. Events include positional indices and delta information that enable proper reconstruction of complete responses.

Streaming Support

Agents support streaming responses through the runtime's streaming capabilities. Streaming is particularly valuable for long-running agent tasks where users benefit from seeing partial results as they become available.

The streaming implementation works by emitting events as the agent produces output. These events can be consumed incrementally, allowing applications to display results in real-time without waiting for complete agent execution.

Configuration and Integration

Tool Configuration

Tools are passed to agents at initialization and define the actions available to the agent. Each tool has a name, description, and schema that describes its arguments. The schema is typically defined using Zod for runtime type validation.

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);

Provider Configuration

Agents can be configured with any LLM provider that LangChain.js supports. The provider configuration includes API keys, model selection, and provider-specific parameters:

import { ChatAnthropicMessages } from "@langchain/langchain-anthropic";
import { ChatOpenAI } from "@langchain/langchain-openai";

const anthropicAgent = createAgent({
  llm: new ChatAnthropicMessages({ model: "claude-sonnet-4-5-20250929" }),
  tools: [getWeather, searchTool],
});

const openaiAgent = createAgent({
  llm: new ChatOpenAI({ model: "gpt-4" }),
  tools: [getWeather, searchTool],
});

Migration from Legacy Agents

The @langchain/classic package provides backward compatibility for legacy agent types that were part of LangChain v0.x. These include LLMChain, ConversationalRetrievalQAChain, and RetrievalQAChain.

For new projects, the recommended approach is to use the new createAgent API from the main langchain package. This provides better performance, cleaner abstractions, and access to middleware capabilities that are not available in the legacy agents.

The legacy agents will continue to be supported but will not receive new features. Applications should plan to migrate to the new API over time, taking advantage of improvements in the agent framework.

Best Practices

When building agents with the LangChain.js Agent Framework, several practices help ensure reliable and maintainable implementations. Tool definitions should include clear, descriptive names and comprehensive descriptions that help the LLM understand when and how to use each tool. Argument schemas should validate inputs and provide clear error messages when invalid arguments are passed.

Middleware should be used judiciously to avoid performance impacts. For high-volume production systems, consider which middleware operations can be performed asynchronously or in batch mode. Human-in-the-loop configurations should be tested thoroughly to ensure the interrupt flow matches expected user interactions.

Agent state should be monitored and logged appropriately. The event system provides hooks for integrating with observability platforms, enabling debugging and performance analysis of agent behavior in production environments.

Related Pages

Related topics: Agent Framework, Memory Systems

Tools and Toolkits

Overview

In LangChain.js, Tools and Toolkits form the fundamental building blocks that enable Large Language Models (LLMs) to interact with external systems, APIs, databases, and web resources. Tools provide a standardized interface for defining callable functions that models can invoke during their reasoning process, while Toolkits bundle collections of related tools into cohesive units optimized for specific use cases.

The architecture follows a clear separation between individual tool implementations and composed toolkit aggregations, allowing developers to use built-in tools, create custom tools, or assemble pre-built toolkits for common workflows.

Core Concepts

What Are Tools?

Tools in LangChain.js are essentially callable functions with structured metadata that enables LLMs to understand when and how to use them. Each tool consists of:

What Are Toolkits?

Toolkits are pre-configured collections of related tools designed to work together for specific domains or workflows. They provide:

• Optimized tool combinations for common tasks
• Shared initialization logic and configuration
• Coordinated error handling and retry strategies
• Consistent authentication patterns where applicable

Tool Architecture

Base Tool Implementation

The foundational tool abstraction in LangChain.js is defined in libs/langchain-classic/src/tools/base.ts. All custom and built-in tools inherit from or conform to this interface.

graph TD
    A[BaseTool Abstract Class] --> B[StructuredTool]
    A --> C[Tool Interface]
    B --> D[Custom Tool Implementations]
    C --> E[Dynamic Tool]
    D --> F[SQL Tool]
    D --> G[Web Browser Tool]

Tool Creation Patterns

LangChain.js supports multiple patterns for creating tools:

#### 1. Function-Based Tool Definition

The tool() function from @langchain/core/tools provides a concise API for defining tools:

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

const getWeather = tool(
  async (input) => `Weather in ${input.location}`,
  {
    name: "get_weather",
    description: "Get weather for a location",
    schema: z.object({ location: z.string() }),
  }
);

#### 2. Dynamic Tool Creation

Dynamic tools allow runtime tool creation, useful for scenarios where tool definitions are not known at compile time. The implementation in libs/langchain-classic/src/tools/dynamic.ts provides the DynamicTool class.

Sources: libs/langchain-classic/src/tools/dynamic.ts:1-50

#### 3. Tool with Extra Parameters

Tools can include additional configuration through the extras field:

const deferredTool = tool(
  async (input) => `Result: ${input.query}`,
  {
    name: "deferred_search",
    description: "Search tool with deferred loading",
    schema: z.object({ query: z.string() }),
    extras: { defer_loading: true },
  }
);

Sources: libs/providers/langchain-openai/src/tools/index.ts:1-30

Built-in Tools

SQL Tool

The SQL Tool enables LLM agents to query relational databases using natural language. It accepts raw SQL queries and returns structured results.

Sources: libs/langchain-classic/src/tools/sql.ts:1-80

Web Browser Tool

The Web Browser Tool allows agents to navigate websites, extract content, and interact with web resources. It simulates browser operations including page navigation, content extraction, and element interaction.

graph LR
    A[User Query] --> B[WebBrowserTool]
    B --> C{Action Type}
    C -->|navigate| D[Load URL]
    C -->|extract| E[Parse Content]
    C -->|interact| F[Click/Type]
    D --> G[HTML Response]
    E --> H[Extracted Data]
    F --> I[Interaction Result]

Sources: libs/langchain-classic/src/tools/webbrowser.ts:1-100

Toolkits

SQL Toolkit

The SQL Toolkit bundles tools for database operations, including query execution, table inspection, and schema understanding. Located at libs/langchain-classic/src/agents/toolkits/sql/sql.ts, it provides:

Sources: libs/langchain-classic/src/agents/toolkits/sql/sql.ts:1-150

OpenAPI Toolkit

The OpenAPI Toolkit enables agents to interact with REST APIs defined in OpenAPI specifications. It parses OpenAPI documents and generates corresponding tools.

graph TD
    A[OpenAPI Spec] --> B[OpenAPIToolkit]
    B --> C[HTTP GET Tool]
    B --> D[HTTP POST Tool]
    B --> E[HTTP PUT Tool]
    B --> F[HTTP DELETE Tool]
    C --> G[API Response]
    D --> G
    E --> G
    F --> G

Sources: libs/langchain-classic/src/agents/toolkits/openapi/openapi.ts:1-120

Vector Store Toolkit

The Vector Store Toolkit provides tools for similarity search and document retrieval from vector databases. This is commonly used in Retrieval Augmented Generation (RAG) pipelines.

Sources: libs/langchain-classic/src/agents/toolkits/vectorstore/vectorstore.ts:1-100

Integration with Agents

Tools and Toolkits are primarily consumed by LangChain agents. The agent runtime coordinates tool selection, execution, and result handling.

graph TD
    A[User Input] --> B[Agent]
    B --> C[LLM Reasoning]
    C --> D{Tool Call?}
    D -->|Yes| E[Select Tool]
    E --> F[Execute Tool]
    F --> G[Return Result]
    G --> C
    D -->|No| H[Final Response]

Tool Calling Configuration

Agents can be configured to use tools with various parameters:

const config: InterruptOnConfig = {
  allowedDecisions: ["approve", "edit"],
  description: formatToolDescription
};

Sources: libs/langchain/src/agents/middleware/hitl.ts:1-50

Best Practices

Tool Design Guidelines

1. Clear Descriptions: Write unambiguous tool descriptions that help the LLM understand when to invoke the tool
2. Strict Schemas: Use Zod schemas to validate inputs and prevent errors
3. Error Handling: Return meaningful error messages that guide the agent toward recovery
4. Idempotency: Design tools to be safely re-callable when needed
5. Resource Management: Properly dispose of connections and resources after tool execution

Toolkit Organization

Conclusion

Tools and Toolkits in LangChain.js provide a powerful abstraction for extending LLM capabilities beyond text generation. By leveraging the standardized tool interface, developers can create reusable components that integrate seamlessly with agent workflows, enabling sophisticated AI applications that interact with databases, APIs, web resources, and more.

Related Pages

Related topics: Embeddings Integration

Vector Stores

Vector stores are a core component in LangChain.js that enable efficient similarity search over embedded data. They serve as the persistence layer for vector embeddings in retrieval-augmented generation (RAG) pipelines, allowing developers to store, index, and query high-dimensional vectors representing documents, text chunks, or other data.

Overview

LangChain.js provides a unified interface for interacting with multiple vector database backends through the @langchain/core package. This abstraction enables developers to switch between different vector store implementations without changing their application code.

graph TD
    A[Documents] --> B[Text Embedding Models]
    B --> C[Vector Embeddings]
    C --> D[Vector Store]
    E[Query] --> F[Embed Query]
    F --> G[Similarity Search]
    G --> H[Retrieved Documents]
    
    D --> I[Pinecone]
    D --> J[Qdrant]
    D --> K[Weaviate]
    D --> L[Redis]
    D --> M[MongoDB]
    D --> N[Neo4j]
    D --> O[PGVector]
    D --> P[Memory]

Supported Vector Stores

LangChain.js integrates with the following vector database providers:

Sources: libs/providers/langchain-pinecone/README.md Sources: libs/providers/langchain-qdrant/README.md

Core Interface

All vector stores in LangChain.js implement a common interface defined in @langchain/core/vectorstores. This interface ensures consistency across different implementations while allowing provider-specific features.

Key Methods

Sources: libs/langchain-classic/src/vectorstores/memory.ts

Usage Patterns

Basic Similarity Search

The following example demonstrates the typical workflow for performing similarity search using the MemoryVectorStore:

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

const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vectorStore = new MemoryVectorStore(embeddings);

// Add documents
const document1 = { pageContent: "foo", metadata: { baz: "bar" } };
const document2 = { pageContent: "thud", metadata: { bar: "baz" } };
const documents = [document1, document2];

await vectorStore.addDocuments(documents);

// Perform similarity search
const results = await vectorStore.similaritySearch("thud", 1);

for (const doc of results) {
  console.log(`* ${doc.pageContent} [${JSON.stringify(doc.metadata, null)}]`);
}

Sources: libs/langchain-classic/src/vectorstores/memory.ts

Installation

Each vector store package has specific installation requirements:

#### Pinecone

npm install @langchain/pinecone @langchain/core @pinecone-database/pinecone

Sources: libs/providers/langchain-pinecone/README.md

#### Qdrant

npm install @langchain/qdrant

Sources: libs/providers/langchain-qdrant/README.md

#### PGVector

The PostgreSQL vector extension requires a running PostgreSQL instance with pgvector installed:

npm install @langchain/pgvector pg

Architecture

Document Model

LangChain.js uses a standardized Document interface for representing content:

interface Document {
  pageContent: string;    // The text content
  metadata: Record<string, any>;  // Associated metadata
}

Documents are processed through embedding models to generate vector representations before storage.

Embedding Integration

Vector stores work in conjunction with embedding models from @langchain/core or provider-specific embedding implementations. The embedding model is passed during vector store initialization and is used to:

1. Generate vectors for incoming documents during addDocuments()
2. Generate vectors for query strings during search operations

sequenceDiagram
    participant App as Application
    participant VS as Vector Store
    participant EM as Embedding Model
    participant DB as Database
    
    App->>VS: addDocuments(documents)
    VS->>EM: embedDocuments(documents)
    EM-->>VS: embeddings
    VS->>DB: store(embeddings + docs)
    
    App->>VS: similaritySearch(query)
    VS->>EM: embedQuery(query)
    EM-->>VS: queryVector
    VS->>DB: findSimilar(queryVector)
    DB-->>VS: results
    VS-->>App: documents

Provider-Specific Implementations

Neo4j Vector Store

The Neo4j integration leverages graph database capabilities for vector storage, enabling hybrid queries that combine vector similarity with graph traversal:

import { Neo4jVectorStore } from '@langchain/neo4j';

Sources: libs/providers/langchain-neo4j/src/vectorstores/neo4j_vector.ts

Weaviate

Weaviate provides hybrid search capabilities combining vector similarity with keyword matching:

import { WeaviateVectorStore } from '@langchain/weaviate';

Sources: libs/providers/langchain-weaviate/src/vectorstores.ts

Redis

Redis vector store offers high-performance in-memory vector operations with built-in pub/sub capabilities:

import { RedisVectorStore } from '@langchain/redis';

Sources: libs/providers/langchain-redis/src/vectorstores.ts

MongoDB Atlas

MongoDB Atlas provides vector search through its Atlas Search feature, integrated via the official MongoDB driver:

import { MongoDBAtlasVectorSearch } from '@langchain/mongodb';

Sources: libs/providers/langchain-mongodb/src/vectorstores.ts

Development Guidelines

Adding New Vector Stores

LangChain.js provides a template for creating new vector store integrations. See the official integration template for the required structure:

Sources: libs/create-langchain-integration/template/README.md

Package Structure

Each vector store package should follow the LangChain.js monorepo conventions:

Testing

Vector store implementations require both unit tests (.test.ts) and integration tests (.int.test.ts):

pnpm test
pnpm test:int

Common Configuration Options

While specific options vary by provider, most vector stores support these common parameters:

Best Practices

1. Embedding Model Consistency: Always use the same embedding model for indexing and querying to ensure vector compatibility.

1. Metadata Indexing: Include relevant metadata during document storage to enable filtered searches.

1. Batch Operations: Use batch operations (addDocuments) rather than single document additions for better performance.

1. Connection Management: Follow provider-specific connection pooling and timeout configurations in production environments.

1. Dimension Matching: Ensure your embedding model dimensions match the vector store's expected configuration.

Related Components

Vector stores are typically used in combination with:

• Document Loaders: Load documents from various sources
• Text Splitters: Split large documents into searchable chunks
• Retrieval Chains: Combine vector stores with language models for RAG
• Memory Systems: Persist conversation context using vector storage

Related Pages

Related topics: Agent Framework

I cannot generate an accurate technical wiki page about Memory Systems because the provided repository context does not contain the actual source files for memory implementations.

The requested source files are not present in the retrieved context:

• libs/langchain-classic/src/memory/buffer_memory.ts
• libs/langchain-classic/src/memory/buffer_window_memory.ts
• libs/langchain-classic/src/memory/summary_buffer.ts
• libs/langchain-classic/src/memory/entity_memory.ts
• libs/langchain-classic/src/memory/vector_store.ts
• libs/langchain-core/src/memory.ts
• libs/langchain-core/src/chat_history.ts

The context only contains files related to:

• HTML text splitting
• Agent HITL middleware
• Anthropic/OpenAI chat models
• SHA256 hashing utilities
• Vector store memory (partial)
• Computer use tools
• Language model utilities
• Agent streaming

To generate an accurate wiki page, I would need access to the actual memory module source files.

Doramagic Pitfall Log

Doramagic extracted 10 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: [Feature request] React Native support

• Severity: high
• Finding: Configuration risk is backed by a source signal: [Feature request] React Native support. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/langchain-ai/langchainjs/issues/4239

2. Installation risk: @langchain/[email protected]

• Severity: medium
• Finding: Installation risk is backed by a source signal: @langchain/[email protected]. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46

3. Configuration risk: Must pass in at least 1 record to upsert.

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Must pass in at least 1 record to upsert.. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/langchain-ai/langchainjs/issues/10890

4. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.

5. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

7. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium

8. Security or permission risk: bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/langchain-ai/langchainjs/issues/10894

9. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown

10. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using langchainjs with real data or production workflows.

• [[Feature request] React Native support](https://github.com/langchain-ai/langchainjs/issues/4239) - github / github_issue
• bug(@langchain/openai): Bare JSON.parse in Responses API converter crash - github / github_issue
• Must pass in at least 1 record to upsert. - github / github_issue
• @langchain/[email protected] - github / github_release
• @langchain/[email protected] - github / github_release
• @langchain/[email protected] - github / github_release
• README/documentation is current enough for a first validation pass. - GitHub / issue