企业官网建设流程全解析

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 response，JSON 解析直接报错——在 Langchain-Chatchat 里做 RAG 与 Agent 应用时，工具调用失效是最常见的坑，而且报错往往只给你半句话。这篇文章带你把 Agent 工具调用链路拆开来看：先对号入座，再按"环境 → 模型与提示词 → 工具代码 → 调用链路"四层逐层排查，每一层只解决一类问题。

快速自检表：先看现象，判断失效发生在哪一层

别急着翻代码，先把现象对到下面这张表里，能砍掉一半排查时间：

环境层：权限、网络与密钥，先排除最"外"的因素

工具代码本身没问题时，环境问题最容易被忽略。🔧 三个高频点：

• 外部 API 密钥：高德地图 POI/天气工具依赖settings.yaml里配置的 API_KEY，没配或配错时工具会静默返回空结果，而不是明确报错；
• 网络连通：search_internet、arxiv、search_youtube这类工具必须能出网。在容器里先验证一下目标域名可达性，Docker 部署时日志是主要观察窗口，报错和超时信息都会打在这里：

• 执行权限：shell工具要执行系统命令，受限用户或最小权限容器里会直接失败。

最快的排除法：先用不依赖任何外部服务的数学计算器工具（calculate）跑一遍。它通了，环境层基本可以排除，问题向内收。

模型与提示词层：Function Call 不生效，多半卡在提示词模板

这是工具调用失效的重灾区，先分清两件事：模型支不支持，格式对不对。

1. 确认模型在 Agent Factory 支持列表里。打开 libs/chatchat-server/chatchat/server/agents_registry/agents_registry.py，支持的工具调用型 Agent 有glm3、qwen、structured-chat-agent、platform-agent等类型。如果你的模型不支持 Function Call 格式，再好的提示词也没用。
2. 检查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}

3. 解析逻辑要跟上。模型输出格式和默认解析器对不上时，就会看到Could not parse model response。GLM-3/4 的做法是自定义 Agent 执行逻辑（create_structured_glm3_chat_agent+StructuredGLM3ChatOutputParser，在 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(description="a math expression")) -> float: """Useful to answer questions about simple calculations.""" import numexpr try: ret = str(numexpr.evaluate(text)) except Exception as e: ret = f"wrong: {e}" return BaseToolOutput(ret)

对照检查三点：

• 装饰器：必须用regist_tool而不是 LangChain 原生@tool，前者才会把工具写进_TOOLS_REGISTRY（见 tools_registry.py）；
• 参数描述：Field(description=...)里的文案模型是直接读到的，写得含糊（比如description="query"）模型就会传错值。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（依赖本地知识库）→ 联网工具。每一级通了再往下走，失败范围就锁死了。

避坑清单：五件可以长期做的事

1. ⚠️ 接入任何自研模型，先在prompt_settings.yaml里自定义提示词，再单独验证输出解析器，别指望默认模板通吃；
2. 新增工具后立刻确认两件事：文件被tools_factory/__init__.py导入、_TOOLS_REGISTRY里能查到；
3. 用户的提问里明确写出工具意图（"联网查一下 xxx"），官方文档专门有一节讲如何让模型知道要调用工具，照着装触发关键词；
4. 排查时保留模型原始输出，和$JSON_BLOB模板逐字段比对，解析报错大多差在一个引号或换行；
5. 环境类问题用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