langchain-ai/langchain

v1 migration

The largest architectural change in LangChain's history happened in late 2025–early 2026: the langchain package was rewritten from scratch and the old implementation was renamed to langchain-classic. This page summarizes what changed, why, and how to migrate.

What was renamed

Before	After
`langchain` (the package)	`langchain-classic` (PyPI distribution: `langchain-classic`)
`import langchain`	`import langchain_classic`
Source in `libs/langchain/`	Source still in `libs/langchain/`, but now the importable package is `langchain_classic`
(new)	`langchain` (the package) — source in `libs/langchain_v1/langchain/`

The directory layout is intentionally confusing because directly renaming libs/langchain/ would have broken every editable install in the wild. The convention is:

libs/langchain_v1/langchain/ ships the langchain PyPI distribution (the new package).
libs/langchain/langchain_classic/ ships the langchain-classic PyPI distribution (the old package).

What `langchain` (v1) gained

The new package is intentionally small (~33 source files vs. ~1,322 in langchain-classic). It focuses on three things:

create_agent — a langgraph-backed agent factory (details).
Middleware — a composable plugin system for cross-cutting agent behavior (details).
init_chat_model — a provider-agnostic factory that lazily imports the right partner package.

Everything else moved to either:

langchain-core (base abstractions).
langchain-classic (legacy chains, agents, retrievers, evaluation, …).
langgraph (graph orchestration).
Partner packages (provider integrations).

What changed in `langchain-core`

Three big shifts:

1. Content blocks v1

AIMessage.content used to be a str or a list of OpenAI-style dicts. v1 introduces a typed taxonomy:

TextContentBlock, ImageContentBlock, AudioContentBlock, VideoContentBlock, FileContentBlock
ReasoningContentBlock for o-series, Claude extended thinking, DeepSeek R1
ServerToolCall, ServerToolCallChunk, ServerToolResult for provider-side tools (OpenAI web search, Anthropic computer use)
Citation, Annotation for grounded responses
NonStandardContentBlock, NonStandardAnnotation as escape hatches

Every partner now translates between provider shapes and these blocks. See primitives/messages for the full taxonomy.

2. `BaseChatModelV1`

The streaming-first chat-model contract. Lives in libs/core/langchain_core/language_models/chat_model_stream.py. BaseChatModel (the legacy contract) is still supported via _compat_bridge.py. New partners are encouraged to implement BaseChatModelV1 directly.

3. Model profiles

langchain-model-profiles (CLI in libs/model-profiles/langchain_model_profiles/cli.py) keeps capability data in sync across all partner integrations. Runtime code reads it through BaseChatModel.profile.

Migration recipes

From `LLMChain` to LCEL

# Before
from langchain.chains import LLMChain
chain = LLMChain(llm=model, prompt=prompt, output_parser=parser)
chain.run({"input": "..."})

# After
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
chain = prompt | model | StrOutputParser()
chain.invoke({"input": "..."})

From `AgentExecutor` to `create_agent`

# Before
from langchain.agents import AgentExecutor, create_react_agent
agent = create_react_agent(model, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
executor.invoke({"input": "..."})

# After
from langchain.agents import create_agent
agent = create_agent(model=model, tools=tools)
agent.invoke({"messages": [{"role": "user", "content": "..."}]})

From `Memory` to LangGraph checkpointer

Legacy Memory classes (ConversationBufferMemory, ConversationSummaryMemory, …) are superseded by LangGraph's checkpointer + agent state. Most users get better results by:

Passing a checkpointer= to create_agent.
Letting the agent's state["messages"] accumulate the conversation.
Adding SummarizationMiddleware if the conversation grows long.

From `langchain.chat_models` to partner packages

# Before
from langchain.chat_models import ChatOpenAI

# After
from langchain_openai import ChatOpenAI
# or, provider-agnostic:
from langchain.chat_models import init_chat_model
model = init_chat_model("openai:gpt-5")

The partner-package import has been the recommended path since 2024; the new langchain package only re-exports init_chat_model.

What stayed

A lot stayed put. langchain-core's public surface — Runnable, messages, BaseChatModel, BaseTool, prompts, output parsers, callbacks — is largely unchanged. Existing LCEL chains continue to work. Partner packages continue to expose their classes via the same imports.

The biggest break in user-facing code was that chains and agents from the old package needed to migrate to LCEL or create_agent. For users who can't migrate, langchain-classic is supported indefinitely.

Why

A few forces drove the rewrite:

LangGraph maturity. Once langgraph was stable and ergonomic, it became the better foundation for agents than the legacy AgentExecutor loop.
Middleware as the extension story. The legacy callback system was good for observation, bad for behavior modification. A typed middleware ABI lets users add summarization, retries, HITL, redaction, etc. without forking.
Content blocks for new model capabilities. Reasoning, server-side tools, citations, and rich multimodal content didn't fit in Union[str, list[dict]]. A typed taxonomy unblocks new partner features.
Smaller surface area. The new langchain package can be reviewed end-to-end in an afternoon. The old one had grown to a monolith that took weeks to internalize.

Compatibility

The new langchain==1.x package can be installed alongside langchain-classic==1.x. They share langchain-core and don't conflict on top-level names.
Partner packages support both — every partner's BaseChatModel subclass works whether you call it from a v1 agent or a classic chain.
Both packages' release tracks continue: langchain==1.2.x, langchain-classic==1.0.x, langchain-core==1.3.x as of this writing.