1. 项目概述从“聊天机器人”到“智能执行体”的跨越如果你已经玩过ChatGPT、Claude这类大语言模型可能会觉得它们很聪明能回答各种问题甚至能写代码、做分析。但不知你有没有过这样的感觉它就像一个知识渊博但“四肢瘫痪”的顾问只能动嘴不能动手。你问它“今天天气怎么样”它能告诉你查询天气的步骤但无法直接给你一个结果你让它“帮我订一张明天去上海的机票”它也只能提供订票网站的链接和注意事项。这种“知道但做不到”的割裂感正是传统LLM应用的瓶颈所在。而Agent智能体的出现就是为了解决这个问题。它不再是一个单纯的对话模型而是一个具备“大脑”和“手脚”的自主执行系统。简单来说Agent LLM大脑 Tools手脚 一个协调两者的“思维框架”。LLM负责理解你的意图、制定计划、做出决策Tools则是它可调用的具体能力比如执行代码、调用API、查询数据库、操作文件等。Agent的核心价值在于它能将LLM的推理规划能力与外部工具的执行能力结合起来形成一个完整的感知-思考-行动闭环。在这个领域LangChain无疑是最受瞩目的框架之一。它就像为LLM打造的一个“万能工具箱”和“操作系统”提供了构建Agent所需的各种标准化组件和最佳实践模式。通过LangChain开发者可以像搭积木一样快速地将不同的LLM、记忆模块、工具链组合起来构建出能够解决复杂、多步骤任务的智能体。今天我们就来动手打造你的第一个LangChain Agent。这不是一个简单的“Hello World”而是一个能真正完成一项实际任务的、具备完整闭环能力的智能体。我们将从最核心的“大脑-手脚”协作原理讲起一步步拆解架构并用代码实现一个能联网搜索、进行数学计算、并给出结构化答案的实用Agent。无论你是想了解AI应用开发的前沿还是希望为自己的项目添加自动化智能这篇文章都将为你提供一个扎实的起点。2. 智能体核心架构拆解大脑、手脚与协调器要理解如何构建一个Agent首先得彻底弄明白它的内部工作机制。一个典型的LangChain Agent主要由三大核心部分组成我们可以用一个“特种作战小队”来类比理解。2.1 LLM作为“决策大脑”的指挥官LLM大语言模型在Agent中扮演着“指挥官”或“大脑”的角色。它的核心职责不是直接生成最终答案而是进行任务规划、工具调度和结果解析。任务拆解与规划当你给Agent一个复杂指令比如“查一下特斯拉最新的股价并计算如果我现在买入100股需要多少钱最后用中文总结给我”。LLM大脑需要将这个指令分解成一系列可执行的子任务1. 搜索“特斯拉 股价”2. 从结果中提取最新股价数字3. 用股价乘以100计算总金额4. 用中文组织答案。工具选择与调用面对分解后的子任务LLM需要判断每个任务应该调用哪个工具Tool来完成。例如搜索股价需要调用“搜索引擎工具”数学计算需要调用“计算器工具”。LLM会根据对任务的理解和工具的描述决定下一步该“指挥”哪只“手”去工作。结果解析与迭代工具执行后会返回结果比如搜索到的网页摘要或计算出的数字。LLM需要解析这个结果判断任务是否完成。如果未完成例如搜索结果没有直接给出股价它可能需要调整策略重新规划或调用其他工具直到得出最终结论。这里的关键在于我们提供给LLM的“上下文”不仅包括用户的问题还包括一套工具说明书Tool Description。LLM通过阅读这些说明书来学习每个工具能干什么、怎么用。因此编写清晰、准确、无歧义的工具描述是Agent能否正确工作的首要前提。2.2 Tools作为“执行手脚”的特种兵Tools是Agent与外部世界交互的接口是它的“手”和“脚”。一个Tool本质上就是一个函数它封装了某种特定的能力。LangChain社区已经提供了海量的内置工具和第三方工具集成。常见的Tool类型包括信息获取类如SerpAPI谷歌搜索、WikipediaAPI维基百科查询、DuckDuckGoSearchRun搜索引擎。这是Agent的“眼睛”和“耳朵”。计算与处理类如LLMMathChain利用LLM进行数学计算、PythonREPLTool执行Python代码。这是Agent的“计算器”和“编程手”。软件与系统交互类如操作文件、发送邮件、调用数据库、控制智能家居的API等。这赋予了Agent操作物理世界和数字世界的能力。在构建Agent时选择哪些Tools直接决定了Agent的能力边界。一个好的实践是从解决一个具体问题出发按需引入工具避免过度设计。例如一个专注于金融分析的Agent可能需要股票数据API、财报解析工具和图表生成工具而不需要图像识别工具。2.3 Agent Executor作为“协调中枢”的调度员有了大脑和手脚还需要一个高效的“神经系统”来协调它们。这就是Agent Executor。你可以把它想象成项目调度员或流程引擎它负责管理Agent运行的整个生命周期循环。其工作流程是一个典型的ReActReason Act模式循环观察将用户输入和当前对话历史记忆传递给LLM大脑。思考LLM根据输入和可用工具列表思考下一步该做什么。它会输出一个结构化的“动作”Action指定要使用哪个工具以及输入什么参数。行动Agent Executor捕获这个“动作”调用对应的Tool并传入参数。观察结果Tool执行完毕返回一个“观察结果”Observation。再思考Agent Executor将“动作”和“观察结果”一起作为新的上下文再次传递给LLM。LLM根据工具执行的结果决定下一步是继续调用另一个工具还是认为任务已经完成可以生成最终答案给用户。循环或结束上述步骤循环进行直到LLM输出一个标志着最终答案的响应。这个循环是Agent智能的核心体现。它允许Agent在复杂任务中“走一步看一步”根据上一步的结果动态调整后续计划具备了初步的自主性和适应性。注意这个循环不是无限的。为了防止Agent陷入死循环比如在某个问题上反复调用工具却无法推进必须设置最大迭代次数max_iterations。通常设置10-15次对于大多数任务已经足够。这是一个非常重要的安全性和稳定性配置。3. 环境准备与核心工具选型在开始编码之前我们需要搭建开发环境并做出几个关键的技术选型。这些选择将直接影响后续开发的效率和Agent的能力。3.1 基础环境搭建首先确保你有一个Python环境建议3.8以上版本。我们使用虚拟环境来管理依赖避免包冲突。# 创建并激活虚拟环境以conda为例也可使用venv conda create -n langchain-agent python3.10 conda activate langchain-agent # 安装LangChain核心库及常用扩展 pip install langchain langchain-community langchain-core # 安装OpenAI库如果我们使用GPT作为大脑 pip install openai # 安装用于Agent的特定库例如用于数学计算的 pip install langchain-experimental # 可能包含一些实验性但好用的Agent组件 # 安装Jupyter notebook或Lab方便交互式开发可选但推荐 pip install jupyterlab3.2 LLM“大脑”的选型OpenAI GPT vs. 开源模型选择哪个LLM作为Agent的“大脑”是第一个关键决策。目前主要有两条路径路径一使用商用API如OpenAI GPT系列优点开箱即用能力强大且稳定在复杂推理、工具调用遵循指令方面表现最佳。对于学习和构建原型来说这是最快、最省心的选择。缺点产生持续费用有速率限制并且所有数据需要发送到第三方服务器。如何选择型号对于Agent任务gpt-3.5-turbo在性价比和速度上是不错的起点。如果任务非常复杂或需要更强的推理能力可以升级到gpt-4或gpt-4-turbo。关键是要确保你选择的模型支持“函数调用”Function Calling功能这是LangChain Agent与模型交互的基石。路径二使用本地部署的开源模型如Llama 3, Qwen, DeepSeek优点数据隐私性好无使用费用可定制化程度高。缺点需要较强的硬件资源GPU模型管理和推理优化有一定门槛在工具调用的指令遵循上可能不如顶级商用API稳定。如何操作可以使用Ollama、vLLM或Transformers库来本地运行模型。在LangChain中通过ChatOllama或ChatOpenAI配置本地API端点来接入。实操心得对于第一个Agent项目强烈建议从OpenAI GPT-3.5/4开始。它能让你专注于理解Agent的工作流程和架构而不是在模型部署和调试上耗费大量精力。当核心逻辑跑通后再考虑迁移到开源模型进行优化和私有化部署。3.3 关键“手脚”Tools的选择与配置我们将构建一个能回答实时信息和进行计算的Agent因此需要以下工具搜索工具SerpAPI让Agent能获取最新的网络信息。你需要去 SerpAPI官网 注册一个免费账户获取API密钥。免费额度足够学习和测试使用。计算工具LLMMathChain让Agent能进行精确的数学运算。这是一个LangChain内置的链它实际上会将数学问题转化为Python代码进行计算比单纯让LLM心算要可靠得多。Python REPL工具一个更通用的执行工具允许Agent运行Python代码。功能强大但需谨慎使用避免执行危险代码。在代码中我们将这样初始化和配置它们import os from langchain.agents import load_tools, Tool from langchain_community.utilities import SerpAPIWrapper from langchain.chains import LLMMathChain from langchain_community.agent_toolkits import create_python_agent from langchain_experimental.tools import PythonREPLTool # 设置API密钥请替换为你的实际密钥 os.environ[OPENAI_API_KEY] your-openai-api-key os.environ[SERPAPI_API_KEY] your-serpapi-api-key # 初始化搜索工具 search SerpAPIWrapper() # 初始化数学计算链需要先有一个LLM对象稍后创建 # llm_math LLMMathChain.from_llm(llmllm) # 稍后创建 # 定义工具列表。每个Tool对象都需要名称、函数、描述。 # 描述至关重要LLM靠它来决定是否调用该工具。 tools [ Tool( nameSearch, funcsearch.run, descriptionuseful for when you need to answer questions about current events or real-time information. Input should be a clear search query. ), # LLMMathChain 需要包装成Tool # Tool( # nameCalculator, # funcllm_math.run, # descriptionuseful for when you need to answer questions about math. Input should be a mathematical expression. # ), # PythonREPLTool() 本身就是一个Tool实例 ]注意上面代码中llm_math和Calculator工具被注释掉了因为我们需要先创建llm对象。我们将在后续完整代码中整合。工具描述Description的写作技巧明确用途用“useful for when you need to...”开头清晰界定使用场景。说明输入格式用“Input should be...”告诉LLM应该传入什么样的参数。避免歧义不要使用模糊的词汇。例如对于搜索工具说“find information”就不如“answer questions about current events”明确。差异化确保不同工具的描述有清晰的区别防止LLM选错工具。4. 构建你的第一个完整Agent从零到一的实战现在让我们把大脑、手脚和协调器组装起来创建一个能真正工作的Agent。我们将采用LangChain中最经典、最稳定的ZERO_SHOT_REACT_DESCRIPTIONAgent类型。它基于ReAct范式不需要示例Zero-Shot就能工作。4.1 初始化LLM与完整工具集首先完成所有组件的初始化。from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from langchain.chains import LLMMathChain # 1. 初始化LLM大脑 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # temperature设为0使输出更确定更适合执行任务。 # 2. 初始化并配置工具 search SerpAPIWrapper() llm_math LLMMathChain.from_llm(llmllm) tools [ Tool( nameSearch, funcsearch.run, descriptionUseful for when you need to answer questions about current events, real-time information, or general knowledge. Input should be a clear and concise search query in English or Chinese. ), Tool( nameCalculator, funcllm_math.run, descriptionUseful for answering questions that require arithmetic, algebra, or unit conversions. Input should be a well-formed mathematical expression or equation. ), # 谨慎添加Python REPL工具仅在你信任运行环境且需要复杂计算时使用 # PythonREPLTool(), ]4.2 创建Agent Executor并运行测试接下来使用initialize_agent函数将大脑和工具绑定在一起形成Agent Executor。# 3. 创建Agent agent initialize_agent( toolstools, llmllm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, # 使用Zero-Shot ReAct代理 verboseTrue, # 设为True可以看到Agent的思考过程对调试至关重要 handle_parsing_errorsTrue, # 优雅地处理解析错误避免程序崩溃 max_iterations10, # 防止无限循环设置最大迭代次数 early_stopping_methodgenerate, # 当Agent认为完成时可以提前停止 ) # 4. 运行一个测试查询 print( Agent 开始执行 ) try: response agent.invoke({ input: 特斯拉Tesla最新的股价是多少美元如果我想买50股总共需要花费多少人民币请用中文回答。 }) print(\n 最终答案 ) print(response[output]) except Exception as e: print(f执行过程中出现错误: {e})当你运行这段代码并将verboseTrue时你会在控制台看到类似以下的精彩输出 Entering new AgentExecutor chain... Thought: 用户想知道特斯拉的最新股价并计算购买50股需要多少人民币。这需要先获取股价然后进行货币换算。我应该先搜索特斯拉股价。 Action: Search Action Input: Tesla stock price latest USD Observation: Tesla Inc (TSLA) is trading at $245.78, up 1.5% today... Thought: 我找到了股价是245.78美元。现在需要计算50股的总美元金额然后换算成人民币。我需要用计算器。 Action: Calculator Action Input: 245.78 * 50 Observation: Answer: 12289.0 Thought: 50股的总价是12289美元。现在需要换算成人民币。我需要知道当前美元对人民币的汇率。我应该再搜索一下。 Action: Search Action Input: USD to CNY exchange rate latest Observation: 1 US Dollar 7.25 Chinese Yuan... Thought: 汇率是1美元兑7.25人民币。现在计算总人民币金额。 Action: Calculator Action Input: 12289 * 7.25 Observation: Answer: 89095.25 Thought: 我现在有了所有信息。可以给出最终答案了。 Final Answer: 根据最新信息特斯拉TSLA股价约为245.78美元。购买50股需要12289美元。按照当前汇率1美元≈7.25人民币这大约相当于89095.25人民币。 Finished chain. 最终答案 根据最新信息特斯拉TSLA股价约为245.78美元。购买50股需要12289美元。按照当前汇率1美元≈7.25人民币这大约相当于89095.25人民币。这个过程完美展示了Agent的ReAct循环思考Thought - 行动Action/Input - 观察Observation。它自主决定先搜索股价然后计算美元总价再搜索汇率最后计算人民币总价最终整合信息给出答案。4.3 代码深度解析与关键参数让我们拆解initialize_agent函数中的几个关键参数理解它们如何控制Agent的行为agentAgentType.ZERO_SHOT_REACT_DESCRIPTION这是Agent的类型。我们选择了零样本ReAct描述型它是最通用的类型之一完全依靠工具描述和LLM的指令遵循能力来工作。其他类型如STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION更适合需要复杂、结构化输出的场景。verboseTrue这是调试Agent最重要的开关。当它为True时你会看到Agent完整的思考链Chain of Thought如上例所示。这能让你清晰地知道Agent每一步在“想”什么为什么选择某个工具以及工具返回了什么结果。在开发阶段务必开启。handle_parsing_errorsTrueLLM的输出有时可能不符合Agent期望的格式比如没有正确生成Action:和Action Input:这会导致解析错误。设置这个参数为True可以让Agent Executor尝试修复或重新提示LLM而不是直接抛出异常导致程序停止。max_iterations10安全阀。它限制了Agent单次运行的最大步骤数防止因逻辑错误或任务过于复杂导致无限循环。根据任务复杂度调整一般10-20步足够。early_stopping_methodgenerate当LLM认为自己已经可以给出最终答案输出Final Answer:时即使未达到max_iterations也会提前停止。这提高了效率。避坑指南如果你看到Agent在反复执行相同的Action而毫无进展例如反复搜索同一个词条这通常意味着工具的描述不够清晰或者LLM无法从工具的返回结果中提取有效信息来推进任务。此时你需要检查工具描述或者优化工具的返回结果格式例如让搜索工具返回更简洁、结构化的摘要。5. 高级技巧与实战优化一个能跑起来的Agent只是开始。要让它在实际应用中稳定、可靠、高效还需要一些进阶技巧。5.1 为Agent赋予“记忆”能力默认的Zero-Shot Agent是“无状态”的它不会记住之前对话的内容。这在多轮对话中是个问题。LangChain提供了多种记忆Memory组件。添加对话记忆ConversationBufferMemoryfrom langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_with_memory initialize_agent( toolstools, llmllm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, # 注意需要更换为支持对话的Agent类型 verboseTrue, memorymemory, max_iterations10, )现在你可以进行多轮对话了agent_with_memory.invoke({input: 特斯拉股价多少}) agent_with_memory.invoke({input: 比昨天涨了还是跌了}) # Agent会记得我们刚才在讨论特斯拉CONVERSATIONAL_REACT_DESCRIPTIONAgent类型专门为处理带记忆的对话而设计。记忆不仅存储了对话历史有时也会被LLM用来总结或提取关键信息避免上下文过长。5.2 构建自定义工具Custom Tools内置工具虽好但真正的威力在于创建你自己的工具。假设我们想创建一个查询本地数据库用户信息的工具。from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type # 1. 定义工具的输入参数模型 class UserQueryInput(BaseModel): user_id: int Field(description用户的唯一ID) # 2. 创建自定义工具类继承BaseTool class UserDatabaseTool(BaseTool): name user_database_query description Useful for querying basic information of a user from the local database by user ID. args_schema: Type[BaseModel] UserQueryInput # 指定输入格式 def _run(self, user_id: int) - str: 执行工具的主逻辑 # 这里模拟一个数据库查询 # 真实场景下这里会是SQL查询或ORM调用 user_data { 1: 姓名: 张三, 角色: 管理员, 注册时间: 2023-01-01, 2: 姓名: 李四, 角色: 用户, 注册时间: 2023-05-15, } result user_data.get(user_id, f未找到ID为 {user_id} 的用户。) return result async def _arun(self, user_id: int) - str: 异步版本可选 # 如果工具需要异步操作在这里实现 raise NotImplementedError(此工具不支持异步调用) # 3. 实例化并添加到工具列表 custom_tool UserDatabaseTool() tools.append(custom_tool) # 4. 重新初始化带有自定义工具的Agent agent_custom initialize_agent(tools, llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue) # 5. 测试 response agent_custom.invoke({input: 请查询一下用户ID为1的信息。}) print(response[output])通过继承BaseTool并定义_run方法你可以将任何函数、API调用或系统操作封装成Agent可用的工具。args_schema利用Pydantic模型来定义和验证输入参数这能极大地帮助LLM理解如何调用你的工具。5.3 错误处理与稳定性提升Agent在复杂环境中运行难免出错。健壮的错误处理机制必不可少。工具调用错误网络超时、API限流、无效参数等。可以在自定义工具的_run方法内部进行try-catch返回友好的错误信息而不是抛出异常导致整个Agent崩溃。def _run(self, query: str) - str: try: # 调用可能失败的API result some_unstable_api(query) return result except TimeoutError: return 搜索工具请求超时请稍后再试。 except Exception as e: return f工具执行时发生错误{str(e)}。请简化您的问题或稍后重试。LLM输出解析错误即使设置了handle_parsing_errorsTrue有时LLM仍会输出无法解析的格式。一个更健壮的方法是使用OutputParser或自定义回调函数来捕获并重试。设置超时和重试对于网络工具可以在初始化时配置超时和重试逻辑。例如使用tenacity库为工具函数添加装饰器。5.4 使用LangSmith进行跟踪与调试可选但强力推荐当你的Agent逻辑变得复杂仅靠verboseTrue打印日志会难以管理。LangChain官方提供了LangSmith平台它是一个用于调试、测试和监控LLM应用的强大工具。它能做什么可视化跟踪以时间线或树状图的形式完整记录每一次LLM调用、工具调用的输入输出、耗时和token使用情况。比较与测试可以保存多次运行的记录对比不同Prompt或模型版本的效果。数据管理将成功的输入输出保存为数据集用于后续的评估或微调。基本使用import os os.environ[LANGCHAIN_TRACING_V2] true os.environ[LANGCHAIN_API_KEY] your-langsmith-api-key # 在LangSmith官网获取 os.environ[LANGCHAIN_PROJECT] My-First-Agent # 设置项目名设置好环境变量后再次运行你的Agent所有的调用轨迹都会自动记录到LangSmith的仪表盘中对于优化和排查问题有巨大帮助。6. 常见问题排查与性能调优实录在实际开发中你一定会遇到各种问题。下面是我在项目中踩过的一些坑和解决方案。6.1 Agent陷入循环或执行无关动作现象Agent反复调用同一个工具或者调用与任务明显无关的工具。根因1工具描述不清晰或重复。LLM无法区分两个相似的工具。解决重写工具描述强调每个工具的独特用途和输入格式。例如区分“搜索通用信息”和“搜索学术论文”。根因2任务过于复杂或模糊。LLM无法制定清晰的计划。解决在用户输入层面进行优化提供更具体、分步骤的指令。或者使用“Plan-and-Execute”模式的Agent先让一个LLM制定详细计划再让另一个LLM负责执行。根因3工具返回结果质量差。例如搜索工具返回了大量无关文本LLM无法提取有效信息。解决对工具返回的结果进行预处理。例如使用另一个LLM对搜索结果进行摘要提取再将简洁的摘要返回给主Agent。6.2 Agent忽略某些工具或错误选择工具现象明明提供了计算器Agent却尝试让LLM心算复杂公式。根因工具描述未能触发LLM的“调用意识”。LLM可能认为自己能直接解决或者没理解该用工具。解决在工具描述中加入强提示词。例如在计算器描述中写明“对于任何涉及数字计算的问题请务必使用此工具以获得精确结果不要尝试自行计算。”进阶在系统提示词System Prompt中明确强调Agent的角色和工具使用原则。例如“你是一个必须依靠工具来完成任务的助手。对于涉及实时数据、计算、代码执行的任务你必须调用相应的工具不得凭空想象或估算。”6.3 处理速度慢或Token消耗高现象简单的查询也耗时很长或者API调用费用激增。优化1精简上下文。每次迭代Agent的完整思考过程都会作为历史记录传给LLM这会导致上下文越来越长。使用ConversationSummaryMemory或ConversationBufferWindowMemory来限制或总结历史记录而不是无限制地堆积。优化2选择合适的模型。对于执行路径明确、逻辑简单的任务gpt-3.5-turbo在速度和成本上远优于gpt-4。只有在需要深度推理和复杂规划时才使用更强的模型。优化3设置合理的max_iterations。根据任务复杂度调整避免不必要的循环。优化4并行化工具调用。如果多个工具调用之间没有依赖关系可以考虑使用支持并行调用的Agent类型如一些实验性Agent或者用asyncio自行封装。6.4 安全性与权限控制警告赋予Agent执行代码PythonREPLTool、访问文件或调用API的能力是高风险操作。原则遵循最小权限原则。只授予Agent完成其核心职责所必需的最低权限。沙箱环境对于代码执行务必在严格的沙箱环境中进行限制网络访问、文件系统访问和运行时间。输入验证与过滤在自定义工具的_run方法中对所有输入参数进行严格的验证和清洗防止注入攻击。人工审核环Human-in-the-loop对于高风险操作如删除数据、发送邮件可以让Agent生成待执行命令但需要人工确认后才能实际执行。这可以通过LangChain的HumanApprovalCallbackHandler来实现。构建第一个能完整运行的LangChain Agent就像第一次让机器人学会了使用工具。你看到的不仅仅是代码的运行更是一个具备自主感知、决策和执行能力的智能雏形。从简单的搜索计算到未来连接数据库、操作软件、分析报告Agent的潜力在于将LLM的通用认知能力锚定到一个个具体的业务动作上。我个人最深的体会是成功的Agent项目30%在于模型和框架70%在于对“工具”的设计和对“任务”的拆解。如何把模糊的人类指令翻译成一套LLM能理解、工具能执行的清晰步骤是其中最需要打磨的艺术。不妨从今天这个小小的闭环开始尝试为它添加一两个你自己的工具解决一个你实际工作中的小痛点那种“它真的帮我做了”的成就感会是学习的最佳动力。