一、本章导学

在前几章中，我们已经能够调用大模型完成对话和文本生成。但大模型有一个根本性的局限：它只能生成文本。它不能上网搜索、不能做精确计算、不能读写文件、不能调用 API。它就像一个博学但被锁在房间里的人——什么都懂，却什么都做不了。

说到使用者痛点。想让 AI 直接获取实时信息、执行计算或与业务程序交互，却被模型的“无手无眼”限制住。

Tool就是给 AI 装上的“双手和眼睛”。按理说，、读写数据库、发送邮件，或者调用任何业务程序中的 API。而 Agent 之所以能“自主决策”何时调用哪个工具，背后靠的是 ReAct循环模式和 Tool-Calling 机制。

本章将程序讲解四大主要主题：

• @tool 装饰器的定义与使用
• Agent 工作原理
• MCP 协议入门
• 多工具 Agent 的综合实战

flowchart TD
A --> B
A --> C
A --> D
A --> E
B --> C --> E
D --> E
style A fill:#e1f5fe。stroke:#01579b
style C fill:#fff3e0,stroke:#e65100

二、@tool 装饰器：定义工具

基础用法

@tool 装饰器是 LangChain 中定义工具最简单的方式。它将普通 Python 函数转换为 Agent 可调用的 Tool 对象：

from langchain.tools import tool
# 示例代码
@tool
def hello -> str:
"""向指定的人打招呼。至于Args，name: 要打招呼的人的名字
"""
return f"你好，{name}！欢迎来到 AI 的世界，"
print
print

再看运行结果，

hello 向指定的人打招呼。

就这几行代码，你就创建了一个可被 Agent 使用的工具。@tool 装饰器的工作过程是：函数签名中的类型注解用于生成 JSON Schema，docstring 作为工具描述传递给模型。

docstring 设计原则

docstring 是模型理解工具的唯一信息来源。写好 docstring 很关键，因为它直接决定了 Agent 能否正确使用你定义的工具。

• 第一句话说明用途和使用场景
• 明确说明什么时候该用、什么时候不该用
• 参数描述包含取值范围和格式
• 保持简洁但完整

from langchain.tools import tool
# 不好的 docstring
@tool
def search -> str:
"""搜索"""
...
# 好的 docstring
@tool
def search_product_reviews -> str:
"""搜索指定商品的使用者评价。当使用者想了解某款产品的口碑或使用体验时使用此工具。不要用于搜索商品价格或库存信息。再看Args，product_name: 商品名称或型号，越具体越好
min_rating: 最低评分筛选，-5分。默认0表示不筛选
"""
...

参数类型注解

类型注解不仅仅是代码规范，它直接决定了工具能否正确工作。LangChain 需要将工具信息转换为 JSON Schema 格式发送给模型，缺少类型注解会导致模型不知道该传什么类型的参数。

支持基本类型和复杂类型：

from typing import List,Dict。Literal
@tool
def filter_products(
categories: List,price_range: Dict,sort_by: Literal,) -> str:
"""搜索和筛选商品。
 Args:
categories: 商品类别列表，如
price_range: 价格范围，格式为{"min": 最低价,"max": 最高价}
sort_by: 排序方式


"""
return (
f"筛选条件这方面，类别={categories},"
f"价格范围={pricerange}-{pricerange},"
f"排序={sort_by}"
)

from pydantic import BaseModel。Field

class FlightSearchInput:
"""航班搜索的输入参数"""
origin: str = Field")
destination: str = Field
departure_date: str = Field
passengers: int = Field(default=1,ge=1,le=10,description="乘客人数")


@tool
def searchflights(origin:str,destination:str,departuredate:str,passengers:int =1) -> str:
"""搜索航班信息。当使用者需要查询机票时使用。"""
return f"搜索航班:{origin} → {destination},出发:{departure_date}。{passengers}人"


返回值处理

工具的返回值必须是字符串。返回有意义的错误信息比抛异常更友好——因为 Agent 需要将错误信息返回给模型，让模型决定如何处理：

@tool
def divide_numbers->str:
"""将两个数相除。
 Args:
a 被除数
b 除数


"""
if b==0:
return "错误：除数不能为零。请提供一个非零除数，"
return f"{a} ÷ {b} = {a / b}"


# 异步工具示例 

import httpx
@tool
async def fetch_webpage->str:
"""异步获取网页内容。
 Args:
url 要获取的网址


"""
async with httpx.AsyncClient as client:
response=await client.get
response.raiseforstatus
return response.text


@tool 装饰器流程图 


flowchart LR
subgraph INPUT
FN
DS
AN
end 


INPUT --| "@tool 装饰器"| TOOL 

TOOL -- NAME
TOOL -- DESC
TOOL -- SCHEMA 

SCHEMA -- PROMPT


三、Agent 工作原理：ReAct 循环 

Chain vs Agent 

C​hain 就像工厂流水线——每一步做什么按什么顺序执行，都在写代码时确定；而 Agent 就像自动驾驶——你只告诉它目的地，它自己决定怎么走。

Tip: 如果任务逻辑固定，用 Chain；如果任务需要灵活决策，用 Agent。

示例链式流程：
python
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain.chat_models import init_chat_model
model = init_chat_model(
model=os.getenv,api_key=os.getenv,base_url=os.getenv。model_provider='openai'
)
prompt = ChatPromptTemplate.from_template(
"将下面内容翻译成{language}:
{text}"
)
chain = prompt | model | StrOutputParser
result = chain.invoke
print
至于**输出**，`Today is a good day.`
示例代理流程：
python
from langchain.agents import create_agent
agent=create_agent
result=agent.invoke]})
print
至于**输出**，`北京今天晴朗温度25°C空气质量良好`
### ReAct 模式详解
ReAct 是目前最主流 agent 架构模式，它让模型交替进行 **思考** 与 **行动**，形成 Think → Act → Observe 的闭环。mermaid flowchart TD START-->T1-->A1-->O1-->T2-->A2...
以“北京天气怎么样”为例：
mermaid sequenceDiagram participant U as 使用者 participant A as Agent participant L as LLM participant T as Tool U->-A 提问 A->-L 问题+Tool 列表 L-->A 返回 tool_calls A->-T 执行 get_wear T-->A 工具结果 A->-L 返回最终回答 A-->U 回答结束
#### 完整可运行 Demo
python # -*- encoding:utf- -*-
"""react_demo.py"""
from dotenv import load_dotenv;怎么说呢，load_dotenv
import os
from langchain.chat_models import init_chat_model
from langchain.tools import tool
from langchain.agents import create_agent
# 定义 Tools ----------------------------------------------
@tool
def get_wear->str:"""查询指定城市当前天气。
Args这方面，city 城市名称"""
wear_db={"北京":"晴，25°C","上海":"多云。28°C"}
return wear_db.get
@tool
def get_distance->str:"""查询两个城市距离。Args这方面，city_a 第一个城市 city_b 第二个城市"""
distances={:1200}
return distances.get,f"{city_a}-{city_b}未找到距离")
model=init_chat_model(
model=os.getenv。api_key=os.getenv,base_url=os.getenv,model_provider='openai'
)
agent=create_agent(model，system_prompt="""
你是智能助手擅长天气及距离查询。""")
question ="我计划从北京去上海出差。请告诉我这两个城市今天天气，还有它们之间距离。"
res=agent.invoke]})
for msg in res:
if hasattr: print
elif hasattr: print
else : pass
**运行结果示例**
text
=============================================
从使用者来看。我计划从北京去上海出差，请告诉我这两个城市今天天气，还有它们之间距离。=============================================
我需要查询信息 调用 get_wear
晴，25°C 我需要再查询上海 ...
北京今天天气晴朗25°C；上海多云28°C，老实说，两地距离约1200公里…### Tool‑Calling 技术细节
| 步骤 | 内容 |
|------|------|
| 注入 | 框架把名称、描述与 JSON Schema 注入 Prompt |
| 决策 | 模型分析问题并决定是否调用；若需则返回 `tool_calls` |
| 执行 | 框架解析 `tool_calls` 并调用对应 Python 函数 |
| 反馈 | 将结果作为 `ToolMessage` 加入消息列表，交由 LLM |
**Agent 消息流示意**
mermaid sequenceDiagram participant S as SystemMessage participant H as HumanMessage participant AM as AIMessage participant TM as ToolMessage AM-->S ... AM-->TM ... TM-->AM ... AM-->
U 返回答案
---
### 常见陷阱 & 调试技巧
#### 工具不被调用？老实说，* docstring 不够清晰导致模型无法识别；* 模型不支持 Function Calling，需要 GPT‑4o/Claude 等；按理说，* 问题本身不需外部数据。#### 无限循环，* 设置 `recursion_limit`;* 检查 docstring 是否含歧义。#### 错误选择，* 合并功能相近且命名相似；* 精细化 DocString 与 Pydantic 校验；#### 打印完整历史调试：
python for msg in result:
if isinstance: print
elif hasattr: print
elif hasattr: print
---

四、MCP 协议入门 
### MCP 架构概述
MCP 为大模型与外部应用之间提供标准化接口，让不同网站提供能力成为“一键插拔”。再看三层角色，* **Host ** - LangChain 服务端；* **Client** - 在 LangChain 内部跑，实现连接管理；老实说，* **Server** - 真正提供功能。例如高德地图、Slack 通知等。### 与 @tool 的对比
" />


MCP协议特性 
@tool 


位置 & 调度方式 \
本地 Python 函数\
跨进程\
复用性仅限当前应用\
任何 Client 均可接入\
适用于私有小规模服务\
易部署。但需额外服务进程 \
维护成本较高 
\
\t\t\t\t\t\t\t\t\t\t\t\r\r\r\r\r\r\r\r\r\r\r\r\r \
\r \
",

位置 & 调度方式 \
同进程内实现\
快速响应，无网络延迟\
复用性仅限当前脚本\
仅适合一次性脚本或测试场景\
易于快速开发与测试\
无须额外部署服务进程 \
// 小规模内部插件就可以。\t\t\t\t","

### 基础 MCP Server 搭建
安装 SDK：
bash uv add mcp
创建最简服务器:
python # math_server.py from mcp.server.fastmcp import FastMCP mcp = FastMCP
@mcp.tool
def add->int:"""计算两个整数之和."""return a+b
@mcp.tool
def multiply->int:"""计算乘积."""return a*b
if __name__=="__main__":
mcp.run
在 LangChain 内部加载并使用:
python from mcp.client.fastmcp_client import FastMCPClient async def main:
model=model_init
async with FastMCPClientas client:
tools=list)
agent=create_agent
res=agent.invoke]})
for msg in res:
if msg.type=='ai' and msg.content : print
asyncio.run)
---

五、多工具Agent 实战案例 
定义本地 & MCP 工具:
python # multi_tool_agent.py from dotenv import load_dotenv;load_dotenv
import os,asyncio
from langchain.chat_models import init_chat_model
from langchain.tools import tool
from lib.mcp_client.fastmcp_client import FastMCPClient
# 本地 tools ------------------------------------------------------------
@tool
def get_stock_price->str:"""获取股票当前价格。当询问某只股票价格时使用"""
prices={'AAPL':'$140','TSLA':'$650'}
return prices.get,f"{symbol} 未找到")
@tool
def convert_currency->str:"""汇率换算"""
rates={'USD':1。'CNY':6.7}
if currency_from.upper not in rates or currency_to.upper not in rates:return 'unsupported'
return f"{amount}{currency_from}->{amount*rates/rates}{currency_to}"
# MCP 工具 ------------------------------------------------------------
async def main: local=
async with FastMCPClientas client :
tools=list) + local
model=model_init
agent=create_agent
res_1=agent.invoke ]})
for m in res_1:
if hasattr:print
res_2=agent.invoke ]})
for m in res_2:
if hasattr:print
asyncio.run)
---
### 概念图解释
---
## 六常见陷阱与调试技巧



**文档不足导致不可调用** – 清晰编写 DocString 与参数校验。
\r

**无 Function Calling 模型** – 必须启用 GPT‑4o / Claude 等支持结构化输出的大语言模 型。\r

**死循环陷阱** – 设置最大迭代次数还有明确错误处理方法。\r

**多重功能冲突** – 合并重叠功能或添加标签区分不同场景。\r









七、本章小结



@@tool装饰器 – 把普通 Python 函数包装成可被 agent 使用的数据接口 – DocString 是关键。
\r

ReAct 循环 – 思考→行动→观察 的闭环，使 agent 能自主规划任务步骤 – Tool‑Calling 是其技术实现。
\r

MCP 协议 – 统一标准让不同网站提供能力成为“一键插拔” – 可与 @to­ol 混合使用。
\r

多‑Tool Agent – 把内置 tools 与远程 MCP tools 合并到同一列表，让 agent 按需选择最合适方案。
\r







八
阅读




\r
a href='#'>https://github.com/mcprotocol/spec?utmsource=mcmc&utmmedium=social&utmcampaign=mcmc ' target='blank' rel='noopener noreferrer'>https://github.com/mcprotocol/spec?utmsource=mcmc&utmmedium=social&utmcampaign=mcmc'