前言

在大模型应用的开发中，工具调用（Tool Calling） 已成为将语言模型从“能说”转变为“能做”的核心机制。它不仅让模型理解自然语言，还能调用外部函数、API 或本地脚本，实现数据查询、智能分析、知识检索以及任务执行等功能。在 LangChain 框架中，Tool 是这一机制的基础组件。

随着工具调用功能的演进，LangChain 引入了 StructuredTool，使工具的输入输出更加结构化、类型安全且可验证。其中，StructuredTool.from_function() 方法能将普通的 Python 函数快速转化为大模型可调用的结构化工具，大大简化了开发流程。

本文将全面剖析 StructuredTool.from_function() 的设计原理、使用方法与实践案例，帮助开发者熟练掌握这一关键特性。

---

1. LangChain 工具机制概述

1.1 什么是 Tool

在 LangChain 中，Tool 是模型与外部世界交互的桥梁。它封装了一个可执行函数，让大模型在生成过程中主动调用它来完成任务。通过工具调用，模型不再局限于文字输出，而是真正执行实际操作。

例如，一个典型的函数如下：

def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

若希望模型调用此函数，只需将其包装成 Tool 对象并注册到智能体（Agent）中，模型就能根据对话内容自动决定是否调用。

1.2 普通 Tool 的局限

传统的 Tool 或 Tool.from_function() 在输入处理上存在明显限制。它通常只接受单一字符串作为输入，模型需自行拼接参数，这会导致多参数函数调用困难、参数类型不明晰、缺乏输入校验，以及模型调用错误率高等问题。

当工具涉及多个参数或复杂结构输入时，这种方式显得笨拙且易出错。为此，LangChain 引入了结构化版本的工具：StructuredTool。

---

2. StructuredTool 的设计与优势

2.1 StructuredTool 简介

StructuredTool 是 Tool 的子类，其设计目标是使工具输入更加结构化和类型化。它利用 Python 的类型注解与 Pydantic 模型自动生成参数定义，让模型明确了解每个参数的名称、类型与用途。

以下表格对比了其核心特性：

特性	Tool	StructuredTool
输入格式	单字符串	JSON 或字典结构
参数解析	模型自行解析	自动由 Pydantic 校验
输入验证	无	有（类型校验、必填验证）
适用场景	简单命令	多参数或复杂输入
类型安全	低	高

这种结构化方式提升了模型调用外部函数的准确性和稳定性，也让开发者能更高效地定义复杂工具。

2.2 核心优势

StructuredTool 的优势在于自动推断参数模型，实现类型安全与校验，并与大模型（LLM）高度对齐。它支持多参数输入，并无缝集成到 Agent 中，无需额外转换。这些特性让工具调用更可靠、更自然。

---

3. from_function() 方法详解

3.1 方法概述

StructuredTool.from_function() 是 StructuredTool 的类方法，用于从普通 Python 函数自动创建结构化工具对象。其核心作用是通过读取函数签名生成参数模型，并构造一个可被 Agent 直接使用的工具。

3.2 方法签名

StructuredTool.from_function(
    func: Callable,
    name: Optional[str] = None,
    description: Optional[str] = None,
    infer_schema: bool = True,
    **kwargs
)

3.3 参数说明

参数名	类型	说明
func	Callable	需要包装的原始 Python 函数
name	str	工具名称（可选，默认使用函数名）
description	str	工具描述信息，供模型理解使用场景
infer_schema	bool	是否自动根据函数签名生成输入模型
**kwargs	任意	其他传递给 StructuredTool 的参数

3.4 内部原理

该方法的工作机制包括四个步骤：首先，使用 inspect.signature(func) 解析函数签名及其类型注解；其次，基于注解自动构建 Pydantic 模型，例如生成 InputSchema 类；然后，封装执行逻辑，接收 JSON 输入并验证后调用函数；最后，注册为结构化工具对象。

例如，对于参数 city: str 和 days: int，它会自动生成：

class InputSchema(BaseModel):
    city: str
    days: int

---

4. 实际使用示例

4.1 基本示例

from langchain.tools import StructuredTool

def get_weather(city: str, unit: str = "C") -> str:
    """查询指定城市的天气"""
    return f"The weather in {city} is 25°{unit}."

weather_tool = StructuredTool.from_function(
    func=get_weather,
    name="get_weather",
    description="获取指定城市的天气信息"
)

result = weather_tool.run({"city": "Taipei", "unit": "C"})
print(result)

输出结果：

The weather in Taipei is 25°C.

LangChain 会自动生成输入模型：

class InputSchema(BaseModel):
    city: str
    unit: str = "C"

开发者无需手动定义结构。

4.2 集成 Agent 示例

在智能体中使用该工具：

from langchain.agents import initialize_agent, AgentType
from langchain.llms import OpenAI

llm = OpenAI(temperature=0)
tools = [weather_tool]

agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

agent.run("请帮我查询台北现在的天气是多少度？")

模型会自动识别并调用 get_weather，生成结构化输入如 {"city": "台北", "unit": "C"}，结果则传回模型上下文。

---

5. 与 Tool.from_function() 的区别

StructuredTool.from_function() 是 Tool.from_function() 的增强版。以下表格总结了二者的差异：

对比项	Tool.from_function()	StructuredTool.from_function()
输入格式	单字符串	JSON/字典
参数类型	未定义	自动推断
输入验证	无	有（Pydantic）
适合场景	简单文本输入	多参数结构化输入
调用可靠性	一般	高

例如，普通 Tool 需模型自行处理字符串，而结构化版本能自动识别参数含义，提升准确率。

---

6. 实战扩展示例：多参数与校验

以下示例展示其高级特性：

from datetime import date
from enum import Enum
from langchain.tools import StructuredTool
from pydantic import BaseModel, Field

class UnitEnum(str, Enum):
    CELSIUS = "C"
    FAHRENHEIT = "F"

def weather_forecast(city: str, date_: date, unit: UnitEnum = UnitEnum.CELSIUS) -> str:
    """根据城市与日期获取天气预报"""
    return f"{date_} {city} will be around 26°{unit.value}."

forecast_tool = StructuredTool.from_function(
    func=weather_forecast,
    name="weather_forecast",
    description="获取指定城市某天的天气预报"
)

print(forecast_tool.run({
    "city": "Taipei",
    "date_": "2025-10-26",
    "unit": "F"
}))

执行结果：

2025-10-26 Taipei will be around 26°F.

此例中，参数类型（如字符串、日期、枚举）自动识别，Pydantic 进行校验，大模型无需解析复杂结构。这体现了结构化工具的核心价值：开发者只需编写函数，模型即可安全调用。

---

7. 最佳实践与建议

在使用中，确保函数参数带有明确类型注解，并添加文档字符串以生成工具描述。同时，为工具提供命名与描述，帮助模型判断使用时机。避免复杂嵌套结构，保持输入清晰，并在集成 Agent 前独立测试工具功能。这些实践能最大化其效能。

---

8. 结语

StructuredTool.from_function() 是 LangChain 工具体系的重要升级。它让开发者以自然方式定义函数，并赋予大模型结构化、可靠的调用能力。相较传统字符串输入，它提供更强的类型安全、更高的准确率，以及更流畅的开发体验。

在构建复杂 AI 应用时，无论知识问答、数据检索、API 调用还是任务执行，这一特性都能成为核心利器。通过它，开发者能让大模型展现更强的执行力和交互能力，提升智能体应用的整体水平。

一句话总结：

“让函数说话，让模型行动。”——这正是 StructuredTool.from_function() 赋予 LangChain 的力量。