在 ​LangChain​ 中，@tool是一个非常重要的装饰器，它是 ​LangChain Tools 框架的一部分，用于将普通的 Python 函数 ​标记为“工具”（Tool）​，从而让 ​AI 模型（如大语言模型 LLM）能够在运行时发现并调用这些函数，以实现 ​工具调用（Function Calling）、工具使用（Tool Use）​​ 的能力。

---

一、🔧 LangChain 中 @tool的作用

@tool是 LangChain 提供的一个 ​装饰器，主要用途是：

​将一个普通的 Python 函数“包装”成一个工具（Tool），使 AI 可以理解它的用途、参数和返回值，并在适当的时候调用它，就像调用一个外部 API 或功能模块一样。​​

它通常与 LangChain 的 ​工具系统（Tools System）​​ 和 ​Agent 系统​ 一起使用，是构建 ​能调用外部功能（如查天气、计算、搜索等）的智能代理（Agent）​​ 的关键部分。

---

二、📦 来自哪个模块？

@tool装饰器来自于 LangChain 的 langchain.tools模块，更具体地说，是从 langchain.tools的子模块 langchain.tools或 langchain.tools.decorators导入的（不同版本可能略有差异）。

在 ​较新版本的 LangChain（比如 0.2.x 及以上）​​ 中，通常是这样导入的：

from langchain.tools import tool

这个 tool就是一个 ​装饰器函数，你可以用它来装饰你的普通函数，使其变成一个 LangChain 工具。

---

三、🔍 基本用法示例

下面是一个最基本的 @tool使用示例：

from langchain.tools import tool

@tool
def search_weather(city: str) -> str:
    """查询某个城市的天气情况"""
    if city.lower() == "上海":
        return "上海今天天气晴朗"
    else:
        return f"{city}的天气暂未查询到，可能是多云。"

解释：

• 我们定义了一个普通的 Python 函数 search_weather，它接收一个字符串参数 city，并返回天气描述。

• 使用了 @tool装饰器，这会将这个函数注册为一个 LangChain 工具。

• 函数上方的 ​docstring（文档字符串）​​ 非常重要！它会被用作该工具的 ​自然语言描述，AI 会根据这个描述来决定是否调用该工具。

• 参数和返回值的类型（如 city: str和 -> str）最好也写明，有助于类型检查和工具调用系统更好地理解输入输出。

---

四、🧠 AI 如何使用这个工具？

当这个工具被添加到 ​LangChain Agent（如 ReAct Agent、OpenAI Function Calling Agent）​​ 中时，AI 可以：

1. ​理解用户问题​（比如：“上海现在天气怎么样？”）；

2. ​分析可用的工具列表，发现有一个叫 search_weather的工具，它的描述是“查询某个城市的天气情况”；

3. ​判断需要调用这个工具，并自动解析出需要传入的参数（比如 city = "上海"）；

4. ​调用该工具（即执行你定义的 search_weather("上海") 函数）​；

5. ​拿到返回结果并生成最终回复给用户。

整个过程对于开发者来说是透明的 —— 你只需要用 @tool定义好工具函数，LangChain 会帮你处理工具注册、参数解析、函数调用和结果整合。

---

五、📌 @tool 装饰器的功能特点

特性	说明
✅ ​函数标记为工具​	通过 @tool装饰器，将普通函数声明为 LangChain 可调用的工具
✅ ​自动生成工具元信息​	包括工具名称（函数名）、描述（docstring）、参数（通过类型注解和签名）
✅ ​支持类型注解​	推荐为函数参数和返回值添加类型注解（如 city: str），便于工具系统理解
✅ ​依赖函数文档（docstring）​​	AI 通过函数的 docstring 理解该工具的用途，所以写清楚很重要！
✅ ​与 Agent 无缝集成​	定义好的工具可以添加到 Agent 的工具列表中，Agent 会按需调用
✅ ​支持 Function Calling（如 OpenAI、Claude 等模型的原生工具调用能力）​​	LangChain 可以将这些工具转换为 JSON Schema，供支持 Function Calling 的 LLM 使用

---

六、🧪 更完整的例子：与 Agent 一起使用

from langchain.agents import load_tools, initialize_agent, AgentType
from langchain.llms import OpenAI
from langchain.tools import tool

# 定义一个自定义工具
@tool
def multiply(a: int, b: int) -> int:
    """返回两个数字的乘积。例如：multiply(2, 3) 返回 6"""
    return a * b

# 加载一些 LangChain 内置的工具，比如搜索引擎等（可选）
builtin_tools = load_tools(["serpapi"], llm=OpenAI())

# 把自定义工具和内置工具都传给 Agent
tools = builtin_tools + [multiply]  # multiply 是一个函数，但 @tool 让它成为了标准 Tool 对象

# 初始化一个支持工具调用的 Agent（比如 React 或 OpenAI Function Calling 方式）
agent = initialize_agent(
    tools,
    OpenAI(temperature=0),
    agent=AgentType.OPENAI_FUNCTIONS,  # 或者使用 REACT 等
    verbose=True
)

# 让 Agent 执行任务（AI 会自己决定什么时候调用 multiply 工具）
result = agent.run("请计算 12 乘以 9 是多少？")
print(result)

🔍 ​在这个例子中：​​

• 我们定义了一个 multiply工具函数，并用 @tool装饰它；

• 然后把这个工具函数与其他工具一起传给 LangChain Agent；

• 当用户问 “12 乘以 9 是多少” 时，AI 可能会决定调用 multiply(12, 9)，从而得到正确答案。

---

七、📚 补充：@tool的参数（高级用法）

在某些 LangChain 版本中，@tool装饰器还支持传入额外参数，比如显式指定工具的名称或描述，例如：

@tool("get_city_weather", description="获取指定城市的天气信息")
def get_weather(city: str) -> str:
    ...

但这种用法依赖于 LangChain 的具体版本。在大多数情况下，​工具的名称默认为函数名，描述来自函数的 docstring，非常智能和方便。

---

八、✅ 总结：LangChain 中 @tool 的核心概念

项目	说明
​是什么​	@tool是 LangChain 提供的一个装饰器，用于将普通 Python 函数定义为“工具”
​为什么用​	让 AI 模型（如 GPT、Claude 等）能够在解决问题时调用自定义的函数/能力，比如查天气、做计算、访问数据库等
​怎么用​	在函数定义前加上 @tool，并写好函数的 ​docstring（描述）​​ 和 ​类型注解​
​与谁配合​	通常与 ​LangChain Agent（如 OpenAI Function Calling、ReAct Agent）​​ 一起使用，让 AI 自主决定何时调用工具
​优势​	让你轻松扩展 AI 的能力，无需修改模型，只需定义工具函数即可

---

🙌 如果你想开始使用

1. 确保你安装了较新版本的 LangChain：

   pip install --upgrade langchain

2. 导入 tool装饰器：

   from langchain.tools import tool

3. 用 @tool装饰你希望 AI 调用的函数，并写清晰的 docstring。

4. 将工具函数添加到 LangChain Agent 中，让 AI 智能地选择何时使用它。

---

🎯 一句话总结：

​LangChain 中的 @tool 装饰器用于将 Python 函数声明为 AI 可调用的工具，让智能代理能够在解决问题时自动发现并使用这些函数，从而扩展 AI 的能力边界。​​