告别 AgentExecutor：LangChain v1.0+ Agent 模块深度迁移指南与实战全解析

【个人主页：玄同765】

大语言模型（LLM）开发工程师｜中国传媒大学·数字媒体技术（智能交互与游戏设计）

深耕领域：大语言模型开发 / RAG知识库 / AI Agent落地 / 模型微调

技术栈：Python / LangChain/RAG（Dify+Redis+Milvus）| SQL/NumPy | FastAPI+Docker ️

工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让AI交互更智能，让技术落地更高效」

欢迎技术探讨/项目合作！ 关注我，解锁大模型与智能交互的无限可能！

在 LangChain 1.0 时代，Agent（智能体）模块经历了一场“脱胎换骨”的变革。如果你还在使用initialize_agent或者AgentType，那么你已经站在了旧时代的边缘。

1.0+ 版本不仅是版本号的跳跃，更是从“黑盒执行器”向“透明状态图”的范式转移。本文将带你深入对比 LangChain 1.0 前后的架构差异，手把手教你完成从旧版到新版的平滑迁移。

一、 时代的分水岭：Pre-1.0 vs 1.0+

在 1.0 之前，Agent 的开发就像是在配置一个“黑盒”。你告诉它工具和模型，它在后台通过复杂的正则匹配（ReAct）来决定下一步。

1. 旧版（Pre-1.0）：以 AgentExecutor 为核心

• 入口函数：initialize_agent（已弃用）。
• 核心逻辑：依赖AgentExecutor循环。这是一个硬编码的 Python 循环，开发者很难修改其内部逻辑。
• 交互方式：基于字符串。Agent 思考过程（Thought）和工具调用（Action）通常是通过 Prompt 强行让模型输出特定格式（如Action: ...），然后用正则解析。
• 记忆管理：使用ConversationBufferMemory等组件，耦合度高。

2. 新版（1.0+）：以 LangGraph 为底座

• 入口函数：create_agent（推荐）。
• 核心逻辑：基于LangGraph。Agent 不再是一个简单的链，而是一个状态机（State Graph）。
• 交互方式：原生Tool Calling。利用 OpenAI 等模型自带的tool_calls参数，输出结构化 JSON，告别正则解析的噩梦。
• 记忆管理：引入checkpointer（检查点机制），支持持久化、断点续传和多线程会话。

二、 代码大对比：从“旧”到“新”

1. 工具定义：从基础到高级

LangChain v1.0+ 提供了多种工具定义方式，满足不同复杂度的需求：

基础工具定义

使用@tool装饰器是最简单直接的方式：

from langchain_core.tools import tool @tool def search_order(order_id: str) -> str: """根据订单ID查询快递状态。""" # 模拟数据库查询 return f"订单 {order_id} 正在派送中..." tools = [search_order]

结构化工具定义

对于需要复杂参数验证的场景，使用StructuredTool：

from langchain_core.tools import StructuredTool from pydantic import BaseModel, Field # 定义参数结构 class WeatherRequest(BaseModel): city: str = Field(description="要查询天气的城市名称") days: int = Field(default=1, description="要查询的天数") def get_weather_detailed(city: str, days: int = 1) -> str: """获取指定城市的详细天气信息""" weather_data = { "北京": ["晴，25℃", "多云，23℃", "阴，22℃"], "上海": ["多云，23℃", "阴，22℃", "小雨，20℃"] } if city in weather_data: return "\n".join(weather_data[city][:days]) return "未知城市" # 创建结构化工具 weather_tool = StructuredTool.from_function( func=get_weather_detailed, name="get_weather_detailed", description="获取指定城市的详细天气信息", args_schema=WeatherRequest )

工具集合（Toolkit）

对于相关工具的组织和管理，使用Toolkit：

from langchain_core.tools import Toolkit from langchain_community.tools import WikipediaQueryRun, DuckDuckGoSearchRun from langchain_community.utilities import WikipediaAPIWrapper class InformationToolkit(Toolkit): """信息查询工具集合""" def __init__(self): self.wikipedia_tool = WikipediaQueryRun( api_wrapper=WikipediaAPIWrapper(lang="zh") ) self.search_tool = DuckDuckGoSearchRun() def get_tools(self): """获取工具列表""" return [self.wikipedia_tool, self.search_tool] # 使用工具集合 toolkit = InformationToolkit() tools = toolkit.get_tools()

2. 初始化 Agent：配置 vs 编排

❌ 旧版写法（已不再推荐）

from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-3.5-turbo") # 依赖 AgentType 枚举，难以自定义逻辑 agent = initialize_agent( tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True ) # 字符串调用 agent.run("帮我查一下订单号 12345 的状态")

✅ 新版写法（1.0+ 推荐）

from langchain.agents import create_agent from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4o") # 1.0+ 版本直接返回一个 CompiledStateGraph agent = create_agent( model=llm, tools=tools, system_prompt="你是一个专业的物流客服，必须通过工具查询信息。" ) # 消息流调用 result = agent.invoke({ "messages": [("human", "帮我查一下订单号 12345 的状态")] })

三、 深度解析：1.0+ 的核心改进点

1. 输入输出的标准化（Messages First）

旧版 Agent 习惯于{"input": "..."}和{"output": "..."}。 新版全面拥向Message 列表。agent.invoke的输入和输出都是BaseMessage对象。 *优势：与 ChatModel 的 API 完美对齐，天然支持多轮对话。

2. 强大的记忆力：Memory vs Checkpointer

在旧版中，如果你想实现多轮对话，需要手动维护一个列表。 在 1.0+ 中，你可以给create_agent传入一个checkpointer：

from langgraph.checkpoint.memory import MemorySaver memory = MemorySaver() # 此时 agent 具备了跨请求的记忆能力 agent = create_agent(model=llm, tools=tools, checkpointer=memory) # 通过 thread_id 隔离不同用户的会话 config = {"configurable": {"thread_id": "session_001"}} agent.invoke({"messages": [("human", "我是玄同")]}, config)

3. 中间件（Middleware）：Agent 的“插件系统”

1.0+ 引入了中间件机制，允许你在“模型调用”或“工具执行”前后插入自定义逻辑。 *场景：API 鉴权、Token 计数、敏感词过滤、自动化日志。

from langchain.agents.middleware import AgentMiddleware class TokenCounterMiddleware(AgentMiddleware): def wrap_model_call(self, request, handler): # 模型调用前的处理 response = handler(request) # 模型调用后的处理（如计数） return response

4. Tools模块高级特性

工具参数验证

使用 Pydantic 模型对工具参数进行验证，确保参数的类型和格式正确：

from langchain_core.tools import StructuredTool from pydantic import BaseModel, Field, field_validator class CalculateRequest(BaseModel): expression: str = Field(description="要计算的数学表达式") @field_validator('expression') def validate_expression(cls, v): # 简单的表达式验证 allowed_chars = set("0123456789+-*/() ") if not all(c in allowed_chars for c in v): raise ValueError("表达式只能包含数字、运算符和括号") return v def calculate(expression: str) -> str: """计算数学表达式""" try: result = eval(expression) return f"计算结果：{result}" except Exception as e: return f"计算错误：{str(e)}" calculate_tool = StructuredTool.from_function( func=calculate, args_schema=CalculateRequest, description="计算数学表达式" )

工具错误处理

为工具添加错误处理机制，确保工具调用失败时能够优雅地处理：

def safe_calculate(expression: str) -> str: """安全计算数学表达式""" try: # 验证表达式安全性 if any(c in expression for c in ["__", "import", "exec", "eval"]): return "表达式不安全" result = eval(expression) return f"计算结果：{result}" except Exception as e: return f"计算错误：{str(e)}"

工具性能优化

使用缓存减少重复调用，提高系统性能：

from functools import lru_cache @lru_cache(maxsize=100) def expensive_tool(query: str) -> str: # 复杂计算或API调用 import time time.sleep(1) # 模拟耗时操作 return f"结果：{query}"

四、 参数速查表：迁移避坑指南

五、 总结：为什么要升级？

如果说旧版 Agent 是一个“配置出来的工具”，那么 1.0+ 的 Agent 就是一个“生长出来的应用”。

基于 LangGraph 的create_agent给了开发者前所未有的控制力：

1.可观测性：你可以清楚地看到图中的每一个节点是如何流转的。

2.灵活性：如果create_agent的默认逻辑不够用，你可以直接手动修改其底层的 Graph 结构。

3.生产就绪：持久化记忆和中间件支持，让 Agent 真正能够落地到复杂的企业级场景。

「从 1.0 开始，Agent 不再是一个简单的 Python 循环，而是一个健壮的分布式状态机。」

下一篇预告：我们将跳出create_agent的便捷封装，手动从零构建一个LangGraph复杂 Agent，挑战多 Agent 协作场景。

参考链接

• LangChain 官方文档
• LangChain GitHub 仓库
• LangChain v1.0+ 核心特性详解
• LangChain Expression Language (LCEL)
• StateGraph 工作流编排
• Pydantic 模型
• OpenAI API 官方文档