LangChain 1.0 迁移指南：哪些 API 变了，怎么改

个人主页 for_ever_love__ 欢迎各位大佬莅临其他栏目: 大模型开发从0到1 其他栏目: iOS项目总结大全 其他栏目: 我想学python了 其他栏目: iOS UI 文章目录LangChain 1.0 迁移指南哪些 API 变了怎么改一、1.0 的核心变化二、Agent 的变化影响最大三、记忆的变化四、create_agent 里能配什么五、结构化输出的变化六、LCEL 的变化基本没变七、迁移步骤八、几个容易卡住的点九、值不值得升级十、小结LangChain 1.0 迁移指南哪些 API 变了怎么改LangChain 1.0 是一次整理式的发布把 0.x 时代积累的多套写法收敛成一套把散落的入口归并把隐式魔法改成显式配置。一、1.0 的核心变化变化0.x 的写法1.0 的写法Agent 入口initialize_agent、AgentExecutorcreate_agent状态图langgraph独立包内建到langchain消息管理RunnableWithMessageHistory内建到 Agent工具toolBaseTool同样但类型更严ChainLLMChain、RetrievalQALCEL0.2 起就在推输出PydanticOutputParserwith_structured_output大方向少即是多。由多个能做同一件事的 API收敛成一个。二、Agent 的变化影响最大0.x 的写法有多套# 写法 Ainitialize_agentagentinitialize_agent(tools,llm,agentzero-shot-react-description)resultagent.run(查一下北京的天气)# 写法 BAgentExecutor create_react_agentagentcreate_react_agent(llm,tools,prompt)executorAgentExecutor(agentagent,toolstools)resultexecutor.invoke({input:...})1.0 的写法统一fromlangchain.agentsimportcreate_agent agentcreate_agent(modelopenai:gpt-4o-mini,tools[get_weather,search_web],system_prompt你是一个助手回答前先确认信息是否足够。,)resultagent.invoke({messages:[{role:user,content:查一下北京的天气}]})print(result[messages][-1].content)三个显著差异返回值是消息列表不再是裸字符串。要拿文本得取result[messages][-1].content。模型可以用字符串简写openai:gpt-4o-mini不需要先实例化 ChatOpenAI。想要更多控制仍然可以传对象。内置了短期记忆——传thread_id即可不需要手动包裹RunnableWithMessageHistoryresultagent.invoke({messages:[{role:user,content:...}]},config{configurable:{thread_id:user-123}},)三、记忆的变化0.x三层套娃fromlangchain_community.chat_message_historiesimportRedisChatMessageHistoryfromlangchain_core.runnables.historyimportRunnableWithMessageHistorydefget_history(session_id):returnRedisChatMessageHistory(session_id,urlREDIS_URL)chain_with_historyRunnableWithMessageHistory(chain,get_history,input_messages_keyquestion,history_messages_keyhistory,)1.0把持久化后端变成可插拔的配置fromlanggraph.checkpoint.redisimportRedisSaverfromlangchain.agentsimportcreate_agentwithRedisSaver.from_conn_string(REDIS_URL)ascheckpointer:agentcreate_agent(modelllm,toolstools,checkpointercheckpointer,# 记忆后端直接声明)resultagent.invoke({messages:[...]},config{configurable:{thread_id:user-123}},)变化的核心记忆从你要手动包装变成Agent 的内建能力。四、create_agent里能配什么fromlangchain.agentsimportcreate_agentfromlangchain.agents.structured_outputimportToolStrategy agentcreate_agent(modelllm,tools[a,b,c],# ① 系统提示system_prompt你是客服助手回答简洁。,# ② 记忆后端checkpointercheckpointer,# ③ 跨会话长期记忆storeInMemoryStore(),# ④ 结构化输出response_formatToolStrategy(MySchema),# ⑤ 中间件1.0 的新概念middleware[summarization_middleware,retry_middleware],# ⑥ 控制细节namecustomer_agent,)middleware是 1.0 新增的抽象——用来插在模型调用前后做的事fromlangchain.agents.middlewareimportbefore_model,after_modelbefore_modeldefsummarize_if_long(state,runtime):消息太长就先摘要ifcount_tokens(state[messages])8000:return{messages:[summarize(state[messages][:-5])]state[messages][-5:]}returnNoneafter_modeldeflog_cost(state,runtime):记录本次调用的成本log.info(model_called,tokens...)returnNoneagentcreate_agent(modelllm,toolstools,middleware[summarize_if_long,log_cost])这比 0.x 里在链上挂回调更结构化。五、结构化输出的变化0.x解析器 格式说明fromlangchain_core.output_parsersimportPydanticOutputParser parserPydanticOutputParser(pydantic_objectMySchema)promptChatPromptTemplate.from_template(回答问题。\n{format_instructions}\n问题{question}).partial(format_instructionsparser.get_format_instructions())chainprompt|llm|parser1.0直接在 Agent/模型上声明frompydanticimportBaseModelclassAnswer(BaseModel):conclusion:strconfidence:floatsources:list[str]agentcreate_agent(modelllm,toolstools,response_formatToolStrategy(Answer))resultagent.invoke({messages:[...]})print(result[structured_response])# Answer 实例变化不用再往提示词里塞format_instructions框架负责。六、LCEL 的变化基本没变好消息是LCEL 语法几乎完全兼容chainprompt|llm|StrOutputParser()# 1.0 里依然有效但推荐场景变了场景0.x 推荐1.0 推荐固定的数据流水线LCELLCEL ✅需要循环/条件分支LCEL 自定义LangGraphAgent 循环AgentExecutorcreate_agent需要人工介入手动实现LangGraph interrupt规律确定的流程用 LCEL动态决策用图/Agent。七、迁移步骤① 先升到 0.3 并清掉警告1.0 的大部分改动在 0.3 就埋了废弃警告。先在 0.3 上把所有DeprecationWarning清掉python-Werror::DeprecationWarning-cimport your_app21|grep-ideprecat② 替换 Agent 相关代码initialize_agent(...) → create_agent(...) AgentExecutor(...) → 不再需要create_agent 自带循环 create_react_agent(...) → create_agent(...)③ 替换记忆删掉RunnableWithMessageHistory改用checkpointer# 删掉chain_with_historyRunnableWithMessageHistory(chain,get_history,...)# 换成agentcreate_agent(modelllm,toolstools,checkpointercheckpointer)④ 改返回值处理# 旧answerexecutor.invoke({input:q})[output]# 新answeragent.invoke({messages:[(user,q)]})[messages][-1].content⑤ 更新依赖pipinstall-Ulangchain1.0langchain-core1.0langchain-openai1.0八、几个容易卡住的点①output键没有了。大量代码在result[output]上取值。全局搜一遍[output]grep-rn\[output\]--include*.py.② 消息格式统一。旧代码里常见{input: ...}、{question: ...}这类自定义键。1.0 的 Agent 统一用messages# 旧executor.invoke({input:问题,chat_history:history})# 新agent.invoke({messages:history[(user,问题)]})③return_intermediate_steps不同。旧代码靠这个参数拿中间步骤。1.0 里中间步骤本来就在messages里resultagent.invoke({messages:[(user,q)]})forminresult[messages]:ifm.typetool:print(工具结果,m.content)elifm.tool_calls:print(调用了,[tc[name]fortcinm.tool_calls])④ 自定义 Agent 需要重写。如果你实现了自定义的BaseSingleActionAgent1.0 里这套接口变了。通常更好的选择是改用 LangGraph 显式建图——表达能力更强也更可控。⑤ 部分 community 集成滞后。一些冷门的 community 集成可能还没适配 1.0。先在测试环境验证别直接上生产。九、值不值得升级值得升你在用 AgentExecutor0.x 的 Agent 在可观测性和可控性上确实弱你想用上内建的 checkpoint / 流式 / 结构化输出你想统一项目里的写法0.x 项目通常混着三四种风格可以等等项目稳定、没有新需求、升级风险大于收益依赖了大量冷门 community 集成通用建议先把 0.3 的废弃警告清干净这是几乎无风险的准备工作等 1.x 生态稳定后再切主体代码。十、小结# 1.0 的核心入口fromlangchain.agentsimportcreate_agent agentcreate_agent(modelllm,toolstools,system_prompt...,checkpointercheckpointer,# 记忆storestore,# 长期记忆response_formatSchema,# 结构化输出middleware[...],# 中间件)五条迁移要点1. AgentExecutor → create_agent 2. RunnableWithMessageHistory → checkpointer 3. 返回值取 messages[-1].content 4. 记忆/结构化输出变成声明式配置 5. LCEL 基本不变1.0 最大的价值不是新功能而是只有一种正确写法。对维护者来说这比任何单个特性都重要。