471 lines
15 KiB
Plaintext
471 lines
15 KiB
Plaintext
{
|
||
"cells": [
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"# 09 工具定义\n",
|
||
"\n",
|
||
"## 学习目标\n",
|
||
"1. 理解工具（Tools）在智能体开发中的核心作用\n",
|
||
"2. 掌握使用 `@tool` 装饰器定义自定义工具\n",
|
||
"3. 学会为工具编写清晰的参数说明和文档字符串\n",
|
||
"4. 理解工具描述如何影响模型选择工具的能力\n",
|
||
"5. 能够定义计算类、查询类和文件处理类工具"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 1. 为什么需要工具\n",
|
||
"\n",
|
||
"大语言模型本身只能处理文本，它的知识截止于训练数据，也无法直接访问外部世界。\n",
|
||
"\n",
|
||
"**工具（Tools）** 让模型能够：\n",
|
||
"\n",
|
||
"- 执行数学计算（模型不擅长精确计算）\n",
|
||
"- 查询数据库、API、搜索引擎\n",
|
||
"- 读写文件、操作数据库\n",
|
||
"- 获取实时信息（天气、股价、新闻）\n",
|
||
"\n",
|
||
"智能体（Agent）的核心工作就是：**根据用户问题选择合适的工具，调用工具，再根据结果回答问题**。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 2. 使用 @tool 装饰器定义第一个工具\n",
|
||
"\n",
|
||
"LangChain 提供了 `@tool` 装饰器，可以把一个普通 Python 函数变成智能体可调用的工具。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"# 使用 @tool 装饰器定义一个加法工具\n",
|
||
"@tool\n",
|
||
"def add(a: int, b: int) -> int:\n",
|
||
" \"\"\"计算两个整数的和。\"\"\"\n",
|
||
" return a + b\n",
|
||
"\n",
|
||
"# 查看工具信息\n",
|
||
"print('工具名称：', add.name)\n",
|
||
"print('工具描述：', add.description)\n",
|
||
"print('参数Schema：', add.args)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `@tool`：把 `add` 函数注册为 LangChain 工具\n",
|
||
"- `a: int, b: int`：参数类型会被自动解析为工具的输入参数格式\n",
|
||
"- 函数文档字符串 `\"\"\"...\"\"\"`：会被自动提取为工具描述（description）\n",
|
||
"- `add.name`：工具名，默认使用函数名\n",
|
||
"- `add.description`：工具描述，来自函数的 docstring\n",
|
||
"- `add.args`：参数的 JSON Schema，模型根据它决定如何传参"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 3. 手动调用工具\n",
|
||
"\n",
|
||
"工具定义好后，可以通过 `invoke` 方法或 `run` 方法调用。\n",
|
||
"\n",
|
||
"注意：`@tool` 装饰后的对象是一个 `StructuredTool` 对象，**不能直接像普通函数那样加括号调用**（如 `multiply(3, 4)`），需要传入字典参数。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def multiply(a: int, b: int) -> int:\n",
|
||
" \"\"\"计算两个整数的乘积。\"\"\"\n",
|
||
" return a * b\n",
|
||
"\n",
|
||
"# 通过 invoke 调用，传入字典参数\n",
|
||
"print('invoke 调用：', multiply.invoke({'a': 3, 'b': 4}))\n",
|
||
"\n",
|
||
"# 通过 run 调用（LangChain 工具的传统调用方式）\n",
|
||
"print('run 调用：', multiply.run({'a': 5, 'b': 6}))"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `@tool` 装饰后的对象是一个 `StructuredTool`，不是普通函数\n",
|
||
"- `multiply.invoke({'a': 3, 'b': 4})`：LangChain 风格调用，智能体实际使用这种方式\n",
|
||
"- `multiply.run({'a': 5, 'b': 6})`：传统工具调用方式，与 `invoke` 效果相同\n",
|
||
"- 注意：不能写成 `multiply(3, 4)`，否则会报 `StructuredTool object is not callable`"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 4. 自定义工具名称和描述\n",
|
||
"\n",
|
||
"默认情况下，工具名就是函数名，描述来自 docstring。你也可以通过 `@tool` 参数自定义。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool('weather-query', description='查询指定城市的当前天气情况')\n",
|
||
"def get_weather(city: str) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 查询天气。\n",
|
||
" 参数：\n",
|
||
" city: 城市名称，例如 \"北京\"、\"上海\"\n",
|
||
" \"\"\"\n",
|
||
" # 这里用模拟数据，实际可接入天气 API\n",
|
||
" weather_data = {\n",
|
||
" '北京': '晴，25°C',\n",
|
||
" '上海': '多云，28°C',\n",
|
||
" '广州': '小雨，30°C'\n",
|
||
" }\n",
|
||
" return weather_data.get(city, f'未找到 {city} 的天气信息')\n",
|
||
"\n",
|
||
"print('工具名称：', get_weather.name)\n",
|
||
"print('工具描述：', get_weather.description)\n",
|
||
"print('调用结果：', get_weather.invoke({'city': '北京'}))"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `@tool('weather-query', description='...')`：自定义工具名和描述\n",
|
||
"- 工具描述非常重要，模型主要依赖它判断什么时候使用该工具\n",
|
||
"- 描述要清晰、具体，包含「工具能做什么」和「参数含义」\n",
|
||
"- 函数 docstring 可以继续补充参数细节"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 5. 定义带多个参数的工具\n",
|
||
"\n",
|
||
"工具可以有多个参数，LangChain 会自动根据类型注解生成参数 Schema。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def calculate_bmi(height: float, weight: float) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 根据身高和体重计算 BMI 指数，并返回健康建议。\n",
|
||
" 参数：\n",
|
||
" height: 身高，单位米\n",
|
||
" weight: 体重，单位千克\n",
|
||
" \"\"\"\n",
|
||
" bmi = weight / (height ** 2)\n",
|
||
" if bmi < 18.5:\n",
|
||
" suggestion = '体重过轻，建议加强营养'\n",
|
||
" elif bmi < 24:\n",
|
||
" suggestion = '体重正常，请保持'\n",
|
||
" elif bmi < 28:\n",
|
||
" suggestion = '超重，建议适当运动'\n",
|
||
" else:\n",
|
||
" suggestion = '肥胖，建议咨询医生'\n",
|
||
" return f'BMI: {bmi:.2f}，{suggestion}'\n",
|
||
"\n",
|
||
"print(calculate_bmi.invoke({'height': 1.75, 'weight': 70}))\n",
|
||
"print('\\n参数 Schema：')\n",
|
||
"print(calculate_bmi.args)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `height: float, weight: float`：类型注解会被 LangChain 自动识别\n",
|
||
"- 生成的 `args` 中会包含参数名、类型、是否必填等信息\n",
|
||
"- 模型会根据这个 Schema 构造正确的 JSON 参数调用工具"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 6. 定义模拟 API 查询工具\n",
|
||
"\n",
|
||
"实际应用中，工具通常会调用外部 API。下面我们用一个模拟的「产品库存查询」工具来演示。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def query_product_stock(product_name: str) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 查询指定商品的库存数量。\n",
|
||
" 参数：\n",
|
||
" product_name: 商品名称\n",
|
||
" \"\"\"\n",
|
||
" # 模拟数据库查询\n",
|
||
" stock_db = {\n",
|
||
" '手机': 150,\n",
|
||
" '笔记本电脑': 45,\n",
|
||
" '耳机': 200,\n",
|
||
" '充电宝': 80\n",
|
||
" }\n",
|
||
" stock = stock_db.get(product_name)\n",
|
||
" if stock is None:\n",
|
||
" return f'未找到商品 \"{product_name}\" 的库存信息'\n",
|
||
" return f'商品 \"{product_name}\" 当前库存：{stock} 件'\n",
|
||
"\n",
|
||
"# 测试工具\n",
|
||
"print(query_product_stock.invoke({'product_name': '手机'}))\n",
|
||
"print(query_product_stock.invoke({'product_name': '相机'}))"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- 这个工具模拟了查询数据库或 API 的场景\n",
|
||
"- 返回的字符串会作为观察结果（Observation）交给模型继续处理\n",
|
||
"- 工具内部可以替换为真实的数据库查询、HTTP 请求等"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 7. 定义文件处理工具\n",
|
||
"\n",
|
||
"工具也可以读写文件。下面是读取文本文件和写入文本文件的工具示例。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def read_text_file(file_path: str) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 读取指定文本文件的内容。\n",
|
||
" 参数：\n",
|
||
" file_path: 文件路径\n",
|
||
" \"\"\"\n",
|
||
" try:\n",
|
||
" with open(file_path, 'r', encoding='utf-8') as f:\n",
|
||
" return f.read()\n",
|
||
" except FileNotFoundError:\n",
|
||
" return f'文件不存在：{file_path}'\n",
|
||
" except Exception as e:\n",
|
||
" return f'读取失败：{str(e)}'\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def write_text_file(file_path: str, content: str) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 将内容写入指定文本文件。\n",
|
||
" 参数：\n",
|
||
" file_path: 文件路径\n",
|
||
" content: 要写入的内容\n",
|
||
" \"\"\"\n",
|
||
" try:\n",
|
||
" with open(file_path, 'w', encoding='utf-8') as f:\n",
|
||
" f.write(content)\n",
|
||
" return f'已成功写入文件：{file_path}'\n",
|
||
" except Exception as e:\n",
|
||
" return f'写入失败：{str(e)}'\n",
|
||
"\n",
|
||
"# 测试写入和读取\n",
|
||
"write_text_file.invoke({'file_path': 'test_note.txt', 'content': '这是测试内容'})\n",
|
||
"print(read_text_file.invoke({'file_path': 'test_note.txt'}))"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `read_text_file`：读取指定文件内容\n",
|
||
"- `write_text_file`：把字符串写入指定文件\n",
|
||
"- 文件路径使用相对路径时，会以当前工作目录为基准\n",
|
||
"- 工具内部要做好异常处理，避免程序崩溃"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 8. 工具列表与工具选择\n",
|
||
"\n",
|
||
"在构建智能体时，通常会把多个工具放在一个列表里，交给模型选择使用。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def add(a: int, b: int) -> int:\n",
|
||
" \"\"\"计算两个整数的和。\"\"\"\n",
|
||
" return a + b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def multiply(a: int, b: int) -> int:\n",
|
||
" \"\"\"计算两个整数的乘积。\"\"\"\n",
|
||
" return a * b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def power(base: int, exponent: int) -> int:\n",
|
||
" \"\"\"计算 base 的 exponent 次方。\"\"\"\n",
|
||
" return base ** exponent\n",
|
||
"\n",
|
||
"# 把工具放入列表\n",
|
||
"tools = [add, multiply, power]\n",
|
||
"\n",
|
||
"# 查看工具列表信息\n",
|
||
"for t in tools:\n",
|
||
" print(f'名称：{t.name}，描述：{t.description}')"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- 智能体通过工具列表了解有哪些工具可用\n",
|
||
"- 模型会根据用户问题和工具描述，决定调用哪个工具、传什么参数\n",
|
||
"- 工具名称和描述的清晰度直接影响模型选择工具的准确率"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 9. 完整示例：多功能计算器工具集\n",
|
||
"\n",
|
||
"下面把多个数学工具组合成一个工具集，模拟智能体可使用的工具环境。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def add(a: float, b: float) -> float:\n",
|
||
" \"\"\"计算两个数的和。\"\"\"\n",
|
||
" return a + b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def subtract(a: float, b: float) -> float:\n",
|
||
" \"\"\"计算两个数的差。\"\"\"\n",
|
||
" return a - b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def multiply(a: float, b: float) -> float:\n",
|
||
" \"\"\"计算两个数的乘积。\"\"\"\n",
|
||
" return a * b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def divide(a: float, b: float) -> float:\n",
|
||
" \"\"\"计算两个数的商，如果除数为0则返回错误信息。\"\"\"\n",
|
||
" if b == 0:\n",
|
||
" return '错误：除数不能为0'\n",
|
||
" return a / b\n",
|
||
"\n",
|
||
"math_tools = [add, subtract, multiply, divide]\n",
|
||
"\n",
|
||
"# 测试每个工具\n",
|
||
"for t in math_tools:\n",
|
||
" print(f'{t.name}: {t.description}')"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 10. 本节课练习\n",
|
||
"\n",
|
||
"1. 使用 `@tool` 定义一个摄氏度转华氏度的工具，参数和返回值都使用 float 类型\n",
|
||
"2. 定义一个「查询课程信息」工具，用字典模拟数据库，根据课程名返回上课时间\n",
|
||
"3. 定义一个「写入学习笔记」工具，接收文件名和内容，把内容写入指定文件\n",
|
||
"4. 把上面三个工具放入一个列表，打印每个工具的名称、描述和参数 Schema\n",
|
||
"5. 尝试修改一个工具的描述，观察参数 Schema 是否会变化"
|
||
]
|
||
}
|
||
],
|
||
"metadata": {
|
||
"kernelspec": {
|
||
"display_name": ".venv",
|
||
"language": "python",
|
||
"name": "python3"
|
||
},
|
||
"language_info": {
|
||
"codemirror_mode": {
|
||
"name": "ipython",
|
||
"version": 3
|
||
},
|
||
"file_extension": ".py",
|
||
"mimetype": "text/x-python",
|
||
"name": "python",
|
||
"nbconvert_exporter": "python",
|
||
"pygments_lexer": "ipython3",
|
||
"version": "3.14.4"
|
||
}
|
||
},
|
||
"nbformat": 4,
|
||
"nbformat_minor": 4
|
||
}
|