LangChain Upgrade Migration

LangChain Upgrade Migration

Overview

Guide for upgrading LangChain versions safely with migration strategies for breaking changes.

Prerequisites

• Existing LangChain application
• Version control with current code committed
• Test suite covering core functionality
• Staging environment for validation

Instructions

Step 1: Check Current Versions

pip show langchain langchain-core langchain-openai langchain-community

# Output current requirements
pip freeze | grep -i langchain > langchain_current.txt

Step 2: Review Breaking Changes

# Key breaking changes by version:

# 0.1.x -> 0.2.x (Major restructuring)
# - langchain-core extracted as separate package
# - Imports changed from langchain.* to langchain_core.*
# - ChatModels moved to provider packages

# 0.2.x -> 0.3.x (LCEL standardization)
# - Legacy chains deprecated
# - AgentExecutor changes
# - Memory API updates

# Check migration guides:
# https://python.langchain.com/​docs/​versions/​migrating_chains/

Step 3: Update Import Paths

# 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

# Migration script
import re

def migrate_imports(content: str) -> str:
    """Migrate old imports to new pattern."""
    migrations = [
        (r"from langchain\.chat_models import ChatOpenAI",
         "from langchain_openai import ChatOpenAI"),
        (r"from langchain\.llms import OpenAI",
         "from langchain_openai import OpenAI"),
        (r"from langchain\.prompts import",
         "from langchain_core.prompts import"),
        (r"from langchain\.schema import",
         "from langchain_core.messages import"),
        (r"from langchain\.callbacks import",
         "from langchain_core.callbacks import"),
    ]
    for old, new in migrations:
        content = re.sub(old, new, content)
    return content

Step 4: Migrate Legacy Chains to LCEL

# OLD: LLMChain (deprecated)
from langchain.chains import LLMChain

chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run(input="hello")

# NEW: LCEL (LangChain Expression Language)
from langchain_core.output_parsers import StrOutputParser

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

Step 5: Migrate Agents

# OLD: initialize_agent (deprecated)
from langchain.agents import initialize_agent, AgentType

agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
)

# NEW: create_tool_calling_agent
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

Step 6: Migrate Memory

# OLD: ConversationBufferMemory
from langchain.memory import ConversationBufferMemory

memory = ConversationBufferMemory()
chain = LLMChain(llm=llm, prompt=prompt, memory=memory)

# NEW: RunnableWithMessageHistory
from langchain_core.chat_history import BaseChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_community.chat_message_histories import ChatMessageHistory

store = {}

def get_session_history(session_id: str) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = ChatMessageHistory()
    return store[session_id]

chain_with_history = RunnableWithMessageHistory(
    chain,
    get_session_history,
    input_messages_key="input",
    history_messages_key="history"
)

Step 7: Upgrade Packages

# Create backup of current environment
pip freeze > requirements_backup.txt

# Upgrade to latest stable
pip install --upgrade langchain langchain-core langchain-openai langchain-community

# Or specific version
pip install langchain==0.3.0 langchain-core==0.3.0

# Verify versions
pip show langchain langchain-core

Step 8: Run Tests

# Run test suite
pytest tests/ -v

# Check for deprecation warnings
pytest tests/ -W error::DeprecationWarning

# Run type checking
mypy src/

Migration Checklist

• Current version documented
• Breaking changes reviewed
• Imports updated
• LLMChain -> LCEL migrated
• Agent initialization updated
• Memory patterns updated
• Tests passing
• Staging validation complete

Error Handling

Resources

• LangChain Migration Guide
• LCEL Documentation
• Release Notes
• Deprecation Timeline

Next Steps

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