大模型能聊天、能写诗——但让它查数据库，它开始编数据。让它发邮件，它只能说"您可以这样发"。
不是模型不行。LLM 天生只有嘴没有手——它能生成文本，但不会调 API、不会查数据库、不会操作文件。
核心认知：Tools 就是给 LLM 装上的"手"。
读完这篇文章，你会：
- 理解 Tool 的三个核心组成（签名、描述、实现）
- 用
@tool装饰器 3 行代码创建一个工具 - 通过
create_agent让 LLM 自动调用你的工具 - 动手写出一个能保存和搜索笔记的完整工具
预计阅读 6 分钟，全程代码可运行。
一、Tools 到底是什么？
一句话：Tool 是一个带类型注解和 docstring 的普通 Python 函数。LLM 根据对话内容判断什么时候调用它。
每个 Tool 由三个角色组成：
| 角色 | 代码 | LLM 用它做什么 |
|---|---|---|
| 函数签名 | 类型注解city: str | 知道该传什么参数 |
| docstring | 函数文档字符串 | 判断"这工具能不能解决用户问题" |
| 函数体 | 实际逻辑 | LLM 不关心，它只管收返回值 |
关键认知：LLM 不执行你的函数。它只生成一个 JSON 调用指令
{name: "get_weather", args: {city: "北京"}}，真正执行的是 LangGraph 的 ToolNode。模型拿到的永远是执行结果，不是执行过程。
什么时候用 Tool？
| 场景 | 用 Tool？ | 原因 |
|---|---|---|
| 查天气、读数据库、调 API | 用 | 模型记忆里没有这些数据 |
| 复杂公式计算、日期运算 | 用 | 模型算不准，Tool 精确可靠 |
| 发邮件、写数据库 | 用 | 有副作用，需要实际执行 |
| 翻译、润色、总结 | 不用 | 纯文本任务，模型自己就能做 |
二、创建 Tool：90% 的情况一个装饰器够了
LangChain 提供四种创建方式，但@tool装饰器覆盖日常开发 90% 的场景：
from langchain.tools import tool @tool def get_weather(city: str) -> str: """查询指定城市的实时天气。 Args: city: 城市名称，如 '北京' """ weather_data = {"北京": "32°C，晴", "上海": "28°C，小雨"} return weather_data.get(city, "未找到该城市数据")三步搞定：加
@tool→ 写类型注解 → 写 docstring。类型注解告诉 LLM “该传什么参数”，docstring 告诉 LLM “这个工具能干什么”。
参数复杂时，用 Pydantic 的args_schema精确约束：
from pydantic import BaseModel, Field class WeatherInput(BaseModel): """天气查询参数""" location: str = Field(description="城市名称") units: str = Field(default="celsius", description="温度单位") @tool(args_schema=WeatherInput) def get_weather(location: str, units: str = "celsius") -> str: """查询指定城市的实时天气。""" return f"{location}：22°C，晴"提示：简单参数用类型注解就够了。参数超过 3 个或带枚举值、范围限制等复杂约束时，再上
args_schema。过早优化只会增加代码量，反而降低可读性。
三、让 Agent 用你的 Tool 干活
3.1 用 create_agent 挂载工具
光有工具不够，得让 Agent 学会用它。create_agent是最简单的方式：
from langchain.agents import create_agent from langchain.tools import tool @tool def get_weather(city: str) -> str: """查询指定城市的实时天气。""" data = {"北京": "32°C，晴", "上海": "28°C，小雨"} return data.get(city, "未找到数据") @tool def calculate(expression: str) -> str: """执行数学计算，如 '3*15+2'。""" return str(eval(expression)) agent = create_agent( model="deepseek:deepseek-chat", tools=[get_weather, calculate], system_prompt="你是一个有用的助手，能查天气和做计算。", ) result = agent.invoke({ "messages": [{"role": "user", "content": "北京今天天气怎么样？"}] }) print(result["messages"][-1].content) # 输出：北京今天 32°C，晴天。3.2 背后发生了什么？
一条消息进来，Agent 内部经过了四个步骤：
步骤 1：LLM 收到"北京今天天气怎么样？"
步骤 2：LLM 判断需要查天气 → 生成tool_call: get_weather(city="北京")
步骤 3：ToolNode 执行get_weather("北京")→ 返回"32°C，晴"
步骤 4：LLM 收到结果，组织回复：“北京今天 32°C，晴天。”
关键洞察：整个流程 LLM 不需要知道天气 API 长什么样。它只决策"该用哪个工具、传什么参数"。API 怎么调、数据怎么查——全部由 ToolNode 代劳。
3.3 什么时候用 Agent + Tool？
| 场景 | 说明 |
|---|---|
| 用户问题需要动态数据 | 订单状态、股价、天气——每次结果不同 |
| 需要精确计算或日期运算 | 复杂公式、日期跨度——模型容易算错 |
| 多工具协作 | Agent 自动判断调用哪个工具 |
边界：单个 Tool 的简单场景不一定要 Agent——直接
tool.invoke({"city": "北京"})更轻量。Agent 的价值在于"自动判断用不用、用哪个"，适合多工具、多轮推理。
四、动手写一个：笔记工具
目标：实现保存笔记 + 搜索笔记，用内存字典模拟数据库。
from langchain.tools import tool # 内存字典模拟数据库（生产环境换 Redis 或 SQLite） notes_db: dict[str, str] = {} @tool def save_note(title: str, content: str) -> str: """保存一条笔记。当用户说"帮我记一下"时使用。 Args: title: 笔记标题 content: 笔记正文 """ notes_db[title] = content returnf"✅ 笔记「{title}」已保存" @tool def search_notes(keyword: str) -> str: """根据关键词搜索笔记。当用户问"之前记的xxx"时使用。 Args: keyword: 搜索关键词 """ results = [ f"📝 {t}: {c}" for t, c in notes_db.items() if keyword in t or keyword in c ] return"/n".join(results) if results else"未找到相关笔记"两个工具的职责分工：
| 工具 | 触发词 | 输入 | 输出 |
|---|---|---|---|
save_note | “帮我记一下” | title + content | 保存确认 |
search_notes | “之前记的xxx” | keyword | 匹配的笔记列表 |
创建 Agent 测试：
from langchain.agents import create_agent agent = create_agent( model="deepseek:deepseek-chat", tools=[save_note, search_notes], system_prompt="你是笔记助手，帮用户记录和查找笔记。", ) # 保存笔记 agent.invoke({ "messages": [{"role": "user", "content": "帮我记：下周三下午3点，401会议室，项目复盘会"}] }) # 输出：✅ 笔记「项目复盘会」已保存 # 搜索笔记 agent.invoke({ "messages": [{"role": "user", "content": "我之前记的关于开会的笔记是什么？"}] }) # 输出：📝 项目复盘会: 下周三下午3点，401会议室五、写 Tool 的四个要点
记住这四点，能省 80% 调试时间：
| 要点 | 原因 | 反面案例 |
|---|---|---|
| 类型注解必须写 | LLM 靠它知道参数类型 | 不写 → LLM 传参不可预测 |
| docstring 是工具的"简历" | LLM 看 docstring 决定用不用 | 只写技术参数 → LLM 不知道该不该调 |
| 返回值只能是字符串 | LLM 拿字符串当推理上下文 | 返回 dict → 解析失败 |
| 函数名用 snake_case | 空格名被部分模型拒绝 | get weather→ 调用报错 |
生产环境注意
⚠️ 生产环境提醒：开启 ToolNode 错误处理，别让一个工具挂了就把整个 Agent 搞崩。
from langgraph.prebuilt import ToolNode tool_node = ToolNode( [get_weather, calculate, save_note, search_notes], handle_tool_errors=True # 异常被捕获，转成错误消息告诉 LLM )开启后，LLM 看到错误消息会尝试换一种方式调用，或者告诉用户"这个操作暂时做不了"——比直接崩溃好得多。
六、总结
三个核心认知：
Tool = 签名 + 描述 + 实现，
@tool装饰器是最简单的方式create_agent一行代码挂载工具，ToolNode 自动管理调用流程docstring 决定 LLM 选不选你的工具——写的越清晰具体，Agent 表现越稳定
下一步学什么？
| 主题 | 一句话说明 | 适合场景 |
|---|---|---|
| ToolRuntime | 给工具注入会话上下文（用户 ID、数据库连接） | 告别全局变量，生产环境必备 |
| MCP 协议 | Anthropic 提出的标准化工具接口 | 一套工具对接多个 LLM 平台 |
| LangSmith | 可视化每次工具调用的入参、出参、耗时 | 排查 Agent 行为异常 |
💡 动手试一下：把第四节的笔记工具跑通，然后试着加一个
delete_note工具。10 分钟就能上手。
这里给大家精心整理了一份全面的AI大模型学习资源，包括：AI大模型全套学习路线图（从入门到实战）、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等，资料免费分享！
👇👇扫码免费领取全部内容👇👇
1. 成长路线图&学习规划
要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。
这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。
2. 大模型经典PDF书籍
书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）
3. 大模型视频教程
对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。
4. 2026行业报告
行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。
5. 大模型项目实战
学以致用，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。
6. 大模型面试题
面试不仅是技术的较量，更需要充分的准备。
在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。
7. 资料领取：全套内容免费抱走，学 AI 不用再找第二份
不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：
👇👇扫码免费领取全部内容👇👇