Cómo migrar a LangChain 1.0 sin que te rompa el agente

LangChain y LangGraph llegaron a su primera versión estable con una promesa concreta: no volverán a romperte el código sin avisar. Pero para llegar ahí hay que cruzar una vez, y el cruce jubila AgentExecutor, el componente sobre el que está construida casi toda la documentación que encontrarás por ahí. Si vas a migrar a LangChain 1.0, esto es lo que cambia, en qué orden hacerlo y los errores textuales con los que te vas a topar.

Cómo migrar a LangChain 1.0, y en qué orden

No saltes directo. El orden importa porque aprovecha los avisos de deprecación como red:

Primero sube a la última 0.3.x. Esa línea trae todos los avisos de deprecación. Es tu lista de trabajo, generada por tu propio código en vez de por una guía genérica.

Arregla lo que avisen. Cada aviso apunta a un cambio de la 1.0.

Y después salta. Hay un comando que detecta los patrones más comunes y los reescribe:

langchain migrate

Antes de ejecutarlo, revisa la guía oficial de migración: el comando resuelve lo mecánico, no lo que requiere decidir.

Los tres cambios que son el 80% de la migración

Si tu agente es un ReAct de toda la vida, casi todo el trabajo son tres ediciones.

Antes, con AgentExecutor:

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o", temperature=0)
agent = create_openai_tools_agent(llm, tools, prompt)
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=False,
    handle_parsing_errors=True,
    max_iterations=6,
)

result = executor.invoke({"input": user_message})

Después, con create_agent:

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver

llm = ChatOpenAI(model="gpt-4o", temperature=0)
checkpointer = MemorySaver()

agent = create_agent(
    model=llm,
    tools=tools,
    system_prompt=SYSTEM_PROMPT,
    checkpointer=checkpointer,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": user_message}]},
    config={"configurable": {"thread_id": session_id}},
)

Lo que acaba de pasar, punto por punto:

• La ruta de importación cambia: create_react_agent de langgraph.prebuilt pasa a create_agent de langchain.agents.
• prompt= se llama ahora system_prompt=.
• La invocación deja de ser {"input": "..."} y pasa a ser {"messages": [...]}.
• handle_parsing_errors desaparece: la lógica de reintento se muda al sistema de middleware.
• La memoria deja de ser un argumento y pasa a ser un checkpointer de LangGraph.

El resto de cambios, y qué los sustituye

Fuera de ese núcleo, la migración toca estos puntos:

• Las callbacks de AgentExecutor —conteo de tokens, PII, límite de peticiones— se registran ahora como middleware sobre el grafo compilado.
• pre_model_hook y post_model_hook se convierten en middleware con métodos before_model y after_model.
• El estado ya no admite Pydantic ni dataclasses: solo TypedDict, heredando de langchain.agents.AgentState.
• response_format para salidas estructuradas pasa a ToolStrategy o ProviderStrategy, de langchain.agents.structured_output.
• El nodo de streaming llamado "agent" se renombra a "model" — si tienes código que escucha ese nombre, déjalo de escuchar.
• .text() deja de ser método y pasa a ser propiedad: se usa response.text, sin paréntesis.
• Python 3.9 se queda fuera. Hace falta 3.10 o superior.

Y un cambio que sorprende a mucha gente: las cadenas clásicas —LLMChain, ConversationChain, los retrievers, la API de indexación, hub— se mudaron al paquete langchain-classic. Si las usas, hay que instalarlo y actualizar los imports. No desaparecieron; cambiaron de casa.

Los errores exactos con los que te vas a topar

Estos son los tres que salen una y otra vez, con lo que significan de verdad:

ImportError: cannot import name 'create_agent' — no es que el nombre esté mal, es que tienes versiones mezcladas. Lo arregla:

pip install --upgrade langchain langgraph langchain-core

TypeError: unexpected keyword argument 'prompt' — el renombrado del que hablábamos. Cambia prompt= por system_prompt=.

ValueError: Checkpointer requires thread_id — le pasaste un checkpointer al agente pero no le dices de qué conversación es. Necesita el thread_id en la configuración:

result = agent.invoke(
    {"messages": [...]},
    config={"configurable": {"thread_id": session_id}},
)

Lo que ganas cuando terminas

La razón por la que vale la pena el cruce. De todo lo nuevo, LangChain señala el MCP nativo como lo de mayor retorno inmediato: conectar el agente a GitHub, a una base de datos o a una API externa pasa a ser configuración en vez de código propio.

Lo demás:

• Middleware: logging, límite de peticiones y reintentos se definen una vez y se aplican a toda la cadena, sin tocar la lógica del agente. Es lo que sustituye a las callbacks y a los hooks.
• Redacción automática de PII, aplicada antes de que los datos lleguen al modelo. LangChain lo llama crítico para banca, salud y legal.
• Carga perezosa de herramientas: en un agente con 15 o 20 herramientas, las que no se usan no se inicializan.

Y en LangGraph 1.0, dos cosas que cambian cómo se escriben los agentes que actúan de verdad:

elicitation="interrupt" declara en qué punto el grafo se detiene a pedir aprobación humana, guarda el estado y sigue cuando se confirma. Antes esto se hacía con apaños alrededor de interrupt_before.

Checkpointing con PostgreSQL y Redis, para que un agente de horas no pierda el estado si el proceso se cae.

Errores frecuentes al planificar la migración

• Saltarse la 0.3.x. Es donde están los avisos de deprecación, que son tu lista de trabajo. Sin ese paso migras a ciegas.
• Mirar documentación vieja. Casi todo lo que encuentres en internet sobre agentes en LangChain usa AgentExecutor, y está jubilado. Si un tutorial no menciona create_agent, es anterior a la 1.0.
• Olvidar langchain-classic. Si tu código usa LLMChain o los retrievers, van a fallar los imports y el mensaje no siempre es obvio.
• No comprobar la versión de Python. 3.9 queda fuera; si tu CI la tiene fijada, el fallo aparece antes de que llegues al código.

Otra pieza del stack: si el agente va a consultar tus documentos, cómo montar un RAG con Elasticsearch serverless encaja con esta migración.

Fuente: la guía oficial de migración a LangChain v1 y las novedades de la v1, más la guía de migración de LangGraph. El resumen del anuncio está en DataPath.