469 lines
16 KiB
Plaintext
469 lines
16 KiB
Plaintext
{
|
||
"cells": [
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"# 10 工具调用\n",
|
||
"\n",
|
||
"## 学习目标\n",
|
||
"1. 理解工具调用（Tool Calling）的基本机制和流程\n",
|
||
"2. 掌握手动解析模型返回的工具调用请求\n",
|
||
"3. 学会使用 `bind_tools` 让模型选择工具\n",
|
||
"4. 掌握 `create_tool_calling_agent` 和 `AgentExecutor` 构建智能体\n",
|
||
"5. 能够处理工具调用中的常见错误"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 1. 工具调用的基本流程\n",
|
||
"\n",
|
||
"工具调用不是由模型直接执行代码，而是模型「决定」要调用哪个工具、传什么参数，然后由程序代为执行。\n",
|
||
"\n",
|
||
"完整流程如下：\n",
|
||
"\n",
|
||
"```\n",
|
||
"用户提问 -> 模型分析 -> 输出工具调用请求 -> 程序执行工具 -> 结果返回模型 -> 模型生成最终回答\n",
|
||
"```\n",
|
||
"\n",
|
||
"模型输出的是结构化的调用请求，包含：\n",
|
||
"- 工具名称（name）\n",
|
||
"- 工具参数（arguments）\n",
|
||
"\n",
|
||
"程序根据请求执行对应函数，再把结果返回给模型。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 2. 准备工具集\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 multiply(a: float, b: float) -> float:\n",
|
||
" \"\"\"计算两个数的乘积。\"\"\"\n",
|
||
" return a * b\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def query_weather(city: str) -> str:\n",
|
||
" \"\"\"\n",
|
||
" 查询指定城市的天气。\n",
|
||
" 参数：\n",
|
||
" city: 城市名称，如北京、上海\n",
|
||
" \"\"\"\n",
|
||
" weather_db = {'北京': '晴 25°C', '上海': '多云 28°C', '广州': '小雨 30°C'}\n",
|
||
" return weather_db.get(city, f'未找到 {city} 的天气信息')\n",
|
||
"\n",
|
||
"tools = [add, multiply, query_weather]\n",
|
||
"\n",
|
||
"for t in tools:\n",
|
||
" print(f'工具：{t.name}，描述：{t.description}')"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 3. 手动执行工具调用\n",
|
||
"\n",
|
||
"在使用智能体之前，先手动走一遍工具调用流程，理解底层机制。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain_openai import ChatOpenAI\n",
|
||
"from langchain_core.messages import HumanMessage\n",
|
||
"from dotenv import load_dotenv\n",
|
||
"\n",
|
||
"load_dotenv()\n",
|
||
"\n",
|
||
"\n",
|
||
"llm = ChatOpenAI(model='qwen3.6-35b-A3b', temperature=0.1)\n",
|
||
"\n",
|
||
"# 把工具绑定到模型上\n",
|
||
"llm_with_tools = llm.bind_tools(tools)\n",
|
||
"\n",
|
||
"# 用户提问\n",
|
||
"question = '北京和上海的气温相差多少度？'\n",
|
||
"messages = [HumanMessage(content=question)]\n",
|
||
"\n",
|
||
"# 模型输出，可能包含工具调用请求\n",
|
||
"response = llm_with_tools.invoke(messages)\n",
|
||
"\n",
|
||
"print('模型回复类型：', type(response))\n",
|
||
"print('工具调用请求：', response.tool_calls)\n",
|
||
"print('文本内容：', response.content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `llm.bind_tools(tools)`：把工具列表绑定到模型上\n",
|
||
"- 模型看到问题后，如果觉得需要工具，会在 `response.tool_calls` 中返回调用请求\n",
|
||
"- 每个 `tool_call` 包含 `name`（工具名）和 `args`（参数）\n",
|
||
"- 如果不需要工具，`response.content` 中直接包含文本回答"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 4. 手动解析并执行工具调用\n",
|
||
"\n",
|
||
"模型只负责「决定」调用什么工具，真正的执行需要程序完成。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain_openai import ChatOpenAI\n",
|
||
"from langchain_core.messages import HumanMessage, ToolMessage\n",
|
||
"\n",
|
||
"llm = ChatOpenAI(model='qwen3.6-35b-A3b', temperature=0.1)\n",
|
||
"llm_with_tools = llm.bind_tools(tools)\n",
|
||
"\n",
|
||
"# 使用一个只需一次工具调用的简单问题\n",
|
||
"question = '北京今天的天气怎么样？'\n",
|
||
"messages = [HumanMessage(content=question)]\n",
|
||
"\n",
|
||
"# 第一步：获取模型的工具调用请求\n",
|
||
"response = llm_with_tools.invoke(messages)\n",
|
||
"messages.append(response)\n",
|
||
"\n",
|
||
"print('第一次模型输出：')\n",
|
||
"print('tool_calls:', response.tool_calls)\n",
|
||
"print('content:', response.content)\n",
|
||
"\n",
|
||
"# 第二步：执行工具调用\n",
|
||
"for tool_call in response.tool_calls:\n",
|
||
" tool_name = tool_call['name']\n",
|
||
" tool_args = tool_call['args']\n",
|
||
" \n",
|
||
" # 找到对应的工具并执行\n",
|
||
" selected_tool = {t.name: t for t in tools}[tool_name]\n",
|
||
" tool_result = selected_tool.invoke(tool_args)\n",
|
||
" \n",
|
||
" # 把工具执行结果加入对话历史\n",
|
||
" messages.append(ToolMessage(content=str(tool_result), tool_call_id=tool_call['id']))\n",
|
||
" \n",
|
||
" print(f'\\n执行工具：{tool_name}，参数：{tool_args}，结果：{tool_result}')\n",
|
||
"\n",
|
||
"# 第三步：把工具结果返回模型，生成最终回答\n",
|
||
"final_response = llm_with_tools.invoke(messages)\n",
|
||
"print('\\n最终回答：', final_response.content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `ToolMessage`：专门用于承载工具执行结果的消息类型\n",
|
||
"- `tool_call_id`：必须和模型请求的 `id` 对应，这是 LangChain 的要求\n",
|
||
"- 工具执行后，需要把结果追加到 `messages` 中，再次调用模型\n",
|
||
"- 这种手动流程帮助我们理解智能体的底层工作原理"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 5. 使用 create_agent 构建智能体\n",
|
||
"\n",
|
||
"LangChain 1.x 推荐使用 `create_agent` 构建工具调用智能体。它会自动处理「模型决定调用工具 -> 执行工具 -> 返回结果 -> 再次调用模型」的循环，并返回一个可执行的状态图。\n",
|
||
"\n",
|
||
"`create_agent` 的核心参数：\n",
|
||
"\n",
|
||
"| 参数 | 说明 |\n",
|
||
"| --- | --- |\n",
|
||
"| `model` | 语言模型实例 |\n",
|
||
"| `tools` | 工具列表 |\n",
|
||
"| `system_prompt` | 系统提示词 |\n",
|
||
"| `checkpointer` | 可选，用于保存对话历史 |"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain_openai import ChatOpenAI\n",
|
||
"from langchain.agents import create_agent\n",
|
||
"\n",
|
||
"llm = ChatOpenAI(model='qwen3.6-35b-A3b', temperature=0.1)\n",
|
||
"\n",
|
||
"# 创建工具调用智能体\n",
|
||
"# create_agent 是 LangChain 1.x 推荐的智能体构建方式，返回一个可执行的状态图\n",
|
||
"agent = create_agent(\n",
|
||
" model=llm,\n",
|
||
" tools=tools,\n",
|
||
" system_prompt='你是一个 helpful 的数学和天气助手，可以使用工具帮助用户。'\n",
|
||
")\n",
|
||
"\n",
|
||
"# 运行智能体\n",
|
||
"result = agent.invoke({'messages': [('user', '3 加 5 乘以 2 等于多少？')]})\n",
|
||
"print('\\n最终输出：', result['messages'][-1].content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `create_agent(model=llm, tools=tools, system_prompt='...')`：创建工具调用智能体\n",
|
||
"- `create_agent` 会自动处理工具调用循环：模型选择工具 -> 执行工具 -> 返回结果 -> 再次调用模型\n",
|
||
"- 返回的 `agent` 是一个 LangGraph 编译后的状态图（CompiledStateGraph），可以直接调用 `invoke`\n",
|
||
"- 调用时传入 `{'messages': [('user', '...')]}`，表示用户消息\n",
|
||
"- `result['messages'][-1].content`：获取最后一条消息，即智能体的最终回答"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 6. 观察智能体的执行过程\n",
|
||
"\n",
|
||
"`create_agent` 返回的是一个 LangGraph 状态图。运行后，`result['messages']` 会包含完整的对话历史，包括模型的思考过程、工具调用请求、工具执行结果和最终回答。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"# 同样的智能体，换个问题运行\n",
|
||
"result = agent.invoke({'messages': [('user', '北京今天天气怎么样？广州呢？')]})\n",
|
||
"for i in result['messages']:\n",
|
||
" print(i)\n",
|
||
"print('\\n最终输出：', result['messages'][-1].content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 7. 多轮对话：带记忆的智能体\n",
|
||
"\n",
|
||
"如果希望智能体能记住上下文，可以在 `create_agent` 中传入 `checkpointer`。这里使用 `MemorySaver` 作为内存型的 checkpointer。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langgraph.checkpoint.memory import MemorySaver\n",
|
||
"\n",
|
||
"# 创建带记忆的智能体\n",
|
||
"# checkpointer 会自动保存和加载对话历史\n",
|
||
"memory = MemorySaver()\n",
|
||
"agent_with_history = create_agent(\n",
|
||
" model=llm,\n",
|
||
" tools=tools,\n",
|
||
" system_prompt='你是一个 helpful 的数学和天气助手，可以使用工具帮助用户。',\n",
|
||
" checkpointer=memory\n",
|
||
")\n",
|
||
"\n",
|
||
"# 第一轮对话\n",
|
||
"config = {'configurable': {'thread_id': 'user_001'}}\n",
|
||
"result1 = agent_with_history.invoke(\n",
|
||
" {'messages': [('user', '我叫张三')]},\n",
|
||
" config=config\n",
|
||
")\n",
|
||
"print('第一轮：', result1['messages'][-1].content)\n",
|
||
"\n",
|
||
"# 第二轮对话，测试是否记得名字\n",
|
||
"result2 = agent_with_history.invoke(\n",
|
||
" {'messages': [('user', '我叫什么名字？')]},\n",
|
||
" config=config\n",
|
||
")\n",
|
||
"print('第二轮：', result2['messages'][-1].content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- `MemorySaver()`：内存型 checkpointer，用于保存对话历史\n",
|
||
"- `checkpointer=memory`：把 checkpointer 传给 `create_agent`，让智能体具备记忆能力\n",
|
||
"- `config={'configurable': {'thread_id': 'user_001'}}`：通过 thread_id 区分不同会话\n",
|
||
"- 同一个 `thread_id` 下的历史消息会被保留并传给模型"
|
||
]
|
||
},
|
||
{
|
||
"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 safe_divide(a: float, b: float) -> str:\n",
|
||
" \"\"\"安全除法，除数为0时返回友好提示。\"\"\"\n",
|
||
" try:\n",
|
||
" if b == 0:\n",
|
||
" return '错误：除数不能为0'\n",
|
||
" return str(a / b)\n",
|
||
" except Exception as e:\n",
|
||
" return f'计算出错：{str(e)}'\n",
|
||
"\n",
|
||
"safe_tools = [safe_divide, add, multiply]\n",
|
||
"\n",
|
||
"safe_agent = create_agent(\n",
|
||
" model=llm,\n",
|
||
" tools=safe_tools,\n",
|
||
" system_prompt='你是一个 helpful 的数学助手，可以使用工具帮助用户。'\n",
|
||
")\n",
|
||
"\n",
|
||
"result = safe_agent.invoke({'messages': [('user', '10 除以 0 等于多少？')]})\n",
|
||
"print('\\n最终输出：', result['messages'][-1].content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"### 代码解释\n",
|
||
"\n",
|
||
"- 工具内部用 try-except 捕获异常，返回错误信息而不是抛出异常\n",
|
||
"- 这样模型能看到错误原因，并据此调整或告知用户\n",
|
||
"- 不要把异常直接抛给 AgentExecutor，否则会导致智能体运行中断"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 9. 完整示例：智能客服助手\n",
|
||
"\n",
|
||
"下面把工具调用应用到智能客服场景：根据用户问题查询订单、库存或计算退款金额。"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "code",
|
||
"execution_count": null,
|
||
"metadata": {},
|
||
"outputs": [],
|
||
"source": [
|
||
"from langchain.tools import tool\n",
|
||
"from langchain_openai import ChatOpenAI\n",
|
||
"from langchain.agents import create_agent\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def query_order(order_id: str) -> str:\n",
|
||
" \"\"\"根据订单号查询订单信息。\"\"\"\n",
|
||
" orders = {\n",
|
||
" '1001': '已发货，预计明天送达',\n",
|
||
" '1002': '已签收',\n",
|
||
" '1003': '处理中'\n",
|
||
" }\n",
|
||
" return orders.get(order_id, '未找到该订单')\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def query_stock(product_name: str) -> str:\n",
|
||
" \"\"\"查询商品库存。\"\"\"\n",
|
||
" stock = {'手机': 100, '耳机': 50, '充电器': 200}\n",
|
||
" return f'{product_name} 库存：{stock.get(product_name, 0)} 件'\n",
|
||
"\n",
|
||
"@tool\n",
|
||
"def calculate_refund(price: float, days: int) -> str:\n",
|
||
" \"\"\"计算退款金额，每天折旧 1%。\"\"\"\n",
|
||
" refund = price * max(0, 1 - days * 0.01)\n",
|
||
" return f'预计退款金额：{refund:.2f} 元'\n",
|
||
"\n",
|
||
"cs_tools = [query_order, query_stock, calculate_refund]\n",
|
||
"\n",
|
||
"cs_agent = create_agent(\n",
|
||
" model=llm,\n",
|
||
" tools=cs_tools,\n",
|
||
" system_prompt='你是电商客服助手，可以通过工具查询订单、库存和计算退款。'\n",
|
||
")\n",
|
||
"\n",
|
||
"cs_result = cs_agent.invoke({\n",
|
||
" 'messages': [('user', '我的订单 1001 现在状态怎样？手机还有库存吗？如果手机 3000 元买了 10 天，退款多少？')]\n",
|
||
"})\n",
|
||
"print('\\n最终输出：', cs_result['messages'][-1].content)"
|
||
]
|
||
},
|
||
{
|
||
"cell_type": "markdown",
|
||
"metadata": {},
|
||
"source": [
|
||
"## 10. 本节课练习\n",
|
||
"\n",
|
||
"1. 手动执行一次工具调用：让模型选择 `add` 或 `multiply`，然后自己解析 `tool_calls` 并执行\n",
|
||
"2. 使用 `create_tool_calling_agent` 和 `AgentExecutor` 构建一个能计算 BMI 的工具智能体\n",
|
||
"3. 给智能体添加 `verbose=True`，观察它执行工具调用的完整过程\n",
|
||
"4. 修改一个工具，让它在参数错误时返回友好提示，而不是抛出异常\n",
|
||
"5. 使用 `RunnableWithMessageHistory` 让智能体记住用户的连续提问"
|
||
]
|
||
}
|
||
],
|
||
"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.11.3"
|
||
}
|
||
},
|
||
"nbformat": 4,
|
||
"nbformat_minor": 4
|
||
}
|