🎯 课程主题

使用 args_schema 参数替代 docstring 中的 :param 风格来定义 @tool 装饰器工具的参数模式，包括 Pydantic BaseModel 和 JSON Schema 两种方式。

📝 核心知识点

1. 使用 Pydantic BaseModel 定义 args_schema

  • 概念说明：通过继承 BaseModel 定义子类，在子类中声明属性（字段），然后将该类赋给 @tool 装饰器的 args_schema 参数，替代传统的 docstring :param 声明。
  • 关键细节：
    • 字段类型以 Pydantic 模型中声明的类型为准，而非函数形参的类型注解。
    • 使用 Field(description="...") 为字段添加描述信息。
    • 使用 Field(default="北京") 设置字段默认值。
    • 使用 Literal["celsius", "fahrenheit"] 限定字段只能从固定选项中取值（类似枚举效果），需从 typing 导入。

2. 使用 JSON Schema 字典定义 args_schema

  • 概念说明：直接将 JSON Schema 字典赋值给 args_schema，适用于需要运行时动态生成参数模式的场景（如参数结构依赖数据库配置或用户输入）。
  • 关键细节：
    • JSON Schema 需包含 type、properties、required 等标准字段。
    • 相比 Pydantic 方式更灵活，但编写时需小心字段格式，写错会导致匹配失败。
    • 适用场景：参数结构需要动态变化、不固定的情况。

3. Pydantic vs JSON Schema 选择建议

  • 确定性场景（参数结构固定）：使用 Pydantic BaseModel，代码清晰、类型安全。
  • 灵活性场景（运行时动态生成参数）：使用 JSON Schema 字典。

🏗️ 架构与工作流

  1. 定义工具函数，使用 @tool 装饰器。
  2. 创建 Pydantic 模型类（继承 BaseModel），声明工具参数字段，可选配 Field 添加描述、默认值、取值限制。
  3. 在装饰器中通过 args_schema=WeatherInput 绑定模型。
  4. 绑定工具后调用模型，模型可正确识别参数的类型、描述和约束。

💻 代码实战

from langchain_core.tools import tool
from pydantic import BaseModel, Field
from typing import Literal

# ==================== 方式一：Pydantic BaseModel ====================

class WeatherInput(BaseModel):
    """天气查询参数"""
    city: str = Field(description="具体的城市名称", default="北京")
    unit: Literal["celsius", "fahrenheit"] = Field(description="温度单位")
    forecast: bool = Field(description="是否包含未来五天天气预报", default=False)

@tool(args_schema=WeatherInput)
def get_weather(city: str, unit: str, forecast: bool) -> str:
    """查询指定城市的天气信息。"""
    return f"{city}今天天气不错，温度25度（{unit}），预测={forecast}"

# 查看工具对应的 OpenAI 格式
print(get_weather.tool_call_schema)

# ==================== 方式二：JSON Schema 字典 ====================

json_schema = {
    "type": "object",
    "properties": {
        "city": {"type": "string", "description": "城市名称"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        "forecast": {"type": "boolean", "default": False}
    },
    "required": ["city"]
}

@tool(args_schema=json_schema)
def get_weather_json(city: str, unit: str = "celsius", forecast: bool = False) -> str:
    """查询天气（JSON Schema 方式）。"""
    return f"{city}天气：晴，25{unit}，预报={forecast}"

⚠️ 常见问题与避坑指南

  • 如果函数形参没有类型注解且未提供 args_schema，@tool 装饰器会报错（因为它会尝试按 Google 风格 docstring 解析参数）。
  • 当 args_schema 中的字段类型与函数形参类型注解不一致时，以 args_schema 中的类型为准。
  • JSON Schema 方式需严格遵循标准格式（properties、required、type），写错会导致参数匹配失败。

💡 个人总结与延伸

本课介绍了使用 args_schema 的两种方式，推荐在固定参数场景下使用 Pydantic BaseModel（类型安全、IDE 友好），在需要运行时动态生成参数结构时使用 JSON Schema。这是 LangChain 工具定义从"文档字符串驱动"向"模型驱动"升级的关键一步，与后续 Agent 自动调用工具紧密相关。

最近更新:
Contributors: yangwenguang