Langchain-Chatchat Agent工具调用失效5分钟排查指南【免费下载链接】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当你在 Langchain-Chatchat 的 WebUI 里提问“计算 3.5×12 的结果”时你会看到模型直接用一段话作答对话区没有出现任何工具调用记录再追问“联网搜索北京天气”它依旧凭记忆回答。Agent 工具调用失效时先别急着重装环境本文带你从配置文件、注册链路、模型到提示词逐层定位并修复。先看正常状态Agent 走通一次共四步先知道正常时是什么样子才能看出问题偏在哪一步。一次正常的 Agent 工具调用要经过四步。第一步是工具注册每个工具用regist_tool装饰器写入全局注册表内置工具都在 libs/chatchat-server/chatchat/server/agent/tools_factory/ 下。第二步是模型配置你用于 Agent 对话的模型写在model_settings.yaml的SUPPORT_AGENT_MODELS列表里配套的输出格式模板在prompt_settings.yaml中。第三步是请求组装对话请求进来后服务读取注册表并按前端传来的工具清单筛选出本次可用的工具这份清单相当于给模型的一张“授权名单”不在名单里的工具进不了对话。第四步是执行循环模型按约定格式输出工具名和参数工具执行并返回 Observation几轮思考后给出最终答案。按自查表逐层过四关环境、注册、模型、提示词 出问题时不要跳着猜按下面从外到内的顺序检查一轮下来就能定位问题落在哪一层。检查层怎么查这一层有问题怎么办环境/配置确认启动目录下有basic_settings.yaml、model_settings.yaml、tool_settings.yaml、prompt_settings.yaml配置缺失或过期时重建配置模板再重启服务工具注册在 Python 会话里执行get_tool()看返回的字典里有没有你期望的工具名检查工具文件是否被tools_factory/__init__.py导入、tool_settings.yaml中use是否为 True模型层对照model_settings.yaml的SUPPORT_AGENT_MODELS列表核对你选的模型换成受支持模型如glm-4、qwen2-instruct或把模型加入列表并配好模板提示词/参数打开prompt_settings.yaml核对action_model模板与模型的输出格式是否一致把action_model的prompt_name改为glm3、qwen、structured-chat-agent等匹配模板每个配置项的说明可查 docs/contributing/settings.md配置模板定义在 libs/chatchat-server/chatchat/settings.py。复盘三个真实故障场景注册链、模型格式、知识库描述场景一新加工具后模型从不调用补上注册链你照 docs/contributing/agent.md 的“增加自己的工具”一节在tools_factory/下写了my_tool.py函数加了regist_tool(title...)装饰器代码本身没有语法问题。但在 WebUI 里问“用 my_tool 处理……”时模型直接作答没有产生工具调用。定位过程先怀疑工具本体可装饰器写法与文档示例完全一致再打开同目录的tools_factory/__init__.py才发现问题——现有每个工具都有一行from .calculate import calculate这样的导入而你的新文件没有。工具注册表像一本通讯录条目写对了、没人登记也就没人能拨通。get_tool()是先导入tools_factory包再读取注册表的my_tool.py从未被导入装饰器就没执行过工具在注册表里根本不存在。修复方法在__init__.py末尾补一行from .my_tool import my_tool然后在tool_settings.yaml里给my_tool配上use: True重启服务模型就能选中这个工具了。场景二模型直接回一段话模型与提示词模板对齐另一个典型现场你把 Agent 模型换成一个不支持 Function Call 的小模型后问一道需要计算的题模型输出一句自然语言“结果是 42”对话区始终没有工具执行记录。定位过程先对照model_settings.yaml的SUPPORT_AGENT_MODELS这个模型名不在列表里再看 Agent 的系统提示词——action_model模板要求模型每一步输出含action和action_input的 JSON而这个模型从不输出 JSON解析逻辑取不到工具名循环只能空转收尾。问题不在工具是模型和模板没对上。修复方法把 Agent 模型换回列表内的例如glm-4、qwen2-instruct、gpt-3.5-turbo。确实要用自定义模型时先把它写进列表SUPPORT_AGENT_MODELS: - chatglm3-6b - glm-4 - openai-api - Qwen-2 - qwen2-instruct - gpt-3.5-turbo - gpt-4o - your-model-name再按模型输出格式选prompt_settings.yaml里LLM_MODEL_CONFIG.action_model.prompt_name对应的模板GLM-3 系列配glm3Qwen 系列配qwen通用 JSON 格式配structured-chat-agent。GLM-3/4 还有自定义的 Agent 执行逻辑来解析输出写法见 docs/contributing/agent.md 的“优化 Agent 系统提示词”一节。场景三新建知识库后工具从不调用先补上描述第三个现场最容易被忽略你新建了知识库并上传文档提问“根据 XX 文档说明……”时模型靠自身知识作答本地知识库工具始终没被触发。定位过程先查工具注册和use开关都没问题再往下查发现kb_settings.yaml里的KB_INFO只有samples一个默认条目。settings.py中该配置项的注释写得很直白没写描述的知识库不会被 Agent 调用。你的新知识库没有描述模型不知道它的存在和适用范围自然不会主动选它。修复方法在kb_settings.yaml的KB_INFO里补一行例如your-kb-name: 这个知识库的适用范围说明重启服务后重新提问模型才会把该知识库纳入候选。修完1分钟冒烟测试确认工具全部可用在 Python 会话里确认注册表里所有工具都在from chatchat.server.utils import get_tool print(list(get_tool().keys()))返回列表应包含calculate、search_internet、search_local_knowledgebase等名字。在 WebUI 选一个SUPPORT_AGENT_MODELS内的模型问“用数学计算器算 3.5×12”对话区应出现工具执行过程和中间结果最终答案为 42。再问一个需要联网的问题确认对话区出现工具输出且答案基于搜索结果。三步都通过即修复完成第 1 步缺名字就回到场景一。把六条防复发动作放进日常清单✅ 1. 新加工具固定走三步写regist_tool→ 在tools_factory/__init__.py加导入 → 在tool_settings.yaml设use: True一步都不能省。改过model_settings.yaml、tool_settings.yaml或prompt_settings.yaml后重启服务否则旧配置仍留在内存里。Agent 对话只用SUPPORT_AGENT_MODELS内的模型新加模型时同步配好action_model模板。新建知识库时先在KB_INFO写一行适用范围描述否则 Agent 不会调用它。改完工具代码先用验证节的一行命令自检注册表再做端到端测试避免“忘了写导入”这类低级耗时。出问题时先翻data/logs目录下的日志看工具执行链路权限和网络类错误大多在那里留有记录。工具完整列表与自定义工具写法见 docs/contributing/agent.md社区讨论入口见 README.md 文末。【免费下载链接】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），仅供参考