langchain 代理在调用自定义工具时意外传入 `arg1` 参数，导致 `typeerror`，根本原因是工具函数签名与 langchain 的参数解析机制不匹配；本文详解问题根源、兼容性修复方法及推荐的最佳实践。
在 LangChain 中，当使用 AgentExecutor 调用自定义工具时，若工具未被正确注册或其参数声明不符合 LangChain 的预期格式，代理会将输入字典强制解包为位置参数名（如 arg1, arg2），而非按实际参数名传递——这正是你看到 {'arg1': 'average temperature...'} 的原因。
你的 SQLFilterTool 继承自 BaseTool，但 _run 方法仅声明了一个带类型注解的参数 query_input: str。LangChain（尤其是较新版本，如 v0.1+）在工具自动推理（tool schema inference）过程中，不会从方法签名中提取参数名，而是默认采用通用占位符 arg1。更关键的是：BaseTool 子类要求显式定义 args_schema（Pydantic 模型）以声明输入结构，否则代理无法准确解析参数。
✅ 正确做法一：使用 @tool 装饰器（推荐）
这是最简洁、最健壮的方式，LangChain 会自动从函数签名和 docstring 生成工具描述与参数 Schema：
from langchain.agents import tool
@tool("filter_user_query")
def sql_filter_vanna(question: str) -> str:
"""对用户自然语言查询进行 SQL 过滤与生成。输入为用户问题，输出为可执行的 SQL 语句。"""
vn = VannaDefault(model=model, api_key=api_key)
return vn.generate_sql(question=question)注意：
- @tool 接收可选的工具名称字符串（如 "filter_user_query"），替代硬编码 name；
- 参数名必须为 question（或任意有意义的名称），不能是 query_input —— 因为 LangChain 会将其作为 JSON Schema 字段名；
- docstring 必须清晰描述功能与输入/输出，用于 agent 的推理决策。
✅ 正确做法二：修复 BaseTool 实现（需显式 Schema）
若必须继承 BaseTool（例如需复用复杂逻辑），则必须提供 args_schema：
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 过滤与生成。输入为用户问题，输出为可执行的 SQL 语句。"
args_schema: type[BaseModel] = SQLFilterInput # ← 关键！必须显式指定
def _run(self, question: str) -> str:
return sql_filter_vanna(question)
async def _arun(self, question: str) -> str:
# 若底层函数支持异步，请实现；否则可抛出 NotImplementedError
raise NotImplementedError("异步调用暂不支持")⚠️ 注意事项：
- 移除 __init__() 中无意义的 super().__init__()（BaseTool 初始化已由父类处理）；
- _arun 方法若不支持异步，应明确抛出 NotImplementedError，避免静默失败；
- 确保 sql_filter_vanna() 函数本身接收 question: str，与 args_schema 和 _run 参数名严格一致；
- 升级 LangChain 到最新稳定版（如 langchain==0.1.20+），旧版本存在 Schema 解析 Bug。
? 总结：
LangChain 工具的本质是“可描述、可序列化、可验证的函数接口”。@tool 装饰器通过约定优于配置（convention over configuration）大幅降低出错概率；而手动继承 BaseTool 则需承担 Schema 定义责任。无论选择哪种方式，参数名一致性（函数签名 ↔ args_schema ↔ docstring 描述）是避免 arg1 类错误的核心原则。
