LangChain ReAct Agent 实战Tool 描述才是工具调用的 “灵魂”最近在折腾 LangChain 的 ReAct 智能体Agent时踩了个不少新手都会踩的坑明明代码逻辑看着没问题工具却要么不调用、要么乱调用折腾了半天才发现问题根源竟在Tool 的描述信息上今天就结合实际代码案例和大家聊聊 ReAct Agent 中 Tool 描述的核心作用教大家怎么写好描述让 Agent 精准 “匹配” 工具、高效执行任务。一、先搭基础ReAct Agent 的核心逻辑拆解首先简单回顾下 ReAct Agent 的核心 —— 它遵循 “思考Thought— 行动Action— 观察Observation” 的循环逻辑能根据用户问题自主判断是否调用工具、调用哪个工具。我这次的测试代码核心逻辑很清晰分 6 步走初始化大模型这里用了本地部署的 qwen3.5-27b-awq保证推理效率定义工具函数比如本次的华为商城搜索工具封装 Tool 对象关键包含工具名称、函数、核心描述编写 ReAct 提示词模板定义 Agent 的思考、行动格式创建 ReAct Agent 并绑定工具、提示词执行 Agent测试工具调用效果。其中最关键的一步就是Tool 对象的封装—— 尤其是description描述字段这是 Agent 识别工具、判断是否调用的核心依据。二、踩坑实录Tool 描述不精准Agent 就 “失灵”先给大家看本次测试的两个典型场景直观感受 Tool 描述的重要性场景 1需求匹配工具Agent 正常调用当我输入问题 **“华为商城最新的手机有哪些”** 时Agent 的执行逻辑很顺畅思考用户问的是华为商城手机信息需要调用华为商城搜索工具行动调用huawei_mall_search工具输入关键词 “手机”观察工具返回华为 Mate 60 系列、P60 系列等最新手机信息最终输出整理后的搜索结果完美回答问题。场景 2需求无关工具Agent “瞎调用”当我输入问题 **“你可以告诉我各个星座的时间么”** 时问题出现了 —— 明明需求和华为商城毫无关系Agent 却依然尝试调用huawei_mall_search工具输入 “星座时间” 作为搜索关键词最终返回 “请在华为商城官网查看详细信息” 的无效结果完全没回答星座问题。一开始我以为是模型逻辑出问题反复检查大模型配置、代码逻辑都没发现问题。直到逐行核对 Tool 的封装代码才意识到Tool 的描述信息太模糊了本次测试中 Tool 的初始描述是查询华为商城相关信息包括产品、活动、政策等—— 这个描述只说了 “能做什么”却没说 “不能做什么”也没限定 “适用范围”。Agent 在思考时会模糊判断 “星座问题是否能通过华为商城搜索间接解答”最终导致错误调用。三、核心真相Tool 描述是 Agent 的 “工具使用说明书”为什么 Tool 描述这么关键我们可以把 Agent 比作一个 “新手助理”工具是 “各种技能道具”—— 而 Tool 描述就是给新手助理看的道具使用说明书。Agent 对工具的认知完全依赖描述信息它不会主动去看工具函数内部的逻辑也不会凭空知道这个工具能处理哪些问题、不能处理哪些问题。ReAct Agent 的思考逻辑是接收用户问题后遍历所有 Tool 的描述对比问题与描述的匹配度 —— 如果描述精准匹配就调用对应 Tool如果多个 Tool 都匹配再根据优先级和问题复杂度选择如果都不匹配就直接用大模型自身的知识回答。简单说Tool 描述写得越精准Agent 的匹配判断就越准确描述模糊Agent 就会 “乱选工具”“漏用工具”。四、实战优化写好 Tool 描述的 3 个核心原则结合本次踩坑经验我总结了写 Tool 描述的 3 个关键原则按这个来写能大幅提升 Agent 工具调用的准确率原则 1限定范围明确 “能做什么”描述要精准说明工具的核心功能避免模糊表述让 Agent 一眼知道工具的核心能力。❌ 错误示例本次初始描述查询华为商城相关信息包括产品、活动、政策等范围太广无边界✅ 优化示例专门查询华为商城的手机、笔记本、智能手表等硬件产品信息以及Mate 60系列等新品动态仅支持华为商城相关产品查询不支持查询星座、天气等非商城类信息原则 2明确禁区说明 “不能做什么”这是解决 “乱调用” 的核心一定要在描述中限定工具的适用边界明确告诉 Agent 哪些问题不该用这个工具。比如本次的华为商城搜索工具除了说明能查产品还要明确不支持查询星座、历史知识、天气等非华为商城相关内容。原则 3简洁具体避免冗余描述不用太长但要关键信息突出让 Agent 能快速抓取核心判断依据。避免写 “这个工具是用 Python 写的”“调用需要 API 密钥” 等无关信息 ——Agent 只需要知道 “工具能解决什么问题”不需要知道工具的实现细节。五、优化后代码效果精准匹配零误调用按照上面的原则优化 Tool 描述后重新测试两个场景效果完全不同场景 1需求匹配工具输入 “华为商城最新的手机有哪些”Agent 依然能精准调用工具返回完整的手机产品信息逻辑和之前一致但判断过程更清晰。场景 2需求无关工具输入 “你可以告诉我各个星座的时间么”Agent 的思考逻辑变成思考用户问的是星座时间没有任何 Tool 的描述匹配这个需求直接用大模型知识回答最终输出直接给出十二星座的具体时间范围回答准确完全不调用任何工具。这才是 ReAct Agent 该有的效果Tool 描述的优化直接解决了 “不匹配也调用” 的问题让 Agent 的决策更精准。六、总结Tool 描述是 Agent 调用的 “核心开关”通过这次实战我深刻体会到在 LangChain ReAct Agent 的开发中代码逻辑是骨架Tool 描述是灵魂。很多时候不是 Agent 不会调用工具而是我们没给 Agent 足够的 “判断依据”。给大家总结 3 个落地技巧后续开发直接套用写 Tool 描述时先明确 “核心功能”再限定 “适用范围”最后标注 “禁止场景”多工具场景下给每个 Tool 写差异化描述避免描述重叠导致 Agent 混淆测试时重点观察 Agent 的 “Thought” 思考过程 —— 如果思考中提到了工具名称说明描述匹配没提到则说明描述没被识别及时优化。代码实现123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687fromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimportToolfromlangchain.agentsimportcreate_react_agent# 改用 ReAct 智能体fromlangchain.agentsimportAgentExecutorfromlangchain_core.promptsimportPromptTemplate# ReAct 用 PromptTemplate 而非 ChatPromptTemplate# 1. 初始化 LLM保持不变DEEPSEEK_API_KEY123# 替换为实际的 API KeyllmChatOpenAI(api_keyDEEPSEEK_API_KEY,base_urlhttp://192.168.0.100:8085/v1,modelqwen3.5-27b-awq,temperature0.3,max_tokens1024,)# 2. 工具函数defhuawei_mall_search(query:str)-str:华为商城搜索工具print(f[DEBUG] 工具被调用搜索关键词{query})search_results{众测活动:华为商城众测活动是让用户体验新品并反馈意见的活动。目前有Mate 60系列众测参与可赢取礼品。,手机:华为商城最新手机Mate 60系列、P60系列、nova系列等。,笔记本:华为MateBook X Pro、MateBook D系列笔记本电脑。,手表:华为Watch 4、Watch GT系列智能手表。,默认:请在华为商城官网查看详细信息或联系客服。}forkeywordinsearch_results:ifkeywordinquery:returnf华为商城搜索结果{search_results[keyword]}returnsearch_results[默认]# 3. 创建工具huawei_toolTool(namehuawei_mall_search,description查询华为商城相关信息包括产品、活动、政策等,funchuawei_mall_search,)tools[huawei_tool]# 4. 定义 ReAct 提示词模板react_promptPromptTemplate.from_template(Answer the following questions as best you can. You have access to the following tools:{tools}Use the following format:Question: the input question you must answerThought: you should always think about what to doAction: the action to take, should be one of [{tool_names}]Action Input: the input to the actionObservation: the result of the action... (this Thought/Action/Action Input/Observation can repeat N times)Thought: I now know the final answerFinal Answer: the final answer to the original input questionBegin!Question: {input}Thought: {agent_scratchpad})# 5. 创建 ReAct 智能体agentcreate_react_agent(llmllm, toolstools, promptreact_prompt)# 6. 创建执行器agent_executorAgentExecutor(agentagent,toolstools,verboseTrue,max_iterations3,handle_parsing_errorsTrue,return_intermediate_stepsTrue)# 7. 测试保持不变print(\n*60)print(测试 Agent 工具调用)print(*60)#会调用注册的方法#result agent_executor.invoke({input: 华为商城最新的手机有哪些})#不会调用resultagent_executor.invoke({input:你可以告诉我各个星座的时间么})print(f\n最终输出: {result[output]})print(f\n中间步骤: {result[intermediate_steps]})调用工具输出测试 Agent 工具调用 Entering new AgentExecutor chain...t./thinkThought: 用户询问华为商城最新的手机有哪些我需要使用华为商城搜索工具来查询相关信息。Action: huawei_mall_searchAction Input: 华为商城最新手机 2024[DEBUG] 工具被调用搜索关键词华为商城最新手机 2024华为商城搜索结果华为商城最新手机Mate 60系列、P60系列、nova系列等。息。/thinkThought: 根据搜索结果华为商城最新手机包括Mate 60系列、P60系列和nova系列。需要确认这些是否为当前最新型号并补充具体信息。Final Answer: 华为商城最新手机主要包括以下系列1. **Mate 60系列**如Mate 60、Mate 60 Pro等2. **P60系列**如P60、P60 Pro、P60 Art等3. **nova系列**如nova 12系列等建议访问华为商城官网或线下门店获取具体型号、配置及最新活动信息。 Finished chain.最终输出: 华为商城最新手机主要包括以下系列1. **Mate 60系列**如Mate 60、Mate 60 Pro等2. **P60系列**如P60、P60 Pro、P60 Art等3. **nova系列**如nova 12系列等建议访问华为商城官网或线下门店获取具体型号、配置及最新活动信息。中间步骤: [(AgentAction(toolhuawei_mall_search, tool_input华为商城最新手机 2024\n, logt.\n/think\n\nThought: 用户询问华为商城最新的手机有哪些我需要使用华为商城搜索工具来查询相关信息。\n\nAction: huawei_mall_search\nAction Input: 华为商城最新手机 2024\n), 华为商城搜索结果华为商城最新手机Mate 60系列、P60系列、nova系列等。)]不调用工具输出测试 Agent 工具调用
AI开发-python-langchain框架（3-16-angent的创建及注册tool）
LangChain ReAct Agent 实战Tool 描述才是工具调用的 “灵魂”最近在折腾 LangChain 的 ReAct 智能体Agent时踩了个不少新手都会踩的坑明明代码逻辑看着没问题工具却要么不调用、要么乱调用折腾了半天才发现问题根源竟在Tool 的描述信息上今天就结合实际代码案例和大家聊聊 ReAct Agent 中 Tool 描述的核心作用教大家怎么写好描述让 Agent 精准 “匹配” 工具、高效执行任务。一、先搭基础ReAct Agent 的核心逻辑拆解首先简单回顾下 ReAct Agent 的核心 —— 它遵循 “思考Thought— 行动Action— 观察Observation” 的循环逻辑能根据用户问题自主判断是否调用工具、调用哪个工具。我这次的测试代码核心逻辑很清晰分 6 步走初始化大模型这里用了本地部署的 qwen3.5-27b-awq保证推理效率定义工具函数比如本次的华为商城搜索工具封装 Tool 对象关键包含工具名称、函数、核心描述编写 ReAct 提示词模板定义 Agent 的思考、行动格式创建 ReAct Agent 并绑定工具、提示词执行 Agent测试工具调用效果。其中最关键的一步就是Tool 对象的封装—— 尤其是description描述字段这是 Agent 识别工具、判断是否调用的核心依据。二、踩坑实录Tool 描述不精准Agent 就 “失灵”先给大家看本次测试的两个典型场景直观感受 Tool 描述的重要性场景 1需求匹配工具Agent 正常调用当我输入问题 **“华为商城最新的手机有哪些”** 时Agent 的执行逻辑很顺畅思考用户问的是华为商城手机信息需要调用华为商城搜索工具行动调用huawei_mall_search工具输入关键词 “手机”观察工具返回华为 Mate 60 系列、P60 系列等最新手机信息最终输出整理后的搜索结果完美回答问题。场景 2需求无关工具Agent “瞎调用”当我输入问题 **“你可以告诉我各个星座的时间么”** 时问题出现了 —— 明明需求和华为商城毫无关系Agent 却依然尝试调用huawei_mall_search工具输入 “星座时间” 作为搜索关键词最终返回 “请在华为商城官网查看详细信息” 的无效结果完全没回答星座问题。一开始我以为是模型逻辑出问题反复检查大模型配置、代码逻辑都没发现问题。直到逐行核对 Tool 的封装代码才意识到Tool 的描述信息太模糊了本次测试中 Tool 的初始描述是查询华为商城相关信息包括产品、活动、政策等—— 这个描述只说了 “能做什么”却没说 “不能做什么”也没限定 “适用范围”。Agent 在思考时会模糊判断 “星座问题是否能通过华为商城搜索间接解答”最终导致错误调用。三、核心真相Tool 描述是 Agent 的 “工具使用说明书”为什么 Tool 描述这么关键我们可以把 Agent 比作一个 “新手助理”工具是 “各种技能道具”—— 而 Tool 描述就是给新手助理看的道具使用说明书。Agent 对工具的认知完全依赖描述信息它不会主动去看工具函数内部的逻辑也不会凭空知道这个工具能处理哪些问题、不能处理哪些问题。ReAct Agent 的思考逻辑是接收用户问题后遍历所有 Tool 的描述对比问题与描述的匹配度 —— 如果描述精准匹配就调用对应 Tool如果多个 Tool 都匹配再根据优先级和问题复杂度选择如果都不匹配就直接用大模型自身的知识回答。简单说Tool 描述写得越精准Agent 的匹配判断就越准确描述模糊Agent 就会 “乱选工具”“漏用工具”。四、实战优化写好 Tool 描述的 3 个核心原则结合本次踩坑经验我总结了写 Tool 描述的 3 个关键原则按这个来写能大幅提升 Agent 工具调用的准确率原则 1限定范围明确 “能做什么”描述要精准说明工具的核心功能避免模糊表述让 Agent 一眼知道工具的核心能力。❌ 错误示例本次初始描述查询华为商城相关信息包括产品、活动、政策等范围太广无边界✅ 优化示例专门查询华为商城的手机、笔记本、智能手表等硬件产品信息以及Mate 60系列等新品动态仅支持华为商城相关产品查询不支持查询星座、天气等非商城类信息原则 2明确禁区说明 “不能做什么”这是解决 “乱调用” 的核心一定要在描述中限定工具的适用边界明确告诉 Agent 哪些问题不该用这个工具。比如本次的华为商城搜索工具除了说明能查产品还要明确不支持查询星座、历史知识、天气等非华为商城相关内容。原则 3简洁具体避免冗余描述不用太长但要关键信息突出让 Agent 能快速抓取核心判断依据。避免写 “这个工具是用 Python 写的”“调用需要 API 密钥” 等无关信息 ——Agent 只需要知道 “工具能解决什么问题”不需要知道工具的实现细节。五、优化后代码效果精准匹配零误调用按照上面的原则优化 Tool 描述后重新测试两个场景效果完全不同场景 1需求匹配工具输入 “华为商城最新的手机有哪些”Agent 依然能精准调用工具返回完整的手机产品信息逻辑和之前一致但判断过程更清晰。场景 2需求无关工具输入 “你可以告诉我各个星座的时间么”Agent 的思考逻辑变成思考用户问的是星座时间没有任何 Tool 的描述匹配这个需求直接用大模型知识回答最终输出直接给出十二星座的具体时间范围回答准确完全不调用任何工具。这才是 ReAct Agent 该有的效果Tool 描述的优化直接解决了 “不匹配也调用” 的问题让 Agent 的决策更精准。六、总结Tool 描述是 Agent 调用的 “核心开关”通过这次实战我深刻体会到在 LangChain ReAct Agent 的开发中代码逻辑是骨架Tool 描述是灵魂。很多时候不是 Agent 不会调用工具而是我们没给 Agent 足够的 “判断依据”。给大家总结 3 个落地技巧后续开发直接套用写 Tool 描述时先明确 “核心功能”再限定 “适用范围”最后标注 “禁止场景”多工具场景下给每个 Tool 写差异化描述避免描述重叠导致 Agent 混淆测试时重点观察 Agent 的 “Thought” 思考过程 —— 如果思考中提到了工具名称说明描述匹配没提到则说明描述没被识别及时优化。代码实现123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687fromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimportToolfromlangchain.agentsimportcreate_react_agent# 改用 ReAct 智能体fromlangchain.agentsimportAgentExecutorfromlangchain_core.promptsimportPromptTemplate# ReAct 用 PromptTemplate 而非 ChatPromptTemplate# 1. 初始化 LLM保持不变DEEPSEEK_API_KEY123# 替换为实际的 API KeyllmChatOpenAI(api_keyDEEPSEEK_API_KEY,base_urlhttp://192.168.0.100:8085/v1,modelqwen3.5-27b-awq,temperature0.3,max_tokens1024,)# 2. 工具函数defhuawei_mall_search(query:str)-str:华为商城搜索工具print(f[DEBUG] 工具被调用搜索关键词{query})search_results{众测活动:华为商城众测活动是让用户体验新品并反馈意见的活动。目前有Mate 60系列众测参与可赢取礼品。,手机:华为商城最新手机Mate 60系列、P60系列、nova系列等。,笔记本:华为MateBook X Pro、MateBook D系列笔记本电脑。,手表:华为Watch 4、Watch GT系列智能手表。,默认:请在华为商城官网查看详细信息或联系客服。}forkeywordinsearch_results:ifkeywordinquery:returnf华为商城搜索结果{search_results[keyword]}returnsearch_results[默认]# 3. 创建工具huawei_toolTool(namehuawei_mall_search,description查询华为商城相关信息包括产品、活动、政策等,funchuawei_mall_search,)tools[huawei_tool]# 4. 定义 ReAct 提示词模板react_promptPromptTemplate.from_template(Answer the following questions as best you can. You have access to the following tools:{tools}Use the following format:Question: the input question you must answerThought: you should always think about what to doAction: the action to take, should be one of [{tool_names}]Action Input: the input to the actionObservation: the result of the action... (this Thought/Action/Action Input/Observation can repeat N times)Thought: I now know the final answerFinal Answer: the final answer to the original input questionBegin!Question: {input}Thought: {agent_scratchpad})# 5. 创建 ReAct 智能体agentcreate_react_agent(llmllm, toolstools, promptreact_prompt)# 6. 创建执行器agent_executorAgentExecutor(agentagent,toolstools,verboseTrue,max_iterations3,handle_parsing_errorsTrue,return_intermediate_stepsTrue)# 7. 测试保持不变print(\n*60)print(测试 Agent 工具调用)print(*60)#会调用注册的方法#result agent_executor.invoke({input: 华为商城最新的手机有哪些})#不会调用resultagent_executor.invoke({input:你可以告诉我各个星座的时间么})print(f\n最终输出: {result[output]})print(f\n中间步骤: {result[intermediate_steps]})调用工具输出测试 Agent 工具调用 Entering new AgentExecutor chain...t./thinkThought: 用户询问华为商城最新的手机有哪些我需要使用华为商城搜索工具来查询相关信息。Action: huawei_mall_searchAction Input: 华为商城最新手机 2024[DEBUG] 工具被调用搜索关键词华为商城最新手机 2024华为商城搜索结果华为商城最新手机Mate 60系列、P60系列、nova系列等。息。/thinkThought: 根据搜索结果华为商城最新手机包括Mate 60系列、P60系列和nova系列。需要确认这些是否为当前最新型号并补充具体信息。Final Answer: 华为商城最新手机主要包括以下系列1. **Mate 60系列**如Mate 60、Mate 60 Pro等2. **P60系列**如P60、P60 Pro、P60 Art等3. **nova系列**如nova 12系列等建议访问华为商城官网或线下门店获取具体型号、配置及最新活动信息。 Finished chain.最终输出: 华为商城最新手机主要包括以下系列1. **Mate 60系列**如Mate 60、Mate 60 Pro等2. **P60系列**如P60、P60 Pro、P60 Art等3. **nova系列**如nova 12系列等建议访问华为商城官网或线下门店获取具体型号、配置及最新活动信息。中间步骤: [(AgentAction(toolhuawei_mall_search, tool_input华为商城最新手机 2024\n, logt.\n/think\n\nThought: 用户询问华为商城最新的手机有哪些我需要使用华为商城搜索工具来查询相关信息。\n\nAction: huawei_mall_search\nAction Input: 华为商城最新手机 2024\n), 华为商城搜索结果华为商城最新手机Mate 60系列、P60系列、nova系列等。)]不调用工具输出测试 Agent 工具调用
