纲要
- 核心概念:单智能体(Single Agent)的定义与定位
- 单智能体 vs 多智能体:适用场景与决策模式对比
ReAct框架:推理与行动的闭环循环
- 技术栈与版本选型
Python 3.10+、LangChain 0.3、Pydantic v2- 依赖管理:
Poetry
- 基于
LangChain的单智能体实现- 核心组件:
LLM、提示词模板(Prompt Template)、工具(Tools) create_react_agent工厂方法解析- 完整的可运行示例:集成搜索工具的智能体
- 核心组件:
- 开发环境与工程化配置
- 项目初始化与依赖锁定
- 关键版本兼容性详解(
Pydantic版本冲突的根源与解决)
LangGraph与多智能体系统前瞻- 有状态工作流图:节点(Node)与边(Edge)
- 单智能体与多智能体的架构权衡
- API 速览
- Demo 示例
- 参考文档
- 总结
单智能体:一个决策核心,多种工具协同
在 AI 应用开发的演进中,智能体(Agent)代表了一种超越固定流程的范式。它指的是能够自主进行目标规划、工具调用并完成复杂任务的程序实体。所谓单智能体(Single Agent),即在系统架构中仅存在一个中心化的决策单元,所有外部工具和能力均围绕该决策核心进行组织和调度。
形象的类比是:将大语言模型(LLM)视作系统的大脑。当用户提出请求时,该大脑并非按照预设的固定路径(如传统的 Chain)执行,而是动态地规划步骤——例如“先检索内部知识库,再查询日历 API,最后整合信息生成回复”。这种自主的、非线性的规划能力,是智能体与普通链式调用的根本分野。后者如同一条固定的流水线,而前者则具备根据环境反馈动态调整执行路径的能力。
单智能体架构具有以下显著的技术特征:
- 结构简洁:仅需一个 LLM 实例负责全部感知、规划与决策过程。
- 决策集中:避开了多智能体协调所带来的通信开销和一致性挑战。
- 资源开销低:推理路径短,上下文窗口占用相对可控,响应延迟较低。
- 任务聚焦:适用于特定领域内的中等复杂度任务,或在问题域边界清晰时的最优解。
单智能体的核心运行机制在学术界和工业界被广泛定义为 ReAct 模式。该术语并非指前端开发框架,而是 Reasoning + Acting 的缩写,即“推理与行动”的交替迭代过程。
流程说明:当系统接收用户输入后,智能体首先观察(Observe)当前上下文状态,随后进行思考(Thought)以确定下一步的最优动作。若判定需要获取外部知识,则执行行动(Action)——调用相应的工具;工具返回结果后,新的观察结果被追加至上下文中,触发新一轮的思考循环。此过程持续进行,直至模型判定信息足以生成最终回复(Final Answer)。LangChain 框架中的 create_react_agent 工厂方法,即是对该理念的标准化工程实现。
LangChain 中的单智能体构建基元
在 LangChain 0.3 版本体系中,尽管官方生态正逐步引导复杂编排向 LangGraph 迁移,但对于单智能体场景,核心能力依然保留在 langchain 基础库中。其中,create_react_agent 是构建自定义智能体的最底层与最基础的方法。
注:绝大多数高级封装的智能体构造器(如
create_tool_calling_agent、create_json_agent等)其底层实现均依赖于create_react_agent。掌握该方法相当于掌握了 LangChain 智能体体系的根基。
构建一个最简智能体需要三个核心要素的协同:
- 大语言模型(LLM):作为推理引擎,负责理解上下文、规划步骤并生成最终回答。
- 提示词模板(Prompt Template):定义智能体的角色、行为边界、可用工具的描述以及推理过程的格式规范。
- 工具集(Tools):智能体可调用的外部能力接口,如搜索引擎、数据库查询、数学计算器或自定义业务函数。
开发环境配置与工程化实践
为确保环境的一致性与可复现性,建议使用 Python 3.10 或更高版本,并采用 Poetry 作为依赖管理与虚拟环境工具。
项目初始化步骤:
首先,创建项目目录并初始化 pyproject.toml:
mkdir first-agent && cd first-agent
poetry init -n
随后,编辑生成的 pyproject.toml 文件,添加核心依赖项:
[tool.poetry.dependencies]
python = "^3.10"
langchain = "^0.3"
langchain-openai = "^0.2"
langchain-community = "^0.3"
python-dotenv = "^1.0"
执行安装命令以创建虚拟环境并下载依赖:
poetry install
版本兼容性警告:
LangChain 0.3 对 Pydantic 的版本有严格约束,必须使用 Pydantic v2。若环境中存在 Pydantic v1 的历史遗留包,运行时会抛出 pydantic.v1 与 pydantic.v2 冲突的异常。解决方案是使用 poetry add pydantic@^2 强制锁定版本,或检查 poetry.lock 文件中的依赖解析树,确保未通过其他库间接引入旧版本。
首个智能体实战:集成网络搜索能力的助手
项目目录结构
first-agent/
├── agent.py # 主程序入口
├── .env # 环境变量(API Keys)
└── pyproject.toml # 项目配置与依赖清单
环境变量配置
在项目根目录下创建 .env 文件,写入访问外部服务所需的密钥:
OPENAI_API_KEY=sk-xxxx
SERPAPI_API_KEY=xxxx
此处选用 SerpAPI 作为搜索工具实现(需前往 serpapi.com 注册获取免费 API Key)。亦可替换为 Tavily 或其他实现了 BaseTool 接口的任意工具。
完整代码实现 agent.py
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain.tools import Tool
from langchain.prompts import PromptTemplate
from langchain_community.utilities import SerpAPIWrapper
# 加载 .env 文件中的环境变量
load_dotenv()
# 1. 初始化 LLM
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
# 2. 定义工具:在线搜索
search = SerpAPIWrapper()
tools = [
Tool(
name="Search",
func=search.run,
description="当你需要回答关于实时事件、新闻或未知事实的问题时,使用此工具进行网络搜索。"
)
]
# 3. 构造提示词模板
# 必须包含 {tools}, {tool_names}, {agent_scratchpad} 等占位符,以满足 ReAct 代理的格式要求
template = """你是一个乐于助人的助手,可以使用工具来回答问题。
可用的工具有:
{tools}
工具名称:{tool_names}
请严格遵循以下格式进行推理:
Question: 需要回答的问题
Thought: 你应该思考当前要做什么
Action: 要使用的工具名称,必须是 [{tool_names}] 之一
Action Input: 向工具传入的输入参数
Observation: 工具返回的结果
... (上述 Thought/Action/Action Input/Observation 循环可按需重复多次)
Thought: 我现在知道最终答案了
Final Answer: 对原始问题的最终完整回答
开始!
Question: {input}
Thought: {agent_scratchpad}"""
prompt = PromptTemplate.from_template(template)
# 4. 创建 ReAct 智能体与执行器
agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True, # 开启详细日志,输出思考链
handle_parsing_errors=True, # 自动处理格式解析异常
)
# 5. 执行任务
if __name__ == "__main__":
question = "2024年诺贝尔物理学奖的得主是谁?"
response = agent_executor.invoke({"input": question})
print("智能体回答:", response["output"])
代码解读与关键机制
create_react_agent:该工厂函数将LLM、tools和prompt绑定为一个Runnable对象,其内部实现了 ReAct 循环的编排逻辑。AgentExecutor:负责驱动智能体运行的管理器。它封装了循环控制、工具调用分发、错误重试与上下文状态维护等复杂逻辑。- 占位符
{agent_scratchpad}:这是 LangChain 的约定占位符,用于存储并传递历史推理过程中的 Thought/Action/Observation 记录,确保模型拥有完整的“短期记忆”以支持多步推理。
架构演进:单智能体与多智能体的决策边界
当业务场景扩展至需并行处理、跨领域专家协作或长周期任务规划时,单智能体架构会面临上下文窗口过载、职责耦合度过高等瓶颈。此时,系统设计需向**多智能体(Multi-Agent)**架构演进。
LangGraph 是 LangChain 生态中专为构建有状态、多角色协作系统而设计的低级编排框架。其核心抽象为图(Graph):每个**节点(Node)**可封装为一个独立的智能体、一个工具函数或一段 LCEL 链;**边(Edge)**则定义了数据在节点间的流转路径与条件分支。
多智能体系统具备更强的扩展性和容错性,能够模拟“团队协作”模式,但也引入了新的复杂性:智能体间的通信协议、全局状态同步、任务分解与结果聚合等。官方推荐的技术选型原则是:优先采用单智能体以降低系统复杂度,当确实面临单点性能瓶颈或逻辑强耦合时,再迁移至 LangGraph 构建多智能体网络。
API 速览
本实战中涉及的核心 API 如下:
-
langchain.agents.create_react_agent- 所属库:
langchain.agents - 方法签名:
create_react_agent(llm: BaseLLM, tools: Sequence[BaseTool], prompt: ChatPromptTemplate) -> Runnable - 参数说明:
llm:任何实现了BaseLLM接口的语言模型实例。tools:工具列表,每个工具需继承自BaseTool。prompt:必须包含{tools},{tool_names},{agent_scratchpad}占位符的ChatPromptTemplate。
- 返回值:一个
Runnable对象,通常传递给AgentExecutor进行执行。
- 所属库:
-
langchain.agents.AgentExecutor- 所属库:
langchain.agents - 方法签名:
AgentExecutor(agent: Runnable, tools: Sequence[BaseTool], verbose: bool = False, handle_parsing_errors: bool = True, max_iterations: int = 15) - 核心方法:
invoke(inputs: Dict[str, Any]) -> Dict[str, Any]:同步执行智能体并返回结果。ainvoke(inputs: Dict[str, Any]) -> Dict[str, Any]:异步执行版本。
- 所属库:
Demo 示例
运行说明:
- 确保
Python 3.10+及Poetry已安装。 - 创建项目并添加上述
pyproject.toml依赖,执行poetry install。 - 在项目根目录创建
.env文件,填入有效的OPENAI_API_KEY和SERPAPI_API_KEY。 - 在终端执行
poetry run python agent.py。
技术点总结:
- 演示了
LangChain 0.3基于create_react_agent构建单智能体的标准流程。 - 展示了外部工具(
SerpAPI)的集成方式与提示词工程的关键约束。 - 通过
verbose=True观察了 ReAct 循环的完整推理链条,直观理解“观察-思考-行动”闭环。
参考文档
官方文档
参考链接
总结
本文聚焦于 AI Agent 领域的单智能体技术栈。首先厘清了单智能体作为“单一决策核心”的架构定义及其与多智能体系统的本质区别;随后深入剖析了 ReAct(推理+行动) 这一核心运行范式的闭环机制。
在工程实践层面,基于 LangChain 0.3 框架,详细拆解了利用 create_react_agent 构建可运行智能体的三要素——LLM、提示词模板与工具集,并给出了完整的代码实战与版本兼容性解决方案(Pydantic v2 强制锁定)。
此外,前瞻性地引入了 LangGraph 作为复杂场景下的演进方向,对比了两种架构的适用边界。本文为开发者提供了从理论概念到可运行 Demo 的完整路径。
488



被折叠的 条评论
为什么被折叠?



