LangChain Upgrade Migration

Current State

!npm list @langchain/core @langchain/openai 2>/dev/null | head -10

Overview

Safely upgrade LangChain versions: check compatibility, migrate import paths, convert legacy chains to LCEL, update agent APIs, and validate with tests.

Breaking Changes Timeline

0.1.x to 0.2.x (Major Restructuring)

• @langchain/core extracted as separate package
• Chat models moved to provider packages (@langchain/openai, @langchain/anthropic)
• Imports changed from langchain/ to @langchain/core/

0.2.x to 0.3.x (LCEL Standardization)

• Legacy LLMChain, ConversationChain deprecated
• initialize_agent deprecated (use createToolCallingAgent)
• Memory API: ConversationBufferMemory replaced by RunnableWithMessageHistory
• All chains should use LCEL pipe syntax

Step 1: Check Current Versions

# Node.js
npm ls @langchain/core @langchain/openai langchain 2>&1 | head -20

# Python
pip show langchain langchain-core langchain-openai | grep -E "Name|Version"

Step 2: Migrate Import Paths (TypeScript)

// OLD (pre-0.2)
import { ChatOpenAI } from "langchain/chat_models/openai";
import { PromptTemplate } from "langchain/prompts";
import { LLMChain } from "langchain/chains";
import { BufferMemory } from "langchain/memory";

// NEW (0.3+)
import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";
// LLMChain replaced by LCEL: prompt.pipe(model).pipe(parser)

# OLD (pre-0.2)
from langchain.chat_models import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain

# NEW (0.3+)
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

Step 3: Convert LLMChain to LCEL

// OLD: LLMChain (deprecated)
import { LLMChain } from "langchain/chains";
const chain = new LLMChain({ llm, prompt });
const result = await chain.call({ input: "hello" });

// NEW: LCEL pipe syntax
import { StringOutputParser } from "@langchain/core/output_parsers";
const chain = prompt.pipe(model).pipe(new StringOutputParser());
const result = await chain.invoke({ input: "hello" });

# OLD
from langchain.chains import LLMChain
chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run(input="hello")

# NEW
chain = prompt | llm | StrOutputParser()
result = chain.invoke({"input": "hello"})

Step 4: Migrate Agents

// OLD: initialize_agent (deprecated)
import { initializeAgentExecutorWithOptions } from "langchain/agents";
const executor = await initializeAgentExecutorWithOptions(tools, llm, {
  agentType: "chat-conversational-react-description",
});

// NEW: createToolCallingAgent
import { createToolCallingAgent, AgentExecutor } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant."],
  new MessagesPlaceholder("chat_history"),
  ["human", "{input}"],
  new MessagesPlaceholder("agent_scratchpad"),
]);

const agent = createToolCallingAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

Step 5: Migrate Memory

// OLD: BufferMemory (deprecated)
import { BufferMemory } from "langchain/memory";
const memory = new BufferMemory();
const chain = new ConversationChain({ llm, memory });

// NEW: RunnableWithMessageHistory
import { RunnableWithMessageHistory } from "@langchain/core/runnables";
import { ChatMessageHistory } from "@langchain/community/stores/message/in_memory";

const store = new Map<string, ChatMessageHistory>();

function getHistory(sessionId: string) {
  if (!store.has(sessionId)) store.set(sessionId, new ChatMessageHistory());
  return store.get(sessionId)!;
}

const chainWithHistory = new RunnableWithMessageHistory({
  runnable: chain,
  getMessageHistory: getHistory,
  inputMessagesKey: "input",
  historyMessagesKey: "history",
});

await chainWithHistory.invoke(
  { input: "Hello" },
  { configurable: { sessionId: "user-1" } }
);

Step 6: Upgrade Packages

# Node.js — update all @langchain/* together
npm install @langchain/core@latest @langchain/openai@latest langchain@latest

# Verify no version conflicts
npm ls @langchain/core

# Python
pip install --upgrade langchain langchain-core langchain-openai langchain-community
pip show langchain langchain-core | grep Version

Step 7: Run Tests and Check Deprecations

# TypeScript
npx vitest run
npx tsc --noEmit

# Python — check for deprecation warnings
pytest tests/ -W error::DeprecationWarning -v

Migration Checklist

• [ ] Current versions documented
• [ ] Breaking changes reviewed for your version jump
• [ ] All langchain/ imports updated to @langchain/core/ or provider packages
• [ ] LLMChain replaced with LCEL .pipe() chains
• [ ] initializeAgent replaced with createToolCallingAgent
• [ ] BufferMemory replaced with RunnableWithMessageHistory
• [ ] All @langchain/* packages on compatible versions
• [ ] Tests passing
• [ ] No deprecation warnings
• [ ] Staging validation complete

Error Handling

Resources

• LangChain.js Migration Guide
• Python Migration Guide
• Release Notes

Next Steps

After upgrade, use langchain-common-errors to troubleshoot any issues.