聊LangChain，绕不开的就是Agent。用过ChatGPT的人都知道，模型本身再强也只是个“建议者”，你问它今天天气如何，它只能抱歉地说自己不知道实时数据。但Agent不一样，它把模型从“会说话的百科全书”变成了“会动手办事的员工”——给定一个目标，它能自己拆解任务、调用工具、查阅外部数据、反复尝试，最后把结果交给你。这就是LangChain框架里智能体的核心价值。这篇内容我想从实操角度把LangChain中的智能体拆开讲透，适合已经会写几行Python、用过OpenAI或同类大模型API，但还没系统搞过Agent编排的开发者。废话不多说，直接进入正题。1. 智能体在LangChain中的定位与核心价值1.1 从“一次问答”到“自主完成任务”传统的大模型调用模式是“你问一句，模型答一句”，Prompt写好了，参数调对了，输出就固定了。这种模式适合翻译、总结、文本生成等一次性任务，但一旦遇到需要多步骤推理、需要实时数据、需要操作外部系统的场景，它就完全不够用。举个最简单的例子：你想让模型查一下某股票最近三个月的价格走势，并计算平均涨幅。如果只是普通调用，模型会坦诚地告诉你“我没有实时数据”。但换成Agent架构后，它会先把任务拆解成几个子任务：第一，确定股票的代码和交易所；第二，调用股票查询工具拉取近90天的历史价格；第三，用Python工具计算平均涨幅；第四，把这四个步骤的结果串成一段话回复你。这个过程中，用户只给了一个目标，中间的步骤全是Agent自己规划出来的。这正是LangChain智能体最核心的价值：把大模型从“问答引擎”升级成“任务执行引擎”。它不再是你说一句它答一句，而是你下达一个目标，它自行规划、调用工具、验证结果、直到完成目标或达到最大迭代次数。1.2 智能体的组成四要素LangChain中一个完整的Agent系统，拆开来看，其实只有四个核心组成部分：模型（LLM）：负责推理、规划、决策。它是Agent的“大脑”，所有关于“下一步做什么”的判断都由它做出。工具（Tools）：负责执行具体操作。查询天气、搜索网页、运行代码、操作数据库，这些都是工具。工具是Agent的“手脚”。记忆（Memory）：负责保存对话历史、中间结果、关键信息。没有记忆的Agent就像一个失忆的员工，每次出发前都得重新交代背景。规划器（Planner）：负责制定行动计划。LangChain里通常通过Prompt引导模型输出Thought（思考）、Action（动作）、Observation（观察）三个部分的循环来完成规划。这四个部分很好记：大脑、手脚、记事本、行动计划表。理解了这个模型，后面所有代码都不过是在把这四样东西拼装起来而已。2. 核心机制拆解：ReAct范式与工具调用循环2.1 什么是ReAct范式LangChain中智能体默认采用的工作模式叫做ReAct，全称是Reason and Act，直译过来是“推理与行动”。这个范式最早由学术界提出，后来被LangChain工程化为Agent的核心执行逻辑。ReAct的核心思想非常朴素：模型在每一轮循环中做两件事——先思考（给出Thought），再行动（给出Action），然后观察工具返回的结果（给出Observation），再根据观察继续思考，形成行动循环。打个比方：你让实习员工去调研一个竞品的定价策略，他不会一口气把所有事做完，而是一步一步来——先想“我需要知道对方官网的报价”，于是打开浏览器搜索，看到结果后再想“价格信息在某个页面里”，于是他点进那个页面，看到具体价格后再想“还需要对比我们自己的定价”，于是他调取内部表格……每一步思考和行动交替进行，直到任务完成。在LangChain中，ReAct循环通常被封装在AgentExecutor或LangGraph的自定义循环里。每一轮循环包含：模型根据当前状态输出一个文本片段，其中包含Thought和Action指令；解析器把Action指令解析成具体的工具名称和参数；对应的工具被执行，返回Observation；观察结果被追加到对话历史中；模型拿到新的历史，再输出下一轮Thought和Action。整个循环一直重复，直到模型输出“Final Answer”或者循环次数达到上限。2.2 工具调用循环的本质很多初学者以为工具调用是模型直接发起一个函数调用，其实不是。在LangChain里，模型输出的Action本质上是一段结构化文本，通常采用JSON格式，包含工具名称和参数。LangChain的解析器拿到这个JSON后，才真正去Python环境里寻找并执行对应的函数。这段流程拆开看是：# 模型输出示例（伪代码） Thought: 用户想知道天气，我需要调用天气查询工具 Action: {"action": "get_weather", "action_input": {"city": "杭州", "date": "today"}}解析器提取到工具名get_weather和参数{"city": "杭州"}后，把它转换为实际的函数调用，再把函数的返回值包装成Observation送回模型。模型拿到Observation后，继续推理，直到能给出最终答案。这种设计的好处是明显的：模型不需要真正执行代码，它只需要“声明”它想调用什么工具、传入什么参数，实际执行交给框架和Python运行时。这大大降低了模型直接操作系统的风险，也使得工具的扩展变得非常容易——只要在工具列表里注册一个新函数，模型就能在推理中自动发现并使用它。2.3 LangChain与LangGraph的两种实现方式这里必须提一个让很多人困惑的问题：新版LangChain中，传统AgentExecutor和LangGraph有什么区别？老牌的AgentExecutor是LangChain 0.1及以前的主推方案。它把ReAct循环封装在一个高层的Executor类里，开发者只需要创建Agent并传入工具列表，剩下的循环过程由框架托管。优点是简单、代码量少、上手快；缺点是循环过程是黑盒，遇到循环卡死、工具调用异常等问题时，很难在循环内部做干预。LangGraph则是LangChain团队推出的新一代编排框架，它把Agent的循环拆成了显式的图结构：节点代表“模型调用”或“工具执行”，边代表“下一步去哪”。开发者可以精确控制每个节点的输入输出，也可以在任意位置插入条件判断、人工审核、缓存逻辑。我个人的建议是：如果你只是在做原型验证、写Demo、快速跑通流程，用老牌的AgentExecutor完全没问题，代码量少，心智负担低。但如果你要做生产级应用、需要精细控制Agent行为、要对循环过程做观测和干预，一定要学LangGraph，而且越早越好，因为LangChain的社区和新特性明显在往LangGraph倾斜。3. 工具定义与选择：让智能体真正“动手”3.1 工具的本质是一个带描述的函数LangChain中定义一个工具，本质上就是把一个普通Python函数包装成模型可以理解的形式。最关键的不是函数本身，而是三个附加信息：函数名、功能描述、参数说明。很多人会忽略描述的重要性，但实际使用中，描述的质量直接决定模型能不能选对工具。我举个反例：你定义了一个搜索天气的工具，如果你把描述写成“获取天气信息”，模型在需要查询天气时确实能选对它。但如果你的系统里有五个工具，其中有“获取城市天气”“获取城市空气质量”“获取城市未来一周天气预报”，描述如果写得模糊，模型就可能选错。所以一个合格的工具描述，应当说清楚三个问题：这个工具是干什么的、适合在什么场景下使用、参数各代表什么含义。比如：from langchain.tools import tool @tool def get_city_weather(city: str, date: str = "today") -> str: """查询指定城市在指定日期的天气情况，包括温度、降水概率、风力等级。 适用场景：用户询问“今天的天气怎么样”“明天会不会下雨”等包含时间地点的问题。 参数说明： - city: 城市名称，中文或拼音均可，例如“杭州”或“hangzhou” - date: 日期，支持"today"、"tomorrow"或"2025-03-01"格式，默认为今天 """ # 这里是调用天气API的实际逻辑 return f"{city} {date} 天气：晴，25°C，降水概率10%"看到没，描述里甚至写清楚了什么时候该用这个工具、参数格式是什么，模型选错的概率就会低很多。3.2 工具注册与参数Schema的坑LangChain的@tool装饰器会自动从函数的类型注解（Type Hints）和文档字符串（Docstring）中提取参数Schema，用于告诉模型“这个工具接受哪些参数”。这意味着你函数的类型注解必须写清楚，否则很可能出现模型生成了某个参数，但在实际调用时因为类型不匹配而报错。举个例子，如果你的函数定义是：@tool def add_numbers(a, b): """计算两个数字的和""" return a + b没有类型注解的话，LangChain解析到的参数Schema就是空泛的，模型可能传字符串进去，也可能把两个参数合并成一个JSON对象传进来，运行时极不稳定。正确写法是：@tool def add_numbers(a: int, b: int) -> int: """计算两个整数a和b的和，返回整数结果。""" return a + b还有一个我踩过的坑：参数名要尽量简洁且语义明确。模型在生成JSON时，会尽量按照参数名来猜测含义，如果你把参数命名为x1、x2这种，模型很难判断应该传入什么内容。更好的做法是用query、city、start_date这类自解释的名称。3.3 工具选择：不是越多越好很多人觉得工具越多，Agent越强大。这个想法大错特错。模型在每一步推理时，要把完整的工具列表和描述都放进上下文里，工具太多会导致两个问题：一是Token消耗暴涨，成本直线上升；二是模型选择工具的准确率下降，它面对一堆相似工具时很容易晕。一个比较实用的经验是：同一时间暴露给模型的核心工具最好控制在5到8个以内。如果你的系统有很多工具，可以考虑做工具分组或路由，让Agent先决定“该去哪一组里挑工具”，再具体选择。LangChain 0.2之后的版本支持ToolNode和工具路由，能把这层逻辑做得比较优雅。另外一个经验是：工具描述里的关键词要和你预期的用户提问方式对应起来。比如你有一个查快递的工具，描述里如果写了“查询物流信息”“快递单号”“包裹追踪状态”这些关键词，模型在面对用户五花八门的问法时，匹配的准确率会明显更高。4. 实操实录：从零搭建一个LangChain智能体4.1 环境准备与版本选择我先分享一下我常用的环境版本组合，这些版本都经过实测，跑通率比较高：Python 3.10+ langchain==0.3.x langchain-openai==0.2.x langgraph==0.2.x langchain-community==0.3.x安装命令很简单：pip install langchain langchain-openai langchain-community langgraph需要说明一点，很多人分不清langchain和langchain-community的区别。langchain是核心框架，负责Chain、Agent的编排逻辑；langchain-community里装的是各种第三方集成，比如浏览器工具、文件工具、数据库工具等。如果你要做Demo，大部分工具类定义都在community包里。4.2 定义一个实用的工具库我以一个“招聘信息助手”为案例来演示，这个场景既有工具调用、又有结构化输出，非常适合入门。假设我们要做一个小助手，它能根据用户输入的城市和岗位，查询某招聘平台的职位信息，还能根据职位描述计算薪酬中位数。工具库定义如下：from langchain.tools import tool @tool def search_jobs(city: str, keyword: str) -> str: """根据城市和岗位关键词搜索招聘信息，返回最多10条职位的标题、公司、月薪范围。 适用场景：用户提到“找工作”“招聘”“职位”“岗位”等关键词时。 参数说明： - city: 城市名称，如“上海”“北京”“杭州” - keyword: 岗位关键词，如“Java开发”“产品经理” """ # 这里应该调用某招聘平台的API，为了演示，我们模拟返回结果 jobs = [ {"title": "Java开发工程师", "company": "某科技公司", "salary": "15k-25k"}, {"title": "资深后端工程师", "company": "某电商平台", "salary": "25k-40k"}, ] return str(jobs) @tool def calculate_median_salary(jobs_str: str) -> str: """从职位信息字符串中提取月薪区间，计算中位数，返回一个总结。 参数说明： - jobs_str: 职位信息字符串，通常是search_jobs工具的返回结果 """ # 用正则提取所有薪水数字，计算中位数 import re salaries = [] for match in re.findall(r"(\d+)k-(\d+)k", jobs_str): low, high = int(match[0]), int(match[1]) salaries.extend([low, high]) if not salaries: return "无法从提供的信息中解析薪水数据" salaries.sort() mid = salaries[len(salaries) // 2] return f"该列表中年薪中位数约为{mid}k/月"这里我刻意设计了两个工具有先后依赖关系：先搜索职位，再基于搜索结果计算中位数。Agent必须理解这个先后顺序，才能正确串联工具。这也是验证Agent推理能力的好案例。4.3 构建Agent并执行任务接下来是核心代码，构建一个能自主规划、调用工具的Agent：from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain.prompts import ChatPromptTemplate # 初始化模型，temperature调低，让Agent更专注执行任务 llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) # 工具列表 tools = [search_jobs, calculate_median_salary] # 提示词模板 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个专业的招聘信息助手。你可以使用工具查询职位信息，并进行分析。回复时请使用简体中文，条理清晰。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 创建Agent agent = create_tool_calling_agent(llm, tools, prompt) # 创建执行器 executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=5) # 执行任务 result = executor.invoke({"input": "帮我查一下杭州的Python开发岗位，并分析薪资中位数是多少"}) print(result["output"])执行过程你可以打开verbose=True参数来看，它会打印每一轮的Thought、Action、Observation，非常直观。我当时第一跑这个案例的时候，看到模型自己规划出“先查职位→再算中位数”的链条，确实很震撼。这里要注意的是max_iterations参数。有些任务Agent会绕圈子，反复调用同一个工具，如果没有上限，可能几分钟都跑不完，Token费用也刹不住。我一般设为5到8，既能覆盖大多数正常任务，又能强制终止异常循环。4.4 用LangGraph实现同样的Agent如果你要更精细地控制流程，LangGraph的写法是这样：from langgraph.graph import StateGraph, END from typing import TypedDict, List class AgentState(TypedDict): messages: List[str] current_tool: str tool_input: dict def call_model(state): # 调用模型，让模型决定是调用工具还是给出最终回答 response = llm.invoke(state["messages"]) return {"messages": [response]} def call_tool(state): # 根据模型输出的工具调用指令，执行对应工具 tool_name = state["current_tool"] tool_input = state["tool_input"] tool_map = {t.name: t for t in tools} result = tool_map[tool_name].invoke(tool_input) return {"messages": [("observation", result)]} def should_continue(state): # 判断是否继续循环：模型如果是最终回答则不继续 if state["current_tool"] == "final_answer": return END return "tool_node" graph = StateGraph(AgentState) graph.add_node("model", call_model) graph.add_node("tool_node", call_tool) graph.add_edge("model", "tool_node") graph.add_conditional_edges("model", should_continue) graph.set_entry_point("model")LangGraph的核心思路是把“模型决策”和“工具执行”拆成独立的节点，中间用条件边控制走向。这种设计让你可以在每个节点前后插入日志、监控、缓存、人工审批等逻辑，生产环境里的可观测性会强很多。我实测过两种实现方式，结论是：如果只是Demo或学习，用AgentExecutor就够了，代码量少、报错信息友好；如果要上线，LangGraph是更稳的选择，它的状态管理机制让调试和扩展都清晰很多。5. 常见问题与排查技巧实录5.1 Agent陷入无限循环这是使用Agent时最常遇到的问题。表现是Agent反复调用同一个工具，每次都拿到相同的结果，然后继续调用，像个死循环一样永不停止。排查思路有三步。第一步，确认是否设置了max_iterations，如果没设置，很可能费用耗光前循环根本停不下来。第二步，打开verbose=True看最后一两轮的输出，通常能发现模型在重复“Observation没变化→Action重复”的模式，这说明模型没有从Observation中提取到有效信息，或者Prompt里没有明确指示“观察结果不变时应该改变策略”。第三步，检查工具返回的结果是否太简短，如果Observation只是“查询成功”而没有实际数据，模型没有足够信息来决定下一步，就会陷入原地打转。我通常会在System Prompt里加一句：如果某个工具返回的结果与前一次相同，必须选择其他方案或直接给出当前可得到的答案。这条指令能显著减少循环卡死的情况。5.2 工具参数解析失败模型生成了工具调用，但实际执行时报参数错误，这在中文场景下特别常见。比如日期格式、城市名称格式，模型可能自由发挥。解决办法有两个层面。第一层，工具的参数描述里写清楚格式示例，例子越多越好。第二层，在工具函数内部做容错解析，比如用正则或字典映射把常见变体归一化成标准格式。我之前做过一个查天气的工具，用户说“上海明天天气”，模型生成的参数可能是{"city": "上海", "date": "明天"}，也可能是{"city": "shanghai", "date": "2025-03-02"}，如果不做归一化，工具很容易报错。后来我在函数里加了日期转换逻辑和城市别名映射，问题基本消失。5.3 模型选错工具选错工具通常是工具描述写得不好导致的。比如你的系统里同时有“查询当日天气”和“查询未来一周天气预报”，如果两个工具的描述都只写“查询天气”，模型根本分不清该用哪个。这种情况下，最好的办法是重写描述，把使用场景写得非常具体。比如“未来一周天气预报”的描述可以写成：“当用户询问未来几天、一周或更长时间的天气时使用。此工具返回每日的最高温、最低温和降水概率。”这样模型在匹配用户意图时，依据就明确多了。5.4 上下文长度爆炸Agent循环次数一多，每轮的Thought、Action、Observation都会累积在上下文里，Token消耗直线上升。尤其是工具返回值非常大的场景，比如搜索返回了几万字的文章内容，后面所有轮次都会带着这些内容反复重读，费用非常吓人。我的做法是：工具返回前先做截断或摘要，只保留最核心的信息。比如搜索工具只返回前3条结果，每条截断到200字以内。另一个做法是定期压缩历史，可以用LLM把早期轮次的内容总结成一段摘要，替代原始记录。LangGraph里有现成的摘要节点可以接，AgentExecutor里则需要自己写逻辑。5.5 常见问题速查表症状可能原因推荐解法Agent反复调用同一工具工具返回信息不足，或Prompt缺少循环中断指令增加max_iterations上限；在Prompt中指示观察不变时换策略工具调用报参数错误类型注解缺失或描述不具体补全类型注解；在描述中给出参数格式示例选错工具工具描述模糊、工具数量太多重写描述明确适用场景；精简工具数量上下文Token爆炸循环轮次多，工具返回内容过大工具返回前做摘要/截断；定期压缩历史费用过高循环无上限、模型选错模型档位设置max_iterations；小任务用小模型，大任务才用大模型结果格式不可控模型自由发挥输出格式用OutputParser强制结构化输出6. 把Agent推向生产前，必须想清楚的几件事6.1 成本与速度的平衡Agent虽然强大，但它比一次普通的API调用贵得多。我的实测经验是，一个中等复杂的任务，通常需要3到6轮循环，每轮都要把累计的上下发送给模型，Token消耗可能是直接问答的5到10倍。如果你是做Demo，用gpt-4o-mini这类轻量模型就够了，便宜、速度快。但如果你遇到需要强推理能力的任务，比如金融分析、代码生成，轻量模型容易在复杂推理环节掉链子。此时可以考虑混合策略：简单轮次用轻量模型，关键决策轮次切换到大模型。LangGraph里每个节点可以指定不同的模型，实现起来并不复杂。6.2 人工审核的兜底机制Agent自主程度越高，越需要人工审核的兜底。尤其是在涉及数据库写入、文件删除、发送邮件等“有副作用”的操作时，我强烈建议加入“人工确认”环节。LangGraph中实现起来很直接：在工具执行节点前插入一个判断，如果工具属于高风险的写操作，就暂停执行，把待执行内容和参数推给人工确认，确认通过后再继续。我在项目里就用过这个模式，效果非常好。模型负责规划，人能保持在关键节点上审核，两者配合比完全放手要靠谱得多。6.3 工具权限的粒度控制别把所有工具都无差别暴露给Agent。比如你的系统里既有只读查询工具，又有写库工具，模型如果有权限直接调用写库工具，误操作的风险很大。建议按任务场景工具分组，不同场景的Agent挂载不同的工具列表。另外，工具的描述本质上是在告诉模型“你有哪些能力”，能力越大，责任越大。如果某个工具只允许特定场景使用，务必在描述里写清楚限制条件。模型虽然不会像人一样“手滑”，但它对描述的理解是字面层面的，限制条件写清楚，它才会避开。最后分享两个小经验一个是我在反复踩坑之后总结的：无论你用AgentExecutor还是LangGraph，先把verbose打开跑一遍再关掉。很多你觉得“不可思议”的错误，只要看见中间过程，立刻就明白了。另一个是关于工具描述的——如果你只能优化一个环节，优化它，而不是优化模型。模型选不选得对工具、用不用得好参数，大部分因素都落在工具定义的质量上。这是我调了很久Agent之后最有体感的一条心得。希望这篇内容能帮你少走些弯路。
聊LangChain，绕不开的就是Agent。用过ChatGPT的人都知道，模型本身再强也只是个“建议者”，你问它今天天气如何，它只能抱歉地说自己不知道实时数据。但Agent不一样，它把模型从“会说话的百科全书”变成了“会动手办事的员工”——给定一个目标，它能自己拆解任务、调用工具、查阅外部数据、反复尝试，最后把结果交给你。这就是LangChain框架里智能体的核心价值。这篇内容我想从实操角度把LangChain中的智能体拆开讲透，适合已经会写几行Python、用过OpenAI或同类大模型API，但还没系统搞过Agent编排的开发者。废话不多说，直接进入正题。1. 智能体在LangChain中的定位与核心价值1.1 从“一次问答”到“自主完成任务”传统的大模型调用模式是“你问一句，模型答一句”，Prompt写好了，参数调对了，输出就固定了。这种模式适合翻译、总结、文本生成等一次性任务，但一旦遇到需要多步骤推理、需要实时数据、需要操作外部系统的场景，它就完全不够用。举个最简单的例子：你想让模型查一下某股票最近三个月的价格走势，并计算平均涨幅。如果只是普通调用，模型会坦诚地告诉你“我没有实时数据”。但换成Agent架构后，它会先把任务拆解成几个子任务：第一，确定股票的代码和交易所；第二，调用股票查询工具拉取近90天的历史价格；第三，用Python工具计算平均涨幅；第四，把这四个步骤的结果串成一段话回复你。这个过程中，用户只给了一个目标，中间的步骤全是Agent自己规划出来的。这正是LangChain智能体最核心的价值：把大模型从“问答引擎”升级成“任务执行引擎”。它不再是你说一句它答一句，而是你下达一个目标，它自行规划、调用工具、验证结果、直到完成目标或达到最大迭代次数。1.2 智能体的组成四要素LangChain中一个完整的Agent系统，拆开来看，其实只有四个核心组成部分：模型（LLM）：负责推理、规划、决策。它是Agent的“大脑”，所有关于“下一步做什么”的判断都由它做出。工具（Tools）：负责执行具体操作。查询天气、搜索网页、运行代码、操作数据库，这些都是工具。工具是Agent的“手脚”。记忆（Memory）：负责保存对话历史、中间结果、关键信息。没有记忆的Agent就像一个失忆的员工，每次出发前都得重新交代背景。规划器（Planner）：负责制定行动计划。LangChain里通常通过Prompt引导模型输出Thought（思考）、Action（动作）、Observation（观察）三个部分的循环来完成规划。这四个部分很好记：大脑、手脚、记事本、行动计划表。理解了这个模型，后面所有代码都不过是在把这四样东西拼装起来而已。2. 核心机制拆解：ReAct范式与工具调用循环2.1 什么是ReAct范式LangChain中智能体默认采用的工作模式叫做ReAct，全称是Reason and Act，直译过来是“推理与行动”。这个范式最早由学术界提出，后来被LangChain工程化为Agent的核心执行逻辑。ReAct的核心思想非常朴素：模型在每一轮循环中做两件事——先思考（给出Thought），再行动（给出Action），然后观察工具返回的结果（给出Observation），再根据观察继续思考，形成行动循环。打个比方：你让实习员工去调研一个竞品的定价策略，他不会一口气把所有事做完，而是一步一步来——先想“我需要知道对方官网的报价”，于是打开浏览器搜索，看到结果后再想“价格信息在某个页面里”，于是他点进那个页面，看到具体价格后再想“还需要对比我们自己的定价”，于是他调取内部表格……每一步思考和行动交替进行，直到任务完成。在LangChain中，ReAct循环通常被封装在AgentExecutor或LangGraph的自定义循环里。每一轮循环包含：模型根据当前状态输出一个文本片段，其中包含Thought和Action指令；解析器把Action指令解析成具体的工具名称和参数；对应的工具被执行，返回Observation；观察结果被追加到对话历史中；模型拿到新的历史，再输出下一轮Thought和Action。整个循环一直重复，直到模型输出“Final Answer”或者循环次数达到上限。2.2 工具调用循环的本质很多初学者以为工具调用是模型直接发起一个函数调用，其实不是。在LangChain里，模型输出的Action本质上是一段结构化文本，通常采用JSON格式，包含工具名称和参数。LangChain的解析器拿到这个JSON后，才真正去Python环境里寻找并执行对应的函数。这段流程拆开看是：# 模型输出示例（伪代码） Thought: 用户想知道天气，我需要调用天气查询工具 Action: {"action": "get_weather", "action_input": {"city": "杭州", "date": "today"}}解析器提取到工具名get_weather和参数{"city": "杭州"}后，把它转换为实际的函数调用，再把函数的返回值包装成Observation送回模型。模型拿到Observation后，继续推理，直到能给出最终答案。这种设计的好处是明显的：模型不需要真正执行代码，它只需要“声明”它想调用什么工具、传入什么参数，实际执行交给框架和Python运行时。这大大降低了模型直接操作系统的风险，也使得工具的扩展变得非常容易——只要在工具列表里注册一个新函数，模型就能在推理中自动发现并使用它。2.3 LangChain与LangGraph的两种实现方式这里必须提一个让很多人困惑的问题：新版LangChain中，传统AgentExecutor和LangGraph有什么区别？老牌的AgentExecutor是LangChain 0.1及以前的主推方案。它把ReAct循环封装在一个高层的Executor类里，开发者只需要创建Agent并传入工具列表，剩下的循环过程由框架托管。优点是简单、代码量少、上手快；缺点是循环过程是黑盒，遇到循环卡死、工具调用异常等问题时，很难在循环内部做干预。LangGraph则是LangChain团队推出的新一代编排框架，它把Agent的循环拆成了显式的图结构：节点代表“模型调用”或“工具执行”，边代表“下一步去哪”。开发者可以精确控制每个节点的输入输出，也可以在任意位置插入条件判断、人工审核、缓存逻辑。我个人的建议是：如果你只是在做原型验证、写Demo、快速跑通流程，用老牌的AgentExecutor完全没问题，代码量少，心智负担低。但如果你要做生产级应用、需要精细控制Agent行为、要对循环过程做观测和干预，一定要学LangGraph，而且越早越好，因为LangChain的社区和新特性明显在往LangGraph倾斜。3. 工具定义与选择：让智能体真正“动手”3.1 工具的本质是一个带描述的函数LangChain中定义一个工具，本质上就是把一个普通Python函数包装成模型可以理解的形式。最关键的不是函数本身，而是三个附加信息：函数名、功能描述、参数说明。很多人会忽略描述的重要性，但实际使用中，描述的质量直接决定模型能不能选对工具。我举个反例：你定义了一个搜索天气的工具，如果你把描述写成“获取天气信息”，模型在需要查询天气时确实能选对它。但如果你的系统里有五个工具，其中有“获取城市天气”“获取城市空气质量”“获取城市未来一周天气预报”，描述如果写得模糊，模型就可能选错。所以一个合格的工具描述，应当说清楚三个问题：这个工具是干什么的、适合在什么场景下使用、参数各代表什么含义。比如：from langchain.tools import tool @tool def get_city_weather(city: str, date: str = "today") -> str: """查询指定城市在指定日期的天气情况，包括温度、降水概率、风力等级。 适用场景：用户询问“今天的天气怎么样”“明天会不会下雨”等包含时间地点的问题。 参数说明： - city: 城市名称，中文或拼音均可，例如“杭州”或“hangzhou” - date: 日期，支持"today"、"tomorrow"或"2025-03-01"格式，默认为今天 """ # 这里是调用天气API的实际逻辑 return f"{city} {date} 天气：晴，25°C，降水概率10%"看到没，描述里甚至写清楚了什么时候该用这个工具、参数格式是什么，模型选错的概率就会低很多。3.2 工具注册与参数Schema的坑LangChain的@tool装饰器会自动从函数的类型注解（Type Hints）和文档字符串（Docstring）中提取参数Schema，用于告诉模型“这个工具接受哪些参数”。这意味着你函数的类型注解必须写清楚，否则很可能出现模型生成了某个参数，但在实际调用时因为类型不匹配而报错。举个例子，如果你的函数定义是：@tool def add_numbers(a, b): """计算两个数字的和""" return a + b没有类型注解的话，LangChain解析到的参数Schema就是空泛的，模型可能传字符串进去，也可能把两个参数合并成一个JSON对象传进来，运行时极不稳定。正确写法是：@tool def add_numbers(a: int, b: int) -> int: """计算两个整数a和b的和，返回整数结果。""" return a + b还有一个我踩过的坑：参数名要尽量简洁且语义明确。模型在生成JSON时，会尽量按照参数名来猜测含义，如果你把参数命名为x1、x2这种，模型很难判断应该传入什么内容。更好的做法是用query、city、start_date这类自解释的名称。3.3 工具选择：不是越多越好很多人觉得工具越多，Agent越强大。这个想法大错特错。模型在每一步推理时，要把完整的工具列表和描述都放进上下文里，工具太多会导致两个问题：一是Token消耗暴涨，成本直线上升；二是模型选择工具的准确率下降，它面对一堆相似工具时很容易晕。一个比较实用的经验是：同一时间暴露给模型的核心工具最好控制在5到8个以内。如果你的系统有很多工具，可以考虑做工具分组或路由，让Agent先决定“该去哪一组里挑工具”，再具体选择。LangChain 0.2之后的版本支持ToolNode和工具路由，能把这层逻辑做得比较优雅。另外一个经验是：工具描述里的关键词要和你预期的用户提问方式对应起来。比如你有一个查快递的工具，描述里如果写了“查询物流信息”“快递单号”“包裹追踪状态”这些关键词，模型在面对用户五花八门的问法时，匹配的准确率会明显更高。4. 实操实录：从零搭建一个LangChain智能体4.1 环境准备与版本选择我先分享一下我常用的环境版本组合，这些版本都经过实测，跑通率比较高：Python 3.10+ langchain==0.3.x langchain-openai==0.2.x langgraph==0.2.x langchain-community==0.3.x安装命令很简单：pip install langchain langchain-openai langchain-community langgraph需要说明一点，很多人分不清langchain和langchain-community的区别。langchain是核心框架，负责Chain、Agent的编排逻辑；langchain-community里装的是各种第三方集成，比如浏览器工具、文件工具、数据库工具等。如果你要做Demo，大部分工具类定义都在community包里。4.2 定义一个实用的工具库我以一个“招聘信息助手”为案例来演示，这个场景既有工具调用、又有结构化输出，非常适合入门。假设我们要做一个小助手，它能根据用户输入的城市和岗位，查询某招聘平台的职位信息，还能根据职位描述计算薪酬中位数。工具库定义如下：from langchain.tools import tool @tool def search_jobs(city: str, keyword: str) -> str: """根据城市和岗位关键词搜索招聘信息，返回最多10条职位的标题、公司、月薪范围。 适用场景：用户提到“找工作”“招聘”“职位”“岗位”等关键词时。 参数说明： - city: 城市名称，如“上海”“北京”“杭州” - keyword: 岗位关键词，如“Java开发”“产品经理” """ # 这里应该调用某招聘平台的API，为了演示，我们模拟返回结果 jobs = [ {"title": "Java开发工程师", "company": "某科技公司", "salary": "15k-25k"}, {"title": "资深后端工程师", "company": "某电商平台", "salary": "25k-40k"}, ] return str(jobs) @tool def calculate_median_salary(jobs_str: str) -> str: """从职位信息字符串中提取月薪区间，计算中位数，返回一个总结。 参数说明： - jobs_str: 职位信息字符串，通常是search_jobs工具的返回结果 """ # 用正则提取所有薪水数字，计算中位数 import re salaries = [] for match in re.findall(r"(\d+)k-(\d+)k", jobs_str): low, high = int(match[0]), int(match[1]) salaries.extend([low, high]) if not salaries: return "无法从提供的信息中解析薪水数据" salaries.sort() mid = salaries[len(salaries) // 2] return f"该列表中年薪中位数约为{mid}k/月"这里我刻意设计了两个工具有先后依赖关系：先搜索职位，再基于搜索结果计算中位数。Agent必须理解这个先后顺序，才能正确串联工具。这也是验证Agent推理能力的好案例。4.3 构建Agent并执行任务接下来是核心代码，构建一个能自主规划、调用工具的Agent：from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain.prompts import ChatPromptTemplate # 初始化模型，temperature调低，让Agent更专注执行任务 llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) # 工具列表 tools = [search_jobs, calculate_median_salary] # 提示词模板 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个专业的招聘信息助手。你可以使用工具查询职位信息，并进行分析。回复时请使用简体中文，条理清晰。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 创建Agent agent = create_tool_calling_agent(llm, tools, prompt) # 创建执行器 executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=5) # 执行任务 result = executor.invoke({"input": "帮我查一下杭州的Python开发岗位，并分析薪资中位数是多少"}) print(result["output"])执行过程你可以打开verbose=True参数来看，它会打印每一轮的Thought、Action、Observation，非常直观。我当时第一跑这个案例的时候，看到模型自己规划出“先查职位→再算中位数”的链条，确实很震撼。这里要注意的是max_iterations参数。有些任务Agent会绕圈子，反复调用同一个工具，如果没有上限，可能几分钟都跑不完，Token费用也刹不住。我一般设为5到8，既能覆盖大多数正常任务，又能强制终止异常循环。4.4 用LangGraph实现同样的Agent如果你要更精细地控制流程，LangGraph的写法是这样：from langgraph.graph import StateGraph, END from typing import TypedDict, List class AgentState(TypedDict): messages: List[str] current_tool: str tool_input: dict def call_model(state): # 调用模型，让模型决定是调用工具还是给出最终回答 response = llm.invoke(state["messages"]) return {"messages": [response]} def call_tool(state): # 根据模型输出的工具调用指令，执行对应工具 tool_name = state["current_tool"] tool_input = state["tool_input"] tool_map = {t.name: t for t in tools} result = tool_map[tool_name].invoke(tool_input) return {"messages": [("observation", result)]} def should_continue(state): # 判断是否继续循环：模型如果是最终回答则不继续 if state["current_tool"] == "final_answer": return END return "tool_node" graph = StateGraph(AgentState) graph.add_node("model", call_model) graph.add_node("tool_node", call_tool) graph.add_edge("model", "tool_node") graph.add_conditional_edges("model", should_continue) graph.set_entry_point("model")LangGraph的核心思路是把“模型决策”和“工具执行”拆成独立的节点，中间用条件边控制走向。这种设计让你可以在每个节点前后插入日志、监控、缓存、人工审批等逻辑，生产环境里的可观测性会强很多。我实测过两种实现方式，结论是：如果只是Demo或学习，用AgentExecutor就够了，代码量少、报错信息友好；如果要上线，LangGraph是更稳的选择，它的状态管理机制让调试和扩展都清晰很多。5. 常见问题与排查技巧实录5.1 Agent陷入无限循环这是使用Agent时最常遇到的问题。表现是Agent反复调用同一个工具，每次都拿到相同的结果，然后继续调用，像个死循环一样永不停止。排查思路有三步。第一步，确认是否设置了max_iterations，如果没设置，很可能费用耗光前循环根本停不下来。第二步，打开verbose=True看最后一两轮的输出，通常能发现模型在重复“Observation没变化→Action重复”的模式，这说明模型没有从Observation中提取到有效信息，或者Prompt里没有明确指示“观察结果不变时应该改变策略”。第三步，检查工具返回的结果是否太简短，如果Observation只是“查询成功”而没有实际数据，模型没有足够信息来决定下一步，就会陷入原地打转。我通常会在System Prompt里加一句：如果某个工具返回的结果与前一次相同，必须选择其他方案或直接给出当前可得到的答案。这条指令能显著减少循环卡死的情况。5.2 工具参数解析失败模型生成了工具调用，但实际执行时报参数错误，这在中文场景下特别常见。比如日期格式、城市名称格式，模型可能自由发挥。解决办法有两个层面。第一层，工具的参数描述里写清楚格式示例，例子越多越好。第二层，在工具函数内部做容错解析，比如用正则或字典映射把常见变体归一化成标准格式。我之前做过一个查天气的工具，用户说“上海明天天气”，模型生成的参数可能是{"city": "上海", "date": "明天"}，也可能是{"city": "shanghai", "date": "2025-03-02"}，如果不做归一化，工具很容易报错。后来我在函数里加了日期转换逻辑和城市别名映射，问题基本消失。5.3 模型选错工具选错工具通常是工具描述写得不好导致的。比如你的系统里同时有“查询当日天气”和“查询未来一周天气预报”，如果两个工具的描述都只写“查询天气”，模型根本分不清该用哪个。这种情况下，最好的办法是重写描述，把使用场景写得非常具体。比如“未来一周天气预报”的描述可以写成：“当用户询问未来几天、一周或更长时间的天气时使用。此工具返回每日的最高温、最低温和降水概率。”这样模型在匹配用户意图时，依据就明确多了。5.4 上下文长度爆炸Agent循环次数一多，每轮的Thought、Action、Observation都会累积在上下文里，Token消耗直线上升。尤其是工具返回值非常大的场景，比如搜索返回了几万字的文章内容，后面所有轮次都会带着这些内容反复重读，费用非常吓人。我的做法是：工具返回前先做截断或摘要，只保留最核心的信息。比如搜索工具只返回前3条结果，每条截断到200字以内。另一个做法是定期压缩历史，可以用LLM把早期轮次的内容总结成一段摘要，替代原始记录。LangGraph里有现成的摘要节点可以接，AgentExecutor里则需要自己写逻辑。5.5 常见问题速查表症状可能原因推荐解法Agent反复调用同一工具工具返回信息不足，或Prompt缺少循环中断指令增加max_iterations上限；在Prompt中指示观察不变时换策略工具调用报参数错误类型注解缺失或描述不具体补全类型注解；在描述中给出参数格式示例选错工具工具描述模糊、工具数量太多重写描述明确适用场景；精简工具数量上下文Token爆炸循环轮次多，工具返回内容过大工具返回前做摘要/截断；定期压缩历史费用过高循环无上限、模型选错模型档位设置max_iterations；小任务用小模型，大任务才用大模型结果格式不可控模型自由发挥输出格式用OutputParser强制结构化输出6. 把Agent推向生产前，必须想清楚的几件事6.1 成本与速度的平衡Agent虽然强大，但它比一次普通的API调用贵得多。我的实测经验是，一个中等复杂的任务，通常需要3到6轮循环，每轮都要把累计的上下发送给模型，Token消耗可能是直接问答的5到10倍。如果你是做Demo，用gpt-4o-mini这类轻量模型就够了，便宜、速度快。但如果你遇到需要强推理能力的任务，比如金融分析、代码生成，轻量模型容易在复杂推理环节掉链子。此时可以考虑混合策略：简单轮次用轻量模型，关键决策轮次切换到大模型。LangGraph里每个节点可以指定不同的模型，实现起来并不复杂。6.2 人工审核的兜底机制Agent自主程度越高，越需要人工审核的兜底。尤其是在涉及数据库写入、文件删除、发送邮件等“有副作用”的操作时，我强烈建议加入“人工确认”环节。LangGraph中实现起来很直接：在工具执行节点前插入一个判断，如果工具属于高风险的写操作，就暂停执行，把待执行内容和参数推给人工确认，确认通过后再继续。我在项目里就用过这个模式，效果非常好。模型负责规划，人能保持在关键节点上审核，两者配合比完全放手要靠谱得多。6.3 工具权限的粒度控制别把所有工具都无差别暴露给Agent。比如你的系统里既有只读查询工具，又有写库工具，模型如果有权限直接调用写库工具，误操作的风险很大。建议按任务场景工具分组，不同场景的Agent挂载不同的工具列表。另外，工具的描述本质上是在告诉模型“你有哪些能力”，能力越大，责任越大。如果某个工具只允许特定场景使用，务必在描述里写清楚限制条件。模型虽然不会像人一样“手滑”，但它对描述的理解是字面层面的，限制条件写清楚，它才会避开。最后分享两个小经验一个是我在反复踩坑之后总结的：无论你用AgentExecutor还是LangGraph，先把verbose打开跑一遍再关掉。很多你觉得“不可思议”的错误，只要看见中间过程，立刻就明白了。另一个是关于工具描述的——如果你只能优化一个环节，优化它，而不是优化模型。模型选不选得对工具、用不用得好参数，大部分因素都落在工具定义的质量上。这是我调了很久Agent之后最有体感的一条心得。希望这篇内容能帮你少走些弯路。