昨天凌晨三点我被线上一个 Agent 的报警吵醒。日志里反复出现一条错误ToolInputParsingException: Could not parse tool input。排查下来问题出在一个自定义工具上——我写了一个查询天气的 Tool返回的是 JSON 字符串但 LLM 在调用时传进来的参数格式跟预期对不上。LLM 以为它传的是{location: Beijing}但我的工具函数签名里写的是def run(self, location: str)LangChain 的默认解析器直接把整个字典当成了一个字符串参数塞了进去。结果就是工具收到了{location: Beijing}这个字符串而不是一个字典自然就炸了。这个坑让我意识到很多人包括当时的我对 LangChain 中 Tool 的底层机制理解得不够深。今天这篇笔记我们就从这个问题出发把自定义工具和第三方工具集成的细节彻底捋一遍。1. Tool 的本质一个带“说明书”的函数LangChain 里的 Tool本质上就是一个函数外加一份给 LLM 看的“说明书”。这个说明书就是name和description。LLM 根据 description 决定要不要调用这个工具根据 name 决定调用哪个工具然后根据函数的参数签名或者你手动定义的 args_schema来生成调用参数。所以开发一个自定义工具核心就两件事写好函数逻辑写好说明书。说明书写不好LLM 要么不调用要么乱调用。2. 自定义工具三种写法各有坑LangChain 提供了三种定义 Tool 的方式我按推荐程度排个序。方式一tool 装饰器最推荐但要注意类型注解fromlangchain.toolsimporttooltooldefget_weather(location:str)-str:查询指定城市的天气。输入应为城市名称例如 Beijing 或 Shanghai。# 这里踩过坑如果返回的是 dictLLM 可能无法直接处理# 最好统一返回字符串returnf{location}的天气是晴天25°C这个写法最简洁LangChain 会自动从函数签名和 docstring 里提取参数信息。但有个隐藏问题如果你的参数是location: str Beijing给了默认值LLM 可能会偷懒不传参直接使用默认值。所以别给工具参数设默认值除非你确定 LLM 的行为符合预期。方式二继承 BaseTool 类最灵活但代码多fromlangchain.toolsimportBaseToolfrompydanticimportBaseModel,FieldclassWeatherInput(BaseModel):location:strField(description城市名称如 Beijing)classWeatherTool(BaseTool):nameget_weatherdescription查询指定城市的天气args_schema:type[BaseModel]WeatherInputdef_run(self,location:str)-str:# 实际业务逻辑returnf{location}的天气是晴天25°Casyncdef_arun(self,location:str)-str:# 异步版本如果不需要可以 raise NotImplementedErrorraiseNotImplementedError(异步调用暂不支持)这种方式的好处是你可以精确控制参数结构。比如你的工具需要同时接收location和date两个参数用 Pydantic 模型定义就非常清晰。而且args_schema里每个字段的description会被 LLM 看到这能显著提高参数生成的准确率。方式三直接实例化 Tool 类最不推荐容易出问题fromlangchain.toolsimportTooldefweather_func(location:str)-str:returnf{location}的天气是晴天25°Cweather_toolTool(nameget_weather,funcweather_func,description查询指定城市的天气。输入应为城市名称。)这种写法看着简单但问题在于description里没有明确告诉 LLM 参数格式。LLM 可能会传{location: Beijing}这种字典而你的函数只接受字符串就会触发我开头说的那个解析异常。除非你的函数只有一个参数且参数名非常直观否则别用这种写法。3. 第三方工具集成别自己造轮子LangChain 社区已经集成了大量第三方工具从 SerpAPI 到 Wikipedia从 Wolfram Alpha 到 YouTube 搜索。集成方式很简单fromlangchain_community.toolsimportWikipediaQueryRunfromlangchain_community.utilitiesimportWikipediaAPIWrapper wikipediaWikipediaQueryRun(api_wrapperWikipediaAPIWrapper(top_k_results1,doc_content_chars_max500))但这里有个容易忽略的点第三方工具的 description 可能不适合你的场景。比如 Wikipedia 工具的默认 description 是“A wrapper around Wikipedia. Useful for when you need to answer general questions about people, places, companies, facts, historical events, or other subjects.” 这个描述太长LLM 可能会被误导。我习惯在集成后手动修改 descriptionwikipedia.description搜索维基百科获取人物、地点、事件等知识。输入应为搜索关键词。另外很多第三方工具需要 API Key。别硬编码在代码里用环境变量。我见过有人把 API Key 直接写在 Tool 的__init__方法里然后代码上传到 GitHub 公开仓库——别这样写。4. 工具链的“暗坑”参数传递与错误处理回到开头的那个问题。为什么 LLM 传的参数格式会跟工具预期的不一致因为 LLM 看到的“说明书”是description和args_schema但实际执行时LangChain 内部有一个ToolInputParser负责把 LLM 输出的字符串通常是 JSON解析成 Python 对象。如果你的工具参数简单比如只有一个字符串LLM 可能会直接输出Beijing而不是{location: Beijing}。这时候默认的解析器会尝试把Beijing当成 JSON 解析结果失败。解决方案有两个在 description 里明确告诉 LLM 参数格式。比如“输入应为 JSON 格式例如{\location\: \Beijing\}”。但 LLM 不一定每次都听话。使用 Pydantic 模型定义 args_schema并设置strictTrue。这样 LangChain 会强制 LLM 输出符合 schema 的 JSON。我推荐第二种因为更可靠。但要注意strictTrue会让 LLM 在无法生成合法 JSON 时直接报错而不是尝试“猜”一个格式。这其实更好——宁可让 Agent 明确失败也不要让它带着错误数据继续执行。5. 调试技巧让 LLM 的“思考过程”可见当你发现工具调用不正常时第一件事不是改代码而是看 LLM 到底输出了什么。在 LangChain 中可以通过设置verboseTrue来打印 LLM 的完整输出agentinitialize_agent(tools[weather_tool],llmllm,agentAgentType.ZERO_SHOT_REACT_DESCRIPTION,verboseTrue# 这里踩过坑生产环境记得关掉否则日志会爆炸)你会看到类似这样的输出 Entering new AgentExecutor chain... Thought: 用户想知道北京的天气我需要调用 get_weather 工具。 Action: get_weather Action Input: Beijing Observation: Beijing 的天气是晴天25°C Thought: 我已经得到了结果可以回答用户了。 Final Answer: 北京今天天气晴朗气温25°C。如果Action Input的格式跟你预期的不一样那就是 description 或 args_schema 的问题。如果Observation是空或者报错那就是工具函数本身的问题。6. 个人经验工具开发的三条铁律工具函数的返回值必须是字符串。不要返回 dict、list 或自定义对象。LLM 只能理解文本你返回一个 Python 对象它看不懂。如果必须返回结构化数据用 JSON 字符串并在 description 里说明格式。每个工具只做一件事。我见过有人写一个execute_sql工具既能查询又能修改还能删除。这很危险——LLM 可能会在用户只要求查询时执行了删除操作。把查询、修改、删除拆成三个独立的工具每个工具的 description 里明确说明它的职责和限制。给工具加“护栏”。比如一个发送邮件的工具在_run方法里检查收件人地址是否在白名单中。LLM 可能会被 prompt injection 攻击诱导它发送恶意邮件。工具函数是你最后的防线别完全信任 LLM 的输入。最后关于第三方工具集成我的建议是能用现成的就别自己写。LangChain 社区维护的第三方工具经过了大量用户的测试稳定性比自己写的要高。但一定要检查它的 description 和参数定义是否符合你的需求必要时手动修改。下一篇我会讲 Agent 的“记忆”机制——为什么你的 Agent 总是“记不住”之前说过的话以及如何让它在长对话中保持上下文连贯。