02-Agent 智能体开发实战指南（二）：工具调用系统

Agent 智能体开发实战指南二工具调用系统深度解析系列导读这是《Agent 智能体开发实战指南》系列的第二篇将深入讲解 Agent 的工具调用系统包括tool 装饰器原理、工具设计原则、多工具协作等核心内容。一、工具Agent 的手脚1.1 为什么需要工具如果把 LLM 比作大脑那么工具就是手脚——没有工具再聪明的大脑也无法影响现实世界。工具的本质将外部能力封装成 LLM 可以理解和调用的接口。┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ LLM 大脑 │ ──→ │ 工具接口 │ ──→ │ 外部系统 │ │ (决策者) │ │ (翻译层) │ │ (执行者) │ └─────────────┘ └─────────────┘ └─────────────┘1.2 工具的三大要素要素作用示例名称LLM 识别工具的标识get_weather描述LLM 理解工具用途“查询指定城市的天气”参数LLM 传递必要信息city: str二、tool 装饰器详解2.1 基础用法fromlangchain_core.toolsimporttooltool(description获取股价传入股票名称返回字符串信息)defget_price(name:str)-str:returnf股票{name}的价格是 40 元装饰器做了什么提取函数名get_price作为工具名解析参数签名name: str确定输入要求解析返回类型- str确定输出格式绑定description供 LLM 理解用途将普通函数转换为 LangChain 的Tool对象2.2 完整 Tool 对象结构# tool 装饰后实际生成的对象结构Tool(nameget_price,description获取股价传入股票名称返回字符串信息,args_schema{name:{type:string,description:股票名称}},funcfunction get_price at 0x...)2.3 多参数工具示例tool(description查询两个城市之间的天气对比)defcompare_weather(city1:str,city2:str)-str:获取两个城市的天气并进行对比# LLM 会自动传入两个参数weather1get_weather(city1)weather2get_weather(city2)returnf{city1}:{weather1}|{city2}:{weather2}三、工具描述编写指南3.1 描述的重要性description 是 LLM 选择工具的唯一依据。糟糕的描述会导致LLM 不知道何时调用该工具LLM 传入错误的参数LLM 完全忽略该工具3.2 优秀描述的三要素# 描述太简略tool(description获取数据)# 描述不够清晰tool(description获取股票价格)# 优秀的描述tool(description获取股票实时价格传入股票名称如华胜天成、贵州茅台返回包含股价、涨跌幅的字符串信息)优秀描述包含功能说明这个工具做什么参数说明需要传入什么格式是什么返回说明会返回什么格式是什么示例值给出典型参数示例3.3 描述模板tool(description[功能]传入 [参数名 格式 示例]返回 [返回内容 格式])实战示例# 天气查询tool(description查询指定城市的天气情况传入城市名称如深圳、北京返回包含气温、湿度、风向的详细天气信息)# 用户信息查询tool(description获取当前用户的 ID无需参数返回纯字符串格式的用户 ID)# 数据检索tool(description从知识库中检索相关内容传入搜索关键词返回最匹配的 3-5 条参考资料)四、多工具协作场景4.1 场景股票查询 介绍fromlangchain.agentsimportcreate_agentfromlangchain_community.chat_models.tongyiimportChatTongyifromlangchain_core.toolsimporttooltool(description获取股票价格传入股票名称返回当前股价字符串)defget_price(name:str)-str:returnf股票{name}的价格是 40 元tool(description获取股票公司信息传入股票名称返回公司业务介绍字符串)defget_info(name:str)-str:returnf股票{name}是一家 A 股上市公司专注于计算机领域。agentcreate_agent(modelChatTongyi(modelqwen3-max),tools[get_price,get_info],system_prompt你是一个智能助手可以回答股票相关问题请告知我思考过程让我知道你为什么调用某个工具)forchunkinagent.stream({messages:[{role:user,content:华胜天成股价多少并介绍一下}]},stream_modevalues):latest_messagechunk[messages][-1]iflatest_message.content:print(latest_message.content)try:iflatest_message.tool_calls:print(f工具调用{[tc[name]fortcinlatest_message.tool_calls]})exceptAttributeError:pass4.2 执行流程分析用户华胜天成股价多少并介绍一下 ↓ Agent 思考用户问了两个问题——股价 公司介绍 ↓ 行动 1调用 get_price(华胜天成) ↓ 观察 1获得股价信息 ↓ 行动 2调用 get_info(华胜天成) ↓ 观察 2获得公司介绍 ↓ 生成答案整合两条信息回复用户4.3 工具调用顺序LLM 会自动决定工具调用顺序通常遵循依赖关系先获取必要数据再进行处理逻辑顺序按人类思考的自然顺序效率优先能并行则并行LangChain 支持并行调用五、工具设计最佳实践5.1 单一职责原则❌ 错误示例一个工具做太多事tool(description处理用户所有请求)defhandle_everything(query:str)-str:# 又查天气又查股价又写报告...pass✅ 正确示例每个工具专注一件事tool(description查询天气)defget_weather(city:str)-str:passtool(description查询股价)defget_price(stock:str)-str:passtool(description生成报告)defgenerate_report(user_id:str)-str:pass5.2 错误处理工具内部应该处理异常返回友好提示tool(description查询天气传入城市名称)defget_weather(city:str)-str:try:# 调用天气 APIresponseweather_api.get(city)returnformat_weather(response)exceptCityNotFoundError:returnf未找到城市{city}的天气信息请检查城市名称是否正确exceptAPIErrorase:returnf天气服务暂时不可用请稍后重试错误码{e.code}为什么避免 Agent 因工具异常而崩溃让 LLM 知道发生了什么可以调整策略提供更好的用户体验5.3 返回值格式原则返回 LLM 容易理解的格式# ❌ 返回复杂对象defget_weather(city:str)-dict:return{temp:26,humidity:50,wind:南风 1 级}# ✅ 返回格式化字符串defget_weather(city:str)-str:returnf城市{city}天气为晴天气温 26 摄氏度空气湿度 50%南风 1 级原因LLM 处理自然语言最擅长结构化数据反而需要额外解析。5.4 参数设计原则参数越少越好类型越简单越好# 参数太多tool(description查询天气)defget_weather(city:str,date:str,unit:str,include_hourly:bool)-str:pass# 简化参数tool(description查询指定城市的天气)defget_weather(city:str)-str:# 内部使用默认值今天、摄氏度、不含小时预报pass六、实战完整的工具集设计6.1 智扫通客服 Agent 工具集fromlangchain_core.toolsimporttoolfromrag.rag_serviceimportRagSummarizeService ragRagSummarizeService()# 1. 知识库检索工具tool(description从向量存储中检索参考资料传入搜索关键词返回最相关的知识内容)defrag_summarize(query:str)-str:returnrag.rag_summarize(query)# 2. 天气查询工具tool(description获取指定城市的天气传入城市名称返回包含气温、湿度、风向的字符串信息)defget_weather(city:str)-str:returnf城市{city}天气为晴天气温 26 摄氏度空气湿度 50%南风 1 级AQI21# 3. 用户位置工具tool(description获取用户所在城市的名称无需参数返回纯字符串格式的城市名)defget_user_location()-str:return深圳# 实际应从用户 profile 获取# 4. 用户 ID 工具tool(description获取当前用户的 ID无需参数返回纯字符串格式的用户 ID)defget_user_id()-str:return1001# 实际应从 session 获取# 5. 时间工具tool(description获取当前月份无需参数返回YYYY-MM格式的字符串)defget_current_month()-str:return2025-03# 6. 外部数据工具tool(description从外部系统获取指定用户在指定月份的使用记录传入 user_id 和 month返回使用数据字符串)deffetch_external_data(user_id:str,month:str)-str:# 从数据库或 API 获取returnexternal_data.get(user_id,{}).get(month,)# 7. 上下文标记工具tool(description无入参无返回值调用后标记当前为报告生成场景触发提示词切换)deffill_context_for_report():returnfill_context_for_report 已调用6.2 工具分类管理agent/tools/ ├── agent_tools.py # 核心业务工具 ├── common_tools.py # 通用工具时间、位置等 └── system_tools.py # 系统工具日志、监控等七、调试技巧7.1 打印工具调用日志forchunkinagent.stream(input_dict,stream_modevalues):latest_messagechunk[messages][-1]iflatest_message.content:print(f Agent:{latest_message.content})try:iflatest_message.tool_calls:tool_names[tc[name]fortcinlatest_message.tool_calls]print(f 工具调用{tool_names})exceptAttributeError:pass7.2 常见问题排查问题可能原因解决方案Agent 不调用工具description 不清晰重写工具描述调用错误工具工具名相似区分工具命名参数传错参数类型不明确在 description 中说明工具返回被忽略返回格式混乱统一返回格式八、本章小结核心要点tool 装饰器将 Python 函数转换为 LLM 可调用的 Tool 对象description 至关重要决定 LLM 是否正确选择工具单一职责每个工具只做一件事做好一件事错误处理工具内部处理异常返回友好提示返回值格式优先返回自然语言字符串下章预告下一篇我们将深入ReAct 框架学习ReAct 的思考 - 行动 - 观察循环多步推理策略如何引导 Agent 按正确顺序调用工具ReAct 实战案例解析Agent 智能体开发实战指南一从 LLM 到 Agent 的认知升级Agent 智能体开发实战指南二工具调用系统深度解析本文Agent 智能体开发实战指南三ReAct 框架深度解析Agent 智能体开发实战指南四流式输出与状态管理Agent 智能体开发实战指南五中间件系统与动态提示词Agent 智能体开发实战指南六RAG 与向量存储实战Agent 智能体开发实战指南七项目架构设计与工程化实践Agent 智能体开发实战指南八UI 集成与生产部署本文是《Agent 智能体开发实战指南》系列的第二篇下一篇将深入讲解 ReAct 框架。