1. 从一次翻车说起为什么智能体离不开工具去年冬天我接了个私活帮一家做跨境电商的朋友搭一套自动处理售后邮件的系统。需求听起来不复杂读邮件、判断意图、查订单状态、生成回复。我一开始想得很简单用 LangChain 挂个 LLM写个提示词让它直接输出答案就完事了。结果上线第一天就翻车——客户问“我上周买的那个蓝色杯子到哪了”模型一本正经地编了个物流单号还配了段“预计明天送达”的鬼话。朋友打电话过来的时候我正蹲在便利店吃关东煮那一刻我意识到光有大脑没有手脚的智能体本质上就是个会说话的算命先生。这就是我写这个系列第五篇的起因。前四篇我们聊了 LangChain 的基础链路、提示词模板、记忆机制和检索增强那些东西解决的是“模型怎么想”的问题。但真实业务里用户要的不是“想”是“做”——查数据库、调接口、发邮件、改状态。智能体Agent与工具Tool这套机制就是给 LLM 装上手脚和感官的关键一环。如果你正在做智能体开发或者被“Agent 框架哪个好”“平台搭建的智能体和 Python 手搓的有什么区别”这类问题困扰这篇内容应该能帮你少走点弯路。我会从设计思路讲到代码落地把工具调用的坑一个个刨开给你看。需要说明的是文中涉及的代码示例基于 LangChain 的通用实践具体版本 API 可能有细微差异你照着思路调整即可。2. 智能体与工具的整体设计思路拆解2.1 智能体的本质一个会自己决定下一步的循环很多人第一次接触 Agent 会懵觉得它比 Chain 高级很多。其实剥开看Agent 就是一个带条件判断的 while 循环。普通 Chain 是线性的输入 → 提示词 → 模型 → 输出一条道走到黑。Agent 不一样它拿到问题后会反复问自己三个问题我现在知道什么我还缺什么信息我该调用哪个工具去补这个循环在 LangChain 里的实现叫ReAct 模式Reasoning Acting核心逻辑是让模型输出“思考 → 行动 → 观察”的序列。模型先想一步Thought决定调哪个工具Action工具返回结果Observation模型再基于新信息继续想直到它认为可以给出最终答案Final Answer。我打个比方你就懂了。普通 Chain 像是你去餐厅点了个套餐厨房按固定流程做完端上来。Agent 像是你走进一家自助餐厅先看看有什么菜想想自己饿不饿、想吃什么然后去拿拿完尝一口觉得不够辣再回去加点辣椒。这个“看-想-拿-尝-再拿”的过程就是智能体的核心循环。2.2 工具在智能体里扮演什么角色工具Tool在 LangChain 里是一个封装好的函数它有三个关键属性名称name、描述description、执行逻辑func。名称是给模型看的标识符描述是告诉模型“我是干什么的、什么时候该用我”执行逻辑是真正干活的代码。这里有个特别容易被忽视的点工具的描述写得怎么样直接决定智能体的智商上限。我见过太多人把描述写成“查询订单”然后抱怨模型不会用。你想想模型面对十几个工具每个描述都含糊其辞它怎么知道该选哪个好的描述应该像给新员工写操作手册说清楚输入格式、输出内容、适用场景。比如查订单的工具描述应该写成“根据订单号查询订单的物流状态和预计送达时间。输入应该是纯数字的订单号例如 20240115001。当用户询问包裹位置、配送进度时使用此工具。”这样模型一看就明白什么时候该掏它出来。2.3 为什么不用一个万能函数搞定所有事有人会问我写一个大函数里面用 if-else 判断用户意图然后分别处理不也行吗行但有几个问题。第一意图判断的活儿交给模型比交给正则表达式靠谱。用户说“我那个杯子咋还没到”你用关键词匹配“杯子”“到”很容易误判。模型能理解语义知道这是在问物流。第二工具是独立可复用的单元。你今天做售后系统需要查订单明天做库存系统也需要查订单同一个工具直接挂上去就行。写成一个大函数耦合太深改一处动全身。第三工具调用过程可观测。LangChain 会把每次工具调用的输入输出记录下来出问题的时候你能清楚看到模型调了哪个工具、传了什么参数、返回了什么。这对调试和审计至关重要尤其是涉及智能体行为审计的场景。2.4 平台搭建的智能体 vs Python 手搓的智能体这个问题被问得特别多我结合自己的使用体验说下区别。平台搭建比如 Coze、Dify 这类的优势是快。拖拖拽拽配几个插件半小时能跑起来一个能用的智能体。适合快速验证想法、做 Demo、非技术同学上手。但它的局限也很明显工具生态受平台限制你想接个内部系统的私有接口可能得等平台支持或者走复杂的自定义流程调试深度有限出问题只能看平台给的日志复杂逻辑编排能力弱多智能体协作、条件分支多了之后会很别扭。Python 手搓LangChain、CrewAI 这类框架的优势是自由。任何 Python 函数都能变成工具任何逻辑都能编排调试信息全在你自己手里。代价是学习曲线陡得懂代码得自己处理错误重试、并发、状态管理这些脏活累活。我的建议是验证阶段用平台生产阶段看情况。如果业务逻辑简单、工具都是通用的平台够用。如果涉及私有系统集成、复杂决策链路、对可观测性要求高老老实实写代码。两者不是对立的我现在的做法是平台做原型跑通了再用 LangChain 重写核心逻辑。3. 核心细节解析与实操要点3.1 工具定义的三个关键参数在 LangChain 里定义一个工具最基础的方式是用tool装饰器。我拿一个查天气的工具举例from langchain.tools import tool tool def get_weather(city: str) - str: 查询指定城市的当前天气情况。 输入应该是城市名称例如北京或上海。 当用户询问天气、气温、是否下雨等问题时使用此工具。 # 实际项目中这里调用天气 API weather_data { 北京: 晴气温 5-12 度西北风 3 级, 上海: 多云气温 8-15 度东南风 2 级 } return weather_data.get(city, f暂时查不到{city}的天气数据)这段代码里有三个要点。第一类型注解必须写。city: str告诉模型这个参数是字符串模型生成调用时会按这个类型来。如果你写city: int模型可能会传个数字进来然后你的 API 调用就炸了。第二docstring 就是给模型看的说明书。LangChain 会自动把 docstring 作为工具描述传给模型。所以别偷懒写“查询天气”四个字要把输入格式、使用场景都写清楚。第三返回值最好是字符串。虽然理论上可以返回任何类型但字符串最稳妥模型处理起来也最自然。如果返回的是复杂结构建议先转成 JSON 字符串或者格式化的文本。3.2 工具描述怎么写才能让模型选对我踩过的坑里工具描述写得太烂排前三。分享几个我总结的写法要点。说清楚“什么时候用”比“是什么”更重要。模型不缺知识它缺的是判断依据。你写“这是一个计算器工具”模型不知道啥时候该用。你写“当用户需要进行数学计算、单位换算、百分比计算时使用此工具”模型就明白了。给出输入示例。尤其是参数格式有要求的时候。比如查订单的工具你写“输入订单号”模型可能传“我的订单号是 12345”。你写“输入纯数字订单号例如 20240115001”模型就知道该提取数字部分。说明输出内容。模型需要知道调用完能得到什么才能决定下一步。你写“返回订单状态”模型不知道有没有物流信息。你写“返回订单的当前状态、物流单号、预计送达日期”模型就知道这些信息可以拿来回答用户。避免描述重叠。如果你有两个工具都能查信息描述里一定要划清界限。比如“查订单物流”和“查订单退款进度”要明确说前者用于配送查询后者用于退款状态查询。否则模型会在两个之间反复横跳。3.3 工具调用的参数传递机制模型决定调用工具后它需要生成符合工具签名的参数。这个过程叫Function Calling或者Tool Calling底层是模型经过专门训练的能力。以 OpenAI 的模型为例你在调用时传入 tools 参数模型会返回一个结构化的 tool_calls 对象里面包含工具名和参数 JSON。LangChain 帮你把这层封装好了你只需要关注工具本身的逻辑。但这里有个隐藏的坑模型生成的参数可能不符合你的预期。比如你定义city: str模型可能传{city: 北京市朝阳区}而你的 API 只认“北京”。解决办法有两个一是在工具函数里做参数清洗二是把描述写得更严格明确说“只传城市名不要带区县”。我一般两个都做。工具函数里加一层校验和清洗描述里也写清楚格式要求。双保险省得线上出问题。3.4 工具执行结果的格式化处理工具返回的结果会作为 Observation 塞回给模型。这个结果的格式直接影响模型的理解。返回纯文本最安全。JSON 虽然结构化但模型解析 JSON 有时候会出错尤其是嵌套深的时候。我一般把关键信息提取出来拼成自然语言。比如查订单返回“订单 20240115001 状态已发货物流单号 SF1234567890预计 1 月 18 日送达”比返回一大坨 JSON 效果好得多。控制返回长度。工具返回的内容会占用上下文窗口。如果你返回一个几百行的列表模型可能被淹没。我一般只返回最相关的几条或者做个摘要。比如搜索工具返回前 5 条结果而不是全部。错误信息也要友好。工具执行失败时别直接抛异常堆栈给模型。返回“查询失败订单号格式不正确请提供 11 位数字订单号”这样的信息模型能理解并调整策略。直接抛ValueError: invalid literal for int()模型看了也懵。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先把环境搭起来。我假设你已经有了 Python 基础没装过 LangChain 的话跟着走一遍。pip install langchain langchain-openai langchain-community如果你用的是其他模型提供商把langchain-openai换成对应的包。国内的话通义千问、智谱、DeepSeek 都有对应的 LangChain 集成。环境变量里配好 API Keyexport OPENAI_API_KEY你的keyWindows 用户用set或者直接在代码里传。我建议用.env文件加python-dotenv管理别把 key 硬编码在代码里这是基本的安全习惯。4.2 构建第一个带工具的智能体我们从一个最小可运行的例子开始。假设要做一个能查天气和做计算的助手。from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.tools import tool from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder tool def get_weather(city: str) - str: 查询指定城市的当前天气。 输入为城市名称例如北京。 当用户询问天气、气温、是否下雨时使用。 data {北京: 晴5-12度, 上海: 多云8-15度} return data.get(city, f暂无{city}的天气数据) tool def calculate(expression: str) - str: 计算数学表达式。 输入为合法的 Python 数学表达式例如23*4。 当用户需要进行数学计算时使用。 try: result eval(expression, {__builtins__: {}}, {}) return f计算结果{result} except Exception as e: return f计算失败{str(e)} tools [get_weather, calculate] llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的助手可以使用工具来回答问题。), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) result agent_executor.invoke({input: 北京今天天气怎么样另外帮我算一下 25 乘以 4 加 10 等于多少}) print(result[output])跑起来之后你会看到 verbose 输出里模型先调了get_weather拿到结果后又调了calculate最后整合成一段回答。这个“先调一个、再调一个、最后汇总”的过程就是智能体多步推理的直观体现。4.3 工具调用的完整链路拆解上面那段代码背后发生了什么我拆开讲。第一步用户输入进入AgentExecutor。Executor 把输入和系统提示词、工具描述一起打包发给 LLM。第二步LLM 分析输入发现需要两个信息天气和计算结果。它生成一个包含两个 tool_calls 的响应分别指定工具名和参数。第三步Executor 解析 tool_calls依次执行对应的工具函数拿到返回值。第四步Executor 把工具返回值作为 Observation 追加到对话历史再次发给 LLM。第五步LLM 看到所有信息齐了生成最终的自然语言回答。第六步Executor 把最终回答返回给调用方。这个链路里第三步和第四步是循环的。如果模型觉得信息还不够它会继续调工具直到它认为可以回答了。LangChain 默认有最大迭代次数限制一般是 15 次防止模型陷入死循环。4.4 参数计算与选择过程实录我拿一个真实场景演示参数是怎么定的。假设要做一个电商客服智能体需要查订单工具。订单号格式是 11 位数字以年份开头。工具定义tool def query_order(order_id: str) - str: 根据订单号查询订单状态和物流信息。 输入必须是 11 位纯数字订单号例如 20240115001。 当用户询问包裹位置、配送进度、订单状态时使用此工具。 不要传入包含文字的描述只传数字。 if not order_id.isdigit() or len(order_id) ! 11: return 订单号格式错误请提供 11 位数字订单号 # 模拟查询 mock_db { 20240115001: 已发货顺丰 SF1234567890预计 1 月 18 日送达, 20240115002: 待发货预计 1 月 16 日发出 } return mock_db.get(order_id, 未找到该订单请确认订单号是否正确)这里我做了三层防护。第一层在描述里明确说“11 位纯数字”“不要传文字”。第二层在函数入口校验格式不符合直接返回友好错误。第三层在查询逻辑找不到订单也返回可读信息而不是抛异常。实测下来加了这三层之后模型传错参数的概率从大概三成降到了不到半成。剩下的半成主要是用户输入本身就有歧义比如用户说“查一下我上周那个订单”模型没有订单号可传这时候它会转而询问用户要订单号这也是合理行为。4.5 多工具协作的编排技巧当工具数量超过 5 个模型选错的概率会上升。我总结了几个编排技巧。按领域分组。如果工具涉及多个领域考虑拆成多个智能体每个智能体只管自己领域的工具。比如售后智能体只管订单和退款技术智能体只管报错和日志。这样每个智能体的工具集小选择准确率高。设置工具优先级。LangChain 本身不直接支持优先级但你可以通过描述暗示。比如在描述里写“优先使用此工具查询订单状态”模型会倾向于先调它。给工具加“兜底”。写一个通用的搜索工具或者人工转接工具当模型不确定该用哪个的时候可以调它。描述写“当你不确定该用哪个工具或者用户问题超出你的能力范围时使用此工具转接人工”。控制工具数量上限。我的经验是单个智能体的工具数量最好控制在 10 个以内。超过 10 个考虑拆分。这不是硬性规定但实测下来超过这个数模型的选择准确率会明显下降。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最高频的问题。模型收到问题后直接自己编答案压根不调工具。原因通常有三个。描述没写清楚。模型不知道这个工具能解决当前问题。解决办法是把描述写得更具体把用户可能的问题表述都覆盖进去。比如查天气的工具描述里加上“用户问‘今天热不热’‘要不要带伞’‘气温多少’时也使用此工具”。系统提示词没强调。在 system message 里明确说“你有工具可用遇到需要实时信息或计算的问题必须调用工具不要自己编造”。我一般会加一句“如果你不确定答案优先调用工具查询而不是猜测”。模型能力不够。一些小模型或者老模型对 Function Calling 支持不好。换个支持 tool calling 的模型试试。LangChain 的create_openai_tools_agent需要模型支持 OpenAI 格式的 tool calling不是所有模型都行。5.2 工具调用参数错误怎么排查打开verboseTrue看模型实际传了什么参数。常见错误类型和处理方式我整理成表错误类型典型表现解决办法参数类型不对该传字符串传了数字在描述里明确类型函数入口做类型转换参数格式不对传了“订单号12345”而非“12345”描述里给示例函数里做正则提取参数缺失该传两个参数只传了一个给参数设默认值或描述里强调必填参数多余传了工具不认识的参数函数用 **kwargs 接收忽略多余参数参数值幻觉编了一个不存在的订单号函数里校验返回“未找到”让模型重新询问我一般会在工具函数入口加一段日志把收到的参数原样打印出来。调试阶段这个日志能省很多时间。5.3 工具执行超时或报错的处理工具调用外部 API 的时候超时和报错是常态。如果直接抛异常整个智能体就挂了。我的处理方式是在工具内部捕获所有异常返回可读的错误信息。tool def call_external_api(query: str) - str: 调用外部 API 查询信息。 import requests try: resp requests.get(https://api.example.com/search, params{q: query}, timeout5) resp.raise_for_status() return resp.json().get(result, 未找到相关信息) except requests.Timeout: return 查询超时请稍后重试或换个问法 except requests.RequestException as e: return f查询服务暂时不可用错误信息{str(e)[:100]} except Exception as e: return f查询过程中出现未知错误{str(e)[:100]}这样即使 API 挂了模型也能收到一个可理解的错误信息然后决定是重试、换工具还是告诉用户稍后再试。智能体的自主容错能力很大程度上就体现在这里。5.4 智能体陷入死循环怎么破模型反复调同一个工具或者在不同工具之间来回横跳这种情况我遇到过几次。原因通常是工具返回的信息让模型觉得“还差一点”但又不知道怎么补。解决办法有几个。设置 max_iterationsAgentExecutor 有这个参数默认 15可以调小到 5-8。在工具返回值里给明确指引比如返回“未找到订单请向用户确认订单号是否正确”引导模型下一步去问用户而不是继续查。加一个“终止工具”描述写“当你已经获得足够信息可以回答用户时调用此工具结束”给模型一个明确的退出信号。5.5 常见问题速查表问题现象可能原因排查动作模型不调工具描述不清/提示词没强调检查工具描述强化 system prompt调错工具描述重叠/工具太多精简工具集划清描述边界参数错误类型/格式没约束加类型注解函数入口校验执行报错外部依赖不稳定工具内捕获异常返回友好信息死循环信息不足/无退出机制设 max_iterations加终止工具响应太慢工具串行执行考虑并行调用或减少工具数量结果不准工具返回格式差格式化返回值控制长度6. 工具设计的一些进阶思考6.1 工具粒度怎么把握工具太粗一个工具干太多事模型不好控制工具太细数量爆炸模型选择困难。我的经验是按“原子操作”来切。一个工具只做一件事但这件事是完整的。比如“处理退款”这个需求不要写一个工具叫handle_refund里面包含查订单、判断是否符合退款条件、发起退款、发通知。应该拆成query_order、check_refund_eligibility、initiate_refund、send_notification四个工具。模型可以根据情况灵活组合比如先查订单发现不符合条件就不需要调后面的了。但也不要细到get_order_id_from_text这种程度提取订单号这种事模型自己就能做不需要专门工具。6.2 工具的安全边界工具是智能体接触真实世界的接口安全必须考虑。几个原则。最小权限。查订单的工具就只给读权限不要给它写权限。需要写的时候单独开一个工具并且加确认机制。输入校验。永远不要相信模型传来的参数。SQL 注入、命令注入这些老问题在智能体场景下同样存在。工具函数里该做的校验一个都不能少。敏感操作二次确认。涉及资金、删除、发送这类不可逆操作工具内部应该有一个确认环节。可以是要求传入确认码或者先返回“待确认”状态等用户确认后再执行。审计日志。每次工具调用都记下来谁调的、什么时候、传了什么、返回了什么。智能体行为审计这个需求在合规场景下是硬性的。6.3 工具的可观测性建设生产环境的智能体可观测性和功能本身一样重要。我一般会记录这几个维度。调用链路。每次 Agent 执行生成一个 trace_id所有工具调用带上这个 id。出问题的时候能串起来看。耗时统计。每个工具的执行时间找出瓶颈。如果某个工具平均要 3 秒考虑加缓存或者优化。成功率。工具调用成功和失败的比例。失败率高的工具要重点排查。参数分布。模型传的参数都是什么样有没有异常值。这能帮你发现描述里的歧义。LangChain 本身有 callback 机制可以挂 LangSmith 或者自己写 callback handler 来收集这些数据。我一开始觉得麻烦没搞后来线上出问题排查了两小时从那以后每个项目都先把可观测性搭好。6.4 从单智能体到多智能体当业务复杂到一定程度单智能体扛不住的时候就要考虑多智能体了。LangChain 生态里有 LangGraph 可以做多智能体编排CrewAI 也是专门做这个的。多智能体的核心思路是分工。一个主管智能体负责理解需求、拆解任务、分发给专业智能体专业智能体各自管好自己的工具集。比如电商场景可以有订单智能体、退款智能体、推荐智能体、投诉智能体主管根据用户意图路由。但多智能体也带来新问题通信成本、状态同步、错误传播。我的建议是不要过早引入多智能体。单智能体加好的工具设计能解决 80% 的问题剩下 20% 再考虑拆分。拆分的时候先从最独立的领域开始比如把“技术问题”从客服智能体里拆出去而不是一上来就搞五六个智能体互相通信。7. 我踩过的几个印象深刻的坑说几个具体案例都是真金白银换来的教训。第一个坑工具描述里用了“可能”“也许”这类词。我写过一个工具描述“此工具可能用于查询物流信息”结果模型经常在该用的时候不用。后来改成“当用户询问包裹位置、配送进度时必须使用此工具”调用率立马上来了。模型对模糊词汇的敏感度比人低描述要斩钉截铁。第二个坑工具返回值太长。有个搜索工具返回了 20 条结果每条 200 字加起来 4000 字塞回给模型。结果模型处理超时而且经常抓错重点。后来改成只返回前 3 条每条摘要到 50 字以内效果好很多。上下文窗口是稀缺资源工具返回值要精打细算。第三个坑没设 max_iterations。有个智能体因为工具返回的信息有歧义模型反复调同一个工具转了 15 圈才停。用户等了半分钟。后来设成 6 圈并且在工具返回值里加了明确指引问题解决。第四个坑工具函数里抛异常。早期我图省事工具里直接raise结果整个 Agent 崩了。后来全部改成返回错误字符串智能体反而能自己处理比如换个工具重试或者告诉用户稍后再试。智能体的健壮性很大程度上取决于工具的错误处理。8. 关于工具生态的一些观察最后聊点宏观的。这两年智能体工具生态发展很快从最早的几个内置工具到现在各种工具市场、插件体系。但我觉得有几个问题还没解决好。工具的标准不统一。每个框架定义工具的方式都不一样LangChain 的 tool、OpenAI 的 function、各平台的插件互相之间迁移成本高。虽然有一些转换层但不够顺滑。工具的质量参差不齐。很多工具是 Demo 级别错误处理、边界情况都没考虑。生产环境用的时候得自己重写一遍。工具的安全审计缺失。工具能干什么、干了什么缺乏统一的审计标准。这在企业场景是很大的障碍。不过趋势是好的。越来越多的系统开始提供标准化的工具接口工具的可观测性和安全性也在被重视。我个人的判断是未来一两年工具的设计能力会成为智能体开发者的核心竞争力。模型能力大家都能用但怎么把业务能力拆成模型能理解、能调用的工具这是真功夫。如果你正在做智能体开发我的建议是先把工具设计这门手艺练好。别急着上多智能体、别急着追新框架把单个工具的描述写清楚、错误处理好、返回值格式化好这些基本功扎实了后面的事情水到渠成。我在实际项目里发现一个描述精准、容错完善的工具集比一个花哨的框架更能决定智能体的实际表现。