Langchain-Chatchat Agent 工具调用失效排查清单从外到内逐层定位10 分钟修复【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat你让模型联网搜索一下最新的 AI 新闻它却自顾自开始凭记忆作答或者日志里突然冒出一句no tool named search_internet又或者Could not parse model responseJSON 解析直接报错——在 Langchain-Chatchat 里做 RAG 与 Agent 应用时工具调用失效是最常见的坑而且报错往往只给你半句话。这篇文章带你把 Agent 工具调用链路拆开来看先对号入座再按环境 → 模型与提示词 → 工具代码 → 调用链路四层逐层排查每一层只解决一类问题。快速自检表先看现象判断失效发生在哪一层别急着翻代码先把现象对到下面这张表里能砍掉一半排查时间失败现象大概率出在哪一层对应排查动作模型直接文本回答从不输出工具调用模型与提示词层确认模型在 Agent Factory 支持列表内检查提示词模板模型输出了 JSON 但报Could not parse model response模型与提示词层对比 GLM-3 自定义 Agent 的执行逻辑与输出解析器日志报no tool named xxx工具代码层 / 调用链路层检查regist_tool注册、文件是否被导入工具执行返回权限错误、超时或空结果环境层检查网络连通、API 密钥、容器运行权限环境层权限、网络与密钥先排除最外的因素工具代码本身没问题时环境问题最容易被忽略。 三个高频点外部 API 密钥高德地图 POI/天气工具依赖settings.yaml里配置的 API_KEY没配或配错时工具会静默返回空结果而不是明确报错网络连通search_internet、arxiv、search_youtube这类工具必须能出网。在容器里先验证一下目标域名可达性Docker 部署时日志是主要观察窗口报错和超时信息都会打在这里执行权限shell工具要执行系统命令受限用户或最小权限容器里会直接失败。最快的排除法先用不依赖任何外部服务的数学计算器工具calculate跑一遍。它通了环境层基本可以排除问题向内收。模型与提示词层Function Call 不生效多半卡在提示词模板这是工具调用失效的重灾区先分清两件事模型支不支持格式对不对。确认模型在 Agent Factory 支持列表里。打开 libs/chatchat-server/chatchat/server/agents_registry/agents_registry.py支持的工具调用型 Agent 有glm3、qwen、structured-chat-agent、platform-agent等类型。如果你的模型不支持 Function Call 格式再好的提示词也没用。检查prompt_settings.yaml模板。你的模型若不兼容 LangChain 默认的 Structured Agent 提示词需要在这个文件里位于chatchat包根目录自定义agent_prompt且必须保留{tools}、{tool_names}、$JSON_BLOB这些占位符# GLM-3 系列的提示词模板节选完整版本参考 docs/contributing/agent.md agent_prompt: | You can answer using the tools. ... You have access to the following tools: {tools} Use a json blob to specify a tool by providing an action key (tool name) and an action_input key (tool input). Valid action values: Final Answer or [{tool_names}] ... Question: {input} {agent_scratchpad}解析逻辑要跟上。模型输出格式和默认解析器对不上时就会看到Could not parse model response。GLM-3/4 的做法是自定义 Agent 执行逻辑create_structured_glm3_chat_agentStructuredGLM3ChatOutputParser在 libs/chatchat-server/langchain_chatchat/agents 下。 你自定义模型时照这套思路走一遍先看模型原始输出长什么样再决定解析器怎么改。工具代码层regist_tool 的三个关键点自研工具调不通九成是注册环节的写法问题。官方模板在 libs/chatchat-server/chatchat/server/agent/tools_factory 下拿计算器工具当标尺from chatchat.server.pydantic_v1 import Field from .tools_registry import regist_tool from langchain_chatchat.agent_toolkits.all_tools.tool import BaseToolOutput regist_tool(title数学计算器) def calculate(text: str Field(descriptiona math expression)) - float: Useful to answer questions about simple calculations. import numexpr try: ret str(numexpr.evaluate(text)) except Exception as e: ret fwrong: {e} return BaseToolOutput(ret)对照检查三点装饰器必须用regist_tool而不是 LangChain 原生tool前者才会把工具写进_TOOLS_REGISTRY见 tools_registry.py参数描述Field(description...)里的文案模型是直接读到的写得含糊比如descriptionquery模型就会传错值。docstring 同样重要——注册时它会成为工具的 description返回封装统一返回BaseToolOutput否则下游格式化上下文会炸。一个隐蔽坑新建的工具文件必须被 tools_factory/init.py 导入注册代码才会执行。文件写好了但没 import工具就是不存在——这正是no tool named xxx的典型来源之一这个报错出自 tool_routes.py。另外Field要从chatchat.server.pydantic_v1导入直接from pydantic import Field在 v1/v2 混用的环境里容易踩参数解析的坑。调用链路层确认 Agent Factory 拿到的工具清单代码都对了还不调最后一层看链路。工具注册状态怎么查在 Python 里直接打印注册表比猜快from chatchat.server.agent.tools_factory.tools_registry import _TOOLS_REGISTRY print(list(_TOOLS_REGISTRY.keys()))工具名以函数名为准。提示词里的{tools}展开后就是这份清单模型输出action时用的是这里面的名字——如果你的自定义 Agent 里手写了工具名、和注册名差一个下划线或大小写日志就会给你no tool named xxx。Agent Factory 配置核对确认你当前会话使用的 Agent 类型glm3/qwen/platform-agent等与模型匹配platform-agent会走平台工具绑定逻辑工具清单和普通 structured-chat 不一样。日志怎么看Agent 执行是 Thought/Action/Observation 循环多轮调用时重点看每轮 Observation 是否为空、是否出现重复 Action模型拿不到有效反馈会原地打转。官方文档 docs/contributing/agent.md 里有完整的多轮执行示例调试顺序建议calculate无外部依赖→search_local_knowledgebase依赖本地知识库→ 联网工具。每一级通了再往下走失败范围就锁死了。避坑清单五件可以长期做的事⚠️ 接入任何自研模型先在prompt_settings.yaml里自定义提示词再单独验证输出解析器别指望默认模板通吃新增工具后立刻确认两件事文件被tools_factory/__init__.py导入、_TOOLS_REGISTRY里能查到用户的提问里明确写出工具意图联网查一下 xxx官方文档专门有一节讲如何让模型知道要调用工具照着装触发关键词排查时保留模型原始输出和$JSON_BLOB模板逐字段比对解析报错大多差在一个引号或换行环境类问题用calculate做金丝雀它不依赖网络、密钥和权限通与不通一步分清。按这个顺序走绝大多数 Agent 工具调用失效都能在 10 分钟内定位到具体那一层。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Langchain-Chatchat Agent 工具调用失效排查清单：从外到内逐层定位，10 分钟修复
Langchain-Chatchat Agent 工具调用失效排查清单从外到内逐层定位10 分钟修复【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat你让模型联网搜索一下最新的 AI 新闻它却自顾自开始凭记忆作答或者日志里突然冒出一句no tool named search_internet又或者Could not parse model responseJSON 解析直接报错——在 Langchain-Chatchat 里做 RAG 与 Agent 应用时工具调用失效是最常见的坑而且报错往往只给你半句话。这篇文章带你把 Agent 工具调用链路拆开来看先对号入座再按环境 → 模型与提示词 → 工具代码 → 调用链路四层逐层排查每一层只解决一类问题。快速自检表先看现象判断失效发生在哪一层别急着翻代码先把现象对到下面这张表里能砍掉一半排查时间失败现象大概率出在哪一层对应排查动作模型直接文本回答从不输出工具调用模型与提示词层确认模型在 Agent Factory 支持列表内检查提示词模板模型输出了 JSON 但报Could not parse model response模型与提示词层对比 GLM-3 自定义 Agent 的执行逻辑与输出解析器日志报no tool named xxx工具代码层 / 调用链路层检查regist_tool注册、文件是否被导入工具执行返回权限错误、超时或空结果环境层检查网络连通、API 密钥、容器运行权限环境层权限、网络与密钥先排除最外的因素工具代码本身没问题时环境问题最容易被忽略。 三个高频点外部 API 密钥高德地图 POI/天气工具依赖settings.yaml里配置的 API_KEY没配或配错时工具会静默返回空结果而不是明确报错网络连通search_internet、arxiv、search_youtube这类工具必须能出网。在容器里先验证一下目标域名可达性Docker 部署时日志是主要观察窗口报错和超时信息都会打在这里执行权限shell工具要执行系统命令受限用户或最小权限容器里会直接失败。最快的排除法先用不依赖任何外部服务的数学计算器工具calculate跑一遍。它通了环境层基本可以排除问题向内收。模型与提示词层Function Call 不生效多半卡在提示词模板这是工具调用失效的重灾区先分清两件事模型支不支持格式对不对。确认模型在 Agent Factory 支持列表里。打开 libs/chatchat-server/chatchat/server/agents_registry/agents_registry.py支持的工具调用型 Agent 有glm3、qwen、structured-chat-agent、platform-agent等类型。如果你的模型不支持 Function Call 格式再好的提示词也没用。检查prompt_settings.yaml模板。你的模型若不兼容 LangChain 默认的 Structured Agent 提示词需要在这个文件里位于chatchat包根目录自定义agent_prompt且必须保留{tools}、{tool_names}、$JSON_BLOB这些占位符# GLM-3 系列的提示词模板节选完整版本参考 docs/contributing/agent.md agent_prompt: | You can answer using the tools. ... You have access to the following tools: {tools} Use a json blob to specify a tool by providing an action key (tool name) and an action_input key (tool input). Valid action values: Final Answer or [{tool_names}] ... Question: {input} {agent_scratchpad}解析逻辑要跟上。模型输出格式和默认解析器对不上时就会看到Could not parse model response。GLM-3/4 的做法是自定义 Agent 执行逻辑create_structured_glm3_chat_agentStructuredGLM3ChatOutputParser在 libs/chatchat-server/langchain_chatchat/agents 下。 你自定义模型时照这套思路走一遍先看模型原始输出长什么样再决定解析器怎么改。工具代码层regist_tool 的三个关键点自研工具调不通九成是注册环节的写法问题。官方模板在 libs/chatchat-server/chatchat/server/agent/tools_factory 下拿计算器工具当标尺from chatchat.server.pydantic_v1 import Field from .tools_registry import regist_tool from langchain_chatchat.agent_toolkits.all_tools.tool import BaseToolOutput regist_tool(title数学计算器) def calculate(text: str Field(descriptiona math expression)) - float: Useful to answer questions about simple calculations. import numexpr try: ret str(numexpr.evaluate(text)) except Exception as e: ret fwrong: {e} return BaseToolOutput(ret)对照检查三点装饰器必须用regist_tool而不是 LangChain 原生tool前者才会把工具写进_TOOLS_REGISTRY见 tools_registry.py参数描述Field(description...)里的文案模型是直接读到的写得含糊比如descriptionquery模型就会传错值。docstring 同样重要——注册时它会成为工具的 description返回封装统一返回BaseToolOutput否则下游格式化上下文会炸。一个隐蔽坑新建的工具文件必须被 tools_factory/init.py 导入注册代码才会执行。文件写好了但没 import工具就是不存在——这正是no tool named xxx的典型来源之一这个报错出自 tool_routes.py。另外Field要从chatchat.server.pydantic_v1导入直接from pydantic import Field在 v1/v2 混用的环境里容易踩参数解析的坑。调用链路层确认 Agent Factory 拿到的工具清单代码都对了还不调最后一层看链路。工具注册状态怎么查在 Python 里直接打印注册表比猜快from chatchat.server.agent.tools_factory.tools_registry import _TOOLS_REGISTRY print(list(_TOOLS_REGISTRY.keys()))工具名以函数名为准。提示词里的{tools}展开后就是这份清单模型输出action时用的是这里面的名字——如果你的自定义 Agent 里手写了工具名、和注册名差一个下划线或大小写日志就会给你no tool named xxx。Agent Factory 配置核对确认你当前会话使用的 Agent 类型glm3/qwen/platform-agent等与模型匹配platform-agent会走平台工具绑定逻辑工具清单和普通 structured-chat 不一样。日志怎么看Agent 执行是 Thought/Action/Observation 循环多轮调用时重点看每轮 Observation 是否为空、是否出现重复 Action模型拿不到有效反馈会原地打转。官方文档 docs/contributing/agent.md 里有完整的多轮执行示例调试顺序建议calculate无外部依赖→search_local_knowledgebase依赖本地知识库→ 联网工具。每一级通了再往下走失败范围就锁死了。避坑清单五件可以长期做的事⚠️ 接入任何自研模型先在prompt_settings.yaml里自定义提示词再单独验证输出解析器别指望默认模板通吃新增工具后立刻确认两件事文件被tools_factory/__init__.py导入、_TOOLS_REGISTRY里能查到用户的提问里明确写出工具意图联网查一下 xxx官方文档专门有一节讲如何让模型知道要调用工具照着装触发关键词排查时保留模型原始输出和$JSON_BLOB模板逐字段比对解析报错大多差在一个引号或换行环境类问题用calculate做金丝雀它不依赖网络、密钥和权限通与不通一步分清。按这个顺序走绝大多数 Agent 工具调用失效都能在 10 分钟内定位到具体那一层。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考