Migrate a LangChain 0.3.x Python codebase to LangChain 1.0 / LangGraph 1.0 without
breaking production — named breaking changes, codemod patterns, and a phased rollout.
Use when upgrading LangChain or LangGraph from 0.2 or 0.3 to 1.0, when hitting
ImportError after an upgrade, or when preparing a migration PR.
Trigger with "langchain 1.0 migration", "langchain upgrade", "LLMChain removed",
"initialize_agent removed", "ConversationBufferMemory removed", "astream_log deprecated",
"langchain-anthropic 1.0".
Migrate a LangChain 0.3.x Python codebase to LangChain 1.0 / LangGraph 1.0 without
breaking production — named breaking changes, codemod patterns, and a phased rollout.
Use when upgrading LangChain or LangGraph from 0.2 or 0.3 to 1.0, when hitting
ImportError after an upgrade, or when preparing a migration PR.
Trigger with "langchain 1.0 migration", "langchain upgrade", "LLMChain removed",
"initialize_agent removed", "ConversationBufferMemory removed", "astream_log deprecated",
"langchain-anthropic 1.0".
Designed for Claude Code, also compatible with Codex
LangChain 1.0 Upgrade Migration (Python)
Overview
The first deploy after pip install -U langchain crashes on import with:
ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'
Fix the import, restart, and the next error lands:
ImportError: cannot import name 'LLMChain' from 'langchain.chains'
AttributeError: module 'langchain.agents' has no attribute 'initialize_agent'
AttributeError: 'ConversationBufferMemory' object has no attribute 'save_context'
LangChain 1.0 removed four entire public-API surfaces in one release:
Provider imports under langchain.chat_models / langchain.llms (pain code P38).
The LLMChain family under langchain.chains (P39).
ConversationBufferMemory and siblings under langchain.memory (P40).
initialize_agent under langchain.agents (P41).
Anything that inspected intermediate_steps also breaks because the tuple shape changed from (AgentAction, observation) to (ToolCall, observation) (P42).
This skill walks a reversible, phased migration:
A pre-flight grep audit.
A pinned package upgrade (including the langchain-anthropic 1.0 peer-pin against anthropic >= 0.40, P66).
Codemod patterns for the seven removed APIs.
A rollout playbook with shadow traffic and a sub-five-minute rollback.
It covers 7 named breaking changes and typically touches 10–100 files in a mid-sized service.
The fix for the error above:
# BEFORE (0.3)from langchain.chat_models import ChatOpenAI
# AFTER (1.0)from langchain_openai import ChatOpenAI
A working test suite for the service being migrated (the playbook runs pytest -W error::DeprecationWarning at every phase).
Git on a clean working tree — the migration uses per-module commits so rollback is per-commit.
Access to staging traffic or a request-mirror. Phase 4 of the playbook needs real-shape traffic.
If conversations are persisted (Redis / Postgres / DynamoDB), a snapshot of the chat-history store before Phase 2. The LangGraph checkpointer uses a new schema and a naive rollback is data-lossy.
Instructions
Step 1 — Pre-flight grep audit
Inventory every 0.3 usage before touching a requirements.txt. Each grep below maps to one pain code and one codemod pattern.
Pipe the full set into langchain-0.3-hits.txt — that file is the migration work list. The migration-detection.md reference has the one-shot bundled block and a line-count triage table.
Step 2 — Pin and upgrade packages together
LangChain 1.0 spans six coordinated packages. A partial upgrade (e.g. pip install -U langchain-anthropic without bumping anthropic) triggers AttributeError at import time (P66). Update all six in the same commit:
Then snapshot the prior state for the rollback: pip freeze > requirements.lock.pre-1.0.txt.
Step 3 — Codemod the four removed APIs
Work through the hits from Step 1 in this order (lowest blast radius first):
Provider imports (P38) — mechanical find/replace. from langchain.chat_models import ChatOpenAI → from langchain_openai import ChatOpenAI. Same pattern for ChatAnthropic, OpenAIEmbeddings, Chroma, etc.
LLMChain → LCEL (P39) — replace chain = LLMChain(llm=llm, prompt=prompt) with chain = prompt | llm | StrOutputParser(). Caller changes from chain.run(x=1) to chain.invoke({"x": 1}). If the caller treated the result as a dict, unwrap — invoke returns the string directly.
initialize_agent → create_react_agent (P41) — swap the import to from langgraph.prebuilt import create_react_agent. Tools written with Tool(name=..., func=...) still work; prefer the @tool decorator from langchain_core.tools. Agent input becomes {"messages": [("user", "...")]}; the final reply is result["messages"][-1].content.
ConversationBufferMemory → LangGraph checkpointer (P40) — swap the memory object for MemorySaver() (dev) or SqliteSaver.from_conn_string(...) (prod). Compile the graph/agent with checkpointer=saver, then pass config={"configurable": {"thread_id": "..."}} on every invoke. The thread_id is the conversation primary key.
astream_log still works in 1.0 but is soft-deprecated. The replacement is astream_events(version="v2"):
# BEFOREasyncfor patch in chain.astream_log({"input": "hi"}):
for op in patch.ops:
if op["op"] == "add"and op["path"].endswith("/streamed_output/-"):
print(op["value"], end="")
# AFTERasyncfor event in chain.astream_events({"input": "hi"}, version="v2"):
if event["event"] == "on_chat_model_stream":
print(event["data"]["chunk"].content, end="")
Event names in v2: on_chain_start, on_chain_end, on_chat_model_start, on_chat_model_stream, on_chat_model_end, on_tool_start, on_tool_end. The payload under data is typed — chunk is an AIMessageChunk, not a raw string.
Step 5 — Fix intermediate_steps consumers (P42)
If any code iterates result["intermediate_steps"] and reads .tool / .tool_input, it breaks silently in 1.0 — the tuples now hold ToolCall dicts, not AgentAction objects. The 1.0 equivalent reads from graph state:
# BEFOREfor action, observation in result["intermediate_steps"]:
log(action.tool, action.tool_input, observation)
# AFTERfor msg in result["messages"]:
for tc ingetattr(msg, "tool_calls", []) or []:
log(tc["name"], tc["args"]) # .tool -> "name", .tool_input -> "args"
ToolCall dict keys are name, args, id. There is no tool or tool_input accessor anywhere in 1.0.
Step 6 — Gate on deprecation-as-error tests
Turn DeprecationWarning into a test failure so any surviving 0.3 pattern surfaces before the rollout:
pytest -W error::DeprecationWarning
Do not promote to staging while this is red. Re-run the Step 1 greps — they should now return zero hits outside intentionally-pinned 0.3 test fixtures.
Step 7 — Phased rollout on production traffic
Deploy behind a feature flag (LANGCHAIN_1_0_ENABLED), canary at 1%, and ramp to 100% over 2–4 hours with a 15-minute soak at each step. The rollback is always "flip the flag off" — not a redeploy. Full playbook (shadow traffic in staging, dual-write for persistent chat histories, per-phase exit criteria) is in phased-rollout-playbook.md.
Output
requirements.txt pinning all six 1.0 packages with the anthropic >= 0.40 peer-pin (P66).
requirements.lock.pre-1.0.txt in the repo root for five-minute rollback.
Per-module git commits referencing pain codes (e.g. refactor: migrate P39 LLMChain in billing-summariser to LCEL).
langchain-0.3-hits.txt work-list returning zero non-test hits on re-run.
pytest -W error::DeprecationWarning green on the migration branch.
Feature-flagged production cutover at 100%, flag removed after a full day of soak.
Error Handling
Error
Cause
Fix
ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'
P38 — provider imports moved to partner packages
from langchain_openai import ChatOpenAI
ImportError: cannot import name 'LLMChain' from 'langchain.chains'
P39 — LLMChain removed
Replace with LCEL: prompt | llm | StrOutputParser()
AttributeError: 'ConversationBufferMemory' object has no attribute 'save_context'
P40 — memory classes removed from the public API
Swap for LangGraph MemorySaver / SqliteSaver with a thread_id
AttributeError: module 'langchain.agents' has no attribute 'initialize_agent'
P41 — legacy agent constructor removed
from langgraph.prebuilt import create_react_agent
AttributeError: 'ToolCall' object has no attribute 'tool'
P42 — tuple shape changed, fields renamed
Read tc["name"] and tc["args"] instead of .tool / .tool_input
AttributeError: module 'anthropic' has no attribute 'AsyncAnthropic'
