LangChain v1 Migration Guide
LangChain v1 replaced hooks with middleware, InjectedState with ToolRuntime, and create_react_agent with create_agent. This guide covers the migration order, what breaks silently, and how to test each step — not just what changed.
Quick Reference
- →Python 3.10+ required — 3.9 is dropped
- →from langchain.agents import create_agent — replaces langgraph.prebuilt.create_react_agent
- →system_prompt replaces prompt — str or SystemMessage, not a prompt template
- →ToolRuntime replaces InjectedState + InjectedStore + InjectedConfig — runtime.state, .context, .store, .config, .tool_call_id, .stream_writer
- →State schema must extend AgentState TypedDict — Pydantic and dataclass are rejected
- →Streaming node name changed: 'agent' → 'model' — update stream filters or miss events
- →Anthropic max_tokens default raised from 1024 — explicitly set if you rely on the old limit
- →langchain-classic coexists with langchain — use for gradual migration, maintained until Dec 2026
Should You Migrate Now?
LangChain v1 shipped in late 2025. LangChain is now at v1.2.x (April 2026). The migration is not optional forever — but you have time. The `langchain-classic` package maintains all v0.x legacy code (LLMChain, output parsers, old retrievers, hub) with security patches until December 2026. After that, no fixes.
| Situation | Recommendation |
|---|---|
| New project starting today | Use v1 from the start — no migration needed |
| Existing project, no custom hooks/state | Migrate now — Steps 1–3 take an afternoon |
| Existing project, heavy InjectedState usage | Add langchain-classic first, migrate service-by-service |
| Existing project, on Python 3.9 | Upgrade Python first — v1 blocks on import if 3.9 |
| Using LLMChain, ConversationChain | Add langchain-classic, migrate chains at your own pace until Dec 2026 |
Two things break immediately on `pip install langchain>=1.0`: imports from removed namespaces (LLMChain, legacy retrievers) throw ImportError at startup. Python 3.9 throws an error before any import. Everything else — hooks, InjectedState — raises deprecation warnings first, then breaks in v2. You have runway, but you need to install langchain-classic before upgrading if you use the legacy APIs.