今日 LangChain 学习 Bug 记录总结（Markdown 版）

一、Agent 新版 API 相关 Bug 及解决方案

1. 混用新旧 Agent 导致报错（`'str' object has no attribute 'tool'` / `log`）

• 报错原因：同时使用新版 `create_agent` + 旧版 `langchain_classic` 包 + 旧版 `AgentExecutor`，三者完全不兼容，新版 LangChain 1.x 已废弃旧版相关组件。

• 解决方案：

• 移除 `langchain_classic` 相关导入，避免与新版混用；

• 放弃导入 `AgentExecutor`，新版 Agent 仅保留 `create_agent`，无需额外包装执行器。

2. 新版 Agent 无 AgentExecutor 导致的调用异常

• 报错/异常表现：强行导入 `AgentExecutor` 失败，或用旧版 `AgentExecutor` 包装新版 `create_agent` 后报错、乱回复。

• 报错原因：新版 LangChain 1.x 中 `AgentExecutor` 已不存在，仅保留 `create_agent`，直接调用 `create_agent` 即可生成可运行的 Agent。

• 解决方案：仅使用 `create_agent` 创建 Agent，无需添加 `AgentExecutor` 包装。

3. Agent 输入格式错误导致乱回复

• 报错/异常表现：直接 invoke agent 时出现乱回复（如无意义反问、固定错误文本）。

• 报错原因：输入格式不对（如用单数 `message`、空消息列表、`input` 格式），或混入旧版执行器导致格式不兼容；新版 Agent 只认 `messages` 结构。

• 解决方案：输入必须是 `{"messages": [HumanMessage(...)]}` 格式，可传入 `HumanMessage` 对象或 `{"role": "user", "content": "问题"}` 字典，确保键名为复数 `messages`。

4. Agent 工具调用不稳定（随机不调用工具）

• 表现：两段完全相同的 Agent 工具调用代码，多次运行后出现“有时调用工具、有时不调用”的随机情况（无代码错误）。

• 原因：通义千问 qwen3-max 模型自身存在随机性，对工具触发门槛的判断不稳定，未明确收到“必须调用工具”的指令时，可能直接生成回答。

• 解决方案：在 `system_prompt` 中添加强制提示，示例：`你是市场经济分析专家，可以分析股票相关问题。必须优先调用工具获取信息，不允许直接猜测答案！`，确保模型100%触发工具调用。

5. Agent 工具定义与调用细节问题

• 表现：工具调用时参数传递异常，或未正确识别工具功能。

• 原因：工具装饰器 `@tool` 描述不清晰，或工具函数参数定义不规范（如缺少参数说明）。

• 解决方案：

  • 给 `@tool` 装饰器添加清晰的 `description`，明确工具功能（如 `@tool(description='查询股票价格')`）；

  • 工具函数参数定义规范（如 `def get_price(name: str) -> str`），确保模型能正确传递参数。

二、LangChain 版本/路径相关 Bug 及解决方案

1. 旧链废弃导致的报错

• 报错原因：旧版 `RetrievalQA` 链已废弃，继续使用会导致导入失败或运行异常。

• 解决方案：改用 LCEL 链式写法构建 RAG 链，示例：`self.rag_chain = ({"context": self.retriever | format_docs, "question": RunnablePassthrough()} | prompt | self.llm | StrOutputParser())`。

2. Chroma 向量库旧方法废弃

• 报错/异常表现：调用 `vector_store.persist()` 时出现警告或报错。

• 报错原因：Chroma 新版已实现自动持久化，旧方法 `.persist()` 已废弃。

• 解决方案：删除 `vector_store.persist()` 调用，调用 `add_documents()` 后数据会自动落盘持久化。

3. 导入包错乱导致的报错

• 报错原因：

  • 混淆 `langchain` 新版与 `langchain_classic` 兼容包，两者混用导致组件冲突；

  • 强行导入新版不存在的组件（如 `AgentExecutor`），导致导入失败。

• 解决方案：

  • 仅使用 `langchain` 新版包，不导入 `langchain_classic`；

  • 不强行导入新版不存在的组件（如 `AgentExecutor`），遵循新版 API 规范。

4. 文本分割器包路径错误

• 报错表现：从 `langchain.text_splitter` 导入 `RecursiveCharacterTextSplitter` 时出现“找不到模块”报错。

• 报错原因：新版 LangChain 已将文本分割器独立为新包，路径发生变更。

• 解决方案：从 `langchain_text_splitters` 导入，同时安装依赖：`pip install langchain-text-splitters`。

三、关键注意事项

• 避免混用 `langchain` 新版与 `langchain_classic`，否则会导致组件冲突、报错；

• 排查 Bug 优先级：先检查格式（消息格式、传参格式）→ 再检查版本兼容性 → 最后排查模型随机性/提示词问题；

• 流式调用 Agent 时，使用 `stream_mode='values'` 可获取每一步状态（用户消息、工具调用、工具结果、最终回答），便于调试。

四、今日实操总结

今日所有 Bug 均围绕「新版 LangChain API 规范」「版本兼容性」「格式规范」「模型特性」四大核心，其中“混用新旧版本”“输入格式错误”是高频报错点。通过梳理可知，新版 LangChain 简化了 Agent 调用流程（无 `AgentExecutor`）、废弃了旧链和旧方法，只需遵循新版 API 规范、规避版本混用、规范输入格式，即可解决大部分报错；针对模型随机性问题，可通过强提示进一步规避，确保工具调用稳定。