langchain早期提供的initialize_agent函数是快速构建智能体的常用工具，但随着框架迭代，该函数因为灵活性不足、和最新架构适配性差等问题被官方禁用，开发者需要采用新的方式实现智能体功能。
initialize_agent被禁用的核心原因
initialize_agent的设计逻辑是将智能体的构建、工具绑定、提示词配置、执行逻辑全部封装在一个函数里，虽然降低了入门门槛，但也带来了几个明显的问题：
- 无法灵活自定义智能体的提示词结构，适配复杂业务场景的能力弱
- 和langchain最新的表达式语言（LCEL）架构不兼容，无法利用链式调用的优势
- 内部逻辑耦合度高，调试和问题排查的难度较大
- 不再接收官方的功能更新，存在潜在的兼容性和安全风险
官方推荐的替代方案
当前langchain官方推荐使用langchain.agents模块下的专用创建函数配合AgentExecutor的方式构建智能体，不同的智能体类型对应不同的创建函数，开发者可以根据业务需求选择。
1. 常用智能体创建函数说明
| 函数名称 | 适用场景 | 特点 |
|---|---|---|
| create_react_agent | 需要推理和行动循环的场景，工具调用逻辑相对简单 | 遵循ReAct范式，提示词结构清晰，适配大多数通用智能体场景 |
| create_structured_chat_agent | 需要结构化输出、多轮复杂工具调用的场景 | 支持更复杂的工具参数传递，适合业务规则较多的场景 |
| create_json_chat_agent | 需要严格JSON格式输出的工具调用场景 | 工具调用结果和输出格式标准化程度高，便于后续数据处理 |
2. 通用替代实现步骤
无论选择哪种智能体类型，核心实现步骤都分为四步：准备大语言模型、定义工具集合、创建智能体、构建执行器并运行。
步骤1：准备基础依赖和大语言模型
首先确保安装了最新版本的langchain和相关模型依赖，这里以OpenAI模型为例：
# 安装依赖 pip install langchain langchain-openai
from langchain_openai import ChatOpenAI
# 初始化大语言模型，这里替换为自己的API密钥和端点
llm = ChatOpenAI(
model="gpt-3.5-turbo",
openai_api_key="your_api_key",
base_url="https://api.openai.com/v1"
)步骤2：定义工具集合
工具的定义方式和之前一致，使用@tool装饰器或者Tool类都可以，这里以一个简单的计算工具为例：
from langchain.tools import tool
@tool
def add_numbers(a: int, b: int) -> int:
"""计算两个整数的和"""
return a + b
# 工具集合，可添加多个自定义工具
tools = [add_numbers]步骤3：创建对应类型的智能体
这里以最常用的create_react_agent为例，需要传入大语言模型、工具集合和对应的提示词，官方已经提供了默认的提示词模板，也可以自定义：
from langchain.agents import create_react_agent, AgentExecutor
from langchain import hub
# 从hub获取官方默认的ReAct提示词模板，也可以自定义提示词
prompt = hub.pull("hwchase17/react")
# 创建ReAct类型的智能体
agent = create_react_agent(
llm=llm,
tools=tools,
prompt=prompt
)步骤4：构建执行器并运行智能体
创建完智能体后，需要将其包装到AgentExecutor中，配置运行参数后就可以执行用户查询：
# 构建智能体执行器，配置相关参数
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True, # 是否打印执行过程，调试时建议开启
handle_parsing_errors=True # 处理解析错误，避免运行中断
)
# 运行智能体，传入用户查询
result = agent_executor.invoke({"input": "计算123和456的和是多少"})
print(result["output"])旧代码迁移注意事项
如果之前的项目使用了initialize_agent，迁移时需要注意几个差异点：
- 原来的agent_type参数需要替换为对应的创建函数，比如agent_type="react-docstore"对应使用create_react_agent
- 原来在initialize_agent中传入的提示词相关参数，需要单独构造提示词后传入创建函数
- 工具的定义如果使用了旧的Tool类写法，建议迁移到@tool装饰器的写法，兼容性更好
- 运行方式从原来的agent.run()变为agent_executor.invoke()，返回结果的字段名可能有变化，需要对应调整
不同场景的选型建议
如果是简单的通用查询、工具调用场景，优先选择create_react_agent，实现简单且适配性好；如果需要调用多个工具、工具参数复杂，建议选择create_structured_chat_agent；如果业务要求输出严格的JSON格式，方便后续程序处理，就选择create_json_chat_agent。如果官方提供的提示词模板无法满足需求，也可以自定义提示词结构，只需要保证提示词中包含工具描述、用户输入、推理步骤等必要部分即可。
langchaininitialize_agentagent替代langchain_agent修改时间：2026-06-04 00:07:33