LangChain 工具调用错误解析：arg1 参数问题与解决方法

LangChain 代理在调用自定义工具时意外传入 `arg1` 参数，导致 `TypeError`，根本原因是工具未按 LangChain v0.1+ 的新规范正确定义输入参数签名，需使用 `@tool` 装饰器或显式声明 `args_schema`。

在 LangChain 的现代版本（特别是 v0.1.x 及以上）中，Agent 执行器对工具的参数解析机制已发生重要变化：它不再依赖 _run() 方法的原始函数签名推断输入，而是严格依据工具的 args_schema（Pydantic 模型）或 @tool 装饰器自动推导的 schema 来绑定参数。当你直接继承 BaseTool 并仅定义 _run(self, query_input: str) 时，LangChain 无法识别 query_input 是唯一期望参数，因此默认将传入的字典（如 {'arg1': '...'}）以位置参数形式尝试解包，最终触发 unexpected keyword argument 'arg1' 错误。

✅ 正确做法有以下两种推荐方案：

方案一：使用 @tool 装饰器（推荐，简洁且健壮）
这是官方最推荐的方式，自动处理类型注解、描述生成与参数校验：

from langchain.agents import tool
from typing import Optional

@tool("filter_user_query")
def sql_filter_vanna(question: str) -> str:
    """对用户自然语言查询进行 SQL 语义解析与过滤，返回可执行的 SQL 语句。

    例如：输入“2023年8月计算机设备的平均温度”，输出"SELECT AVG(temperature) FROM sensors WHERE device_type = 'computer' AND month = 'August' AND year = 2023;"
    """
    # 注意：此处应复用已初始化的 Vanna 实例，避免每次调用重复初始化
    return sql_filter_vanna_impl(question)  # 封装实际逻辑，确保 vn 实例单例或缓存

# 注册到 Agent 时直接使用该函数对象
tools = [sql_filter_vanna]

⚠️ 关键提示：@tool 装饰器要求参数必须有明确的类型注解（如 str, int, Optional[str]），且函数文档字符串（docstring）会自动作为 description 使用——这是 Agent 决策的关键依据。

方案二：修复 BaseTool 子类，显式定义 args_schema
若需保留类结构（如需状态管理、依赖注入等），必须提供 Pydantic BaseModel 描述输入：

from langchain.tools import BaseTool
from pydantic import BaseModel, Field

class SQLFilterInput(BaseModel):
    question: str = Field(..., description="用户提出的自然语言查询，需转换为结构化SQL条件")

class SQLFilterTool(BaseTool):
    name = "filter_user_query"
    description = "将用户自然语言问题转换为数据库可执行的SQL过滤条件"
    args_schema: type[BaseModel] = SQLFilterInput  # ✅ 必须显式声明！

    def _run(self, question: str) -> str:
        return sql_filter_vanna_impl(question)

    async def _arun(self, question: str) -> str:
        # 若支持异步，请实现；否则可省略或抛出 NotImplementedError
        raise NotImplementedError("异步暂不支持")

? 为什么旧代码突然失效？
你提到“几天前还能运行”，大概率是因 LangChain 升级（如从 0.0.x 升至 0.1.x）。v0.1 引入了严格的工具 schema 驱动机制，废弃了旧版基于 inspect.signature 的模糊匹配逻辑，以提升 Agent 推理可靠性与可调试性。

? 额外建议：

• 避免在 _run 中重复初始化重资源（如 VannaDefault），应在工具初始化时创建并复用；
• 使用 langchain.debug = True 开启调试日志，直观查看 Agent 如何解析和调用工具；
• 工具名称（name）应语义清晰、无空格/特殊字符，利于 Agent 理解。

遵循上述任一方案，即可彻底解决 arg1 参数错误，让工具重新被 Agent 稳定、准确地调用。