如果说模型负责“理解、推理和表达”，那么工具（Tools）负责“接触真实世界”。没有工具的模型，只能基于训练数据和当前上下文进行回答；有了工具，模型才能查天气、查订单、读数据库、检索知识库、发送草稿、访问内部接口。因此，工具是从“会聊天”走向“能办事”的关键桥梁。

本章会从 Tool 的概念、定义方式、Schema 设计、返回值设计、状态访问、错误处理，到与 Agent 协同工作的方法，系统讲清楚如何构建真正“好用”的工具。

Tool 本质上是一段可被模型调用的函数能力。根据 LangChain 官方文档，一个工具通常包含三个关键元素：

• 名称：模型看到的工具名；
• 描述：模型判断“何时该用”的依据；
• 参数 Schema：模型知道“怎么调用”的结构。

最容易理解的比喻是：Tool 就是给模型看的 API 文档。

如果你只给程序员看，它是函数；如果你既要给程序员看，也要给模型看，它就必须设计成 Tool。

普通函数通常只考虑：

• 逻辑是否正确；
• 参数是否完整；
• 返回是否可用。

而 Tool 还要额外考虑：

• 模型能不能理解这个工具是干什么的；
• 模型会不会误用它；
• 模型能不能正确填参数；
• 返回结果是否适合下一步推理。

from langchain_core.tools import tool
 
@tool
def get_weather(city: str) -> str:
    """查询指定城市天气。"""
    return f"{city} 今日晴，24 到 31 摄氏度。"

这个工具已经具备：

• 工具名：`get_weather`
• 描述：来自 docstring
• 参数：`city: str`

LangChain 官方文档明确强调，工具 docstring 应当简洁且信息充分，因为它直接帮助模型理解何时使用该工具。

一个好的 docstring 应该回答：

• 什么时候该用；
• 参数分别表示什么；
• 结果大致返回什么；
• 是否有边界限制。

坏例子：

• “查询接口。”

好例子：

• “根据订单编号查询订单状态和物流信息，仅适用于已创建订单。”

如果参数很少，直接靠函数签名即可。

@tool
def exchange_rate(base_currency: str, quote_currency: str) -> str:
    """查询两种货币之间的汇率。"""
    return f"1 {base_currency} = 7.21 {quote_currency}"

复杂工具更推荐使用 Pydantic 定义 Schema，这样字段描述会更清晰。

from pydantic import BaseModel, Field
from typing import Literal
from langchain_core.tools import tool
 
class WeatherInput(BaseModel):
    city: str = Field(description="城市名称，例如北京、上海")
    units: Literal["celsius", "fahrenheit"] = Field(
        default="celsius",
        description="温度单位"
    )
    include_forecast: bool = Field(
        default=False,
        description="是否返回未来 3 天预报"
    )
 
@tool(args_schema=WeatherInput)
def get_weather(city: str, units: str = "celsius", include_forecast: bool = False) -> str:
    """查询城市天气，可选返回未来天气预报。"""
    temp = 26 if units == "celsius" else 78
    result = f"{city} 当前温度：{temp}°"
    if include_forecast:
        result += "；未来三天：多云、小雨、晴"
    return result

• 字段名应清晰，不要用 `x1`、`arg2` 这类无语义名字；
• 能枚举就枚举，例如 `priority` 用 `low/medium/high`；
• 描述要体现业务语义，不只是技术含义；
• 尽量避免一个工具接受十几个松散参数；
• 高风险参数要明确写明取值规则。

根据 LangChain 官方文档，工具返回值可以是：

• 字符串；
• 对象 / dict；
• `Command`（用于更新状态）。

适合模型直接阅读的自然语言结果。

@tool
def get_inventory(sku: str) -> str:
    """查询商品库存。"""
    return f"SKU {sku} 当前库存 23 件，位于华东一号仓。"

适合场景：

• 返回结果本身就是一句清晰结论；
• 模型只需继续基于文字推理；
• 结果结构简单。

如果你希望模型能显式读取字段，返回 `dict` 更合适。

@tool
def get_inventory_data(sku: str) -> dict:
    """查询商品库存详情。"""
    return {
        "sku": sku,
        "available": 23,
        "reserved": 5,
        "warehouse": "east_01",
        "last_updated": "2026-04-03 10:30:00"
    }

适合场景：

• 下游模型需要基于多个字段推理；
• 你希望结果更稳定可解析；
• 后面可能会把同一个工具复用于 API 或审计系统。

在 LangChain / LangGraph 体系中，某些工具不仅返回数据，还要直接修改 Agent 状态。这时可以返回 `Command`。

from langchain_core.tools import ToolRuntime, tool
from langchain_core.messages import ToolMessage
from langgraph.types import Command
 
@tool
def set_language(language: str, runtime: ToolRuntime) -> Command:
    """设置用户偏好的回复语言。"""
    return Command(
        update={
            "preferred_language": language,
            "messages": [
                ToolMessage(
                    content=f"已将语言偏好设置为 {language}",
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

这类工具适合：

• 保存用户偏好；
• 更新当前任务状态；
• 写入工作流共享字段。

LangChain 官方文档提到，可以通过 `runtime: ToolRuntime` 访问会话状态，这个参数不会暴露给模型，只会在运行时自动注入。

from langchain_core.tools import tool, ToolRuntime
from langchain_core.messages import HumanMessage
 
@tool
def get_last_user_message(runtime: ToolRuntime) -> str:
    """读取最近一条用户消息。"""
    messages = runtime.state["messages"]
    for message in reversed(messages):
        if isinstance(message, HumanMessage):
            return message.content
    return "未找到用户消息"

@tool
def get_user_preference(pref_name: str, runtime: ToolRuntime) -> str:
    """读取用户偏好设置。"""
    preferences = runtime.state.get("user_preferences", {})
    return str(preferences.get(pref_name, "未设置"))

这种方式的好处是：

• 工具可以更“上下文化”；
• 不必要求模型把所有状态字段都手工重复传参；
• 对复杂 Agent 特别有价值。

from langchain_openai import ChatOpenAI
 
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
model_with_tools = model.bind_tools([get_weather, get_inventory])
response = model_with_tools.invoke("查询 SKU A-100 库存，并顺便看看上海天气")
print(response.tool_calls)

绑定之后，模型就具备了“选择工具”的能力。但你仍需要决定：

• 是手动执行工具调用闭环；
• 还是交给 Agent 框架自动完成。

response = model_with_tools.invoke("北京天气怎么样？")
for tool_call in response.tool_calls:
    print("tool:", tool_call["name"])
    print("args:", tool_call["args"])

这个阶段很适合调试：

• 模型到底会不会选对工具；
• 参数有没有填错；
• 工具描述是否足够清楚。

大多数真实项目不会手写每一轮工具循环，而是直接交给 `create_agent()`。

from langchain.agents import create_agent
 
agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[get_weather, get_inventory],
    system_prompt="你是企业运营助手，涉及事实问题时优先调用工具核实。"
)
 
result = agent.invoke({
    "messages": [{"role": "user", "content": "帮我查一下上海天气，并看看 SKU A-100 库存是否够发货。"}]
})
 
print(result)

此时 Agent 会：

• 读取用户消息；
• 判断是否要调工具；
• 执行工具；
• 将 ToolMessage 回传；
• 再次调用模型汇总答案。

工具连接的是外部世界，所以错误不是异常情况，而是常态：

• 网络超时；
• 参数错误；
• 权限不足；
• 数据为空；
• 下游返回格式变化；
• 第三方接口不可用。

@tool
def safe_order_query(order_id: str) -> str:
    """查询订单状态。"""
    try:
        if not order_id.startswith("ORD"):
            return "订单号格式错误，请提供以 ORD 开头的订单编号。"
        return f"订单 {order_id} 当前状态：已出库，预计明日送达。"
    except TimeoutError:
        return "订单服务超时，请稍后重试。"
    except Exception as exc:
        return f"订单查询失败：{exc}"

LangChain 官方自定义中间件文档提供了 `@wrap_tool_call` 的模式，适合做日志、监控、统一错误包装。

from collections.abc import Callable
from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage
from langchain.tools.tool_node import ToolCallRequest
from langgraph.types import Command
 
@wrap_tool_call
def monitor_tool(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
    print(f"Executing tool: {request.tool_call['name']}")
    print(f"Arguments: {request.tool_call['args']}")
    try:
        result = handler(request)
        print("Tool completed successfully")
        return result
    except Exception as e:
        print(f"Tool failed: {e}")
        raise

这类中间件适合做：

• 调用日志；
• 指标采集；
• 错误监控；
• 风险操作审计。

坏工具：

• `business_assistant()`：既查天气、又查订单、又发邮件。

好工具：

• `get_weather()`
• `query_order_status()`
• `draft_email()`
• `create_approval_draft()`

拆分的好处：

• 便于模型选择；
• 便于测试；
• 便于权限控制；
• 便于指标分析。

模型关心的不是你的内部接口路径，而是“我什么时候该调用这个工具”。

例如：

• 好描述：根据订单号查询订单当前状态和物流信息，仅适用于已创建订单。
• 坏描述：调用 `/api/v3/order/detail` 接口，返回 OMS JSON。

不要机械返回原始 JSON。更好的方式通常是：

• 过滤无关字段；
• 统一单位和时间格式；
• 标明数据更新时间；
• 在必要时补充解释；
• 对异常场景返回模型可理解的提示。

不是所有工具都能直接暴露给 Agent。尤其是：

• 写数据库；
• 发正式邮件；
• 退款；
• 创建审批单；
• 删除数据；
• 执行系统命令。

这类工具建议采取分层策略：

• 只读工具：可直接开放；
• 草拟工具：允许生成草稿，不允许最终提交；
• 审批工具：必须人工确认后执行；
• 禁止暴露工具：只允许后台系统调用。

@tool
def draft_email(to: str, subject: str, body: str) -> dict:
    """生成待确认的邮件草稿，不会真正发送。"""
    return {
        "status": "draft",
        "to": to,
        "subject": subject,
        "body": body
    }

真正发送邮件应由：

• 用户在界面确认；
• 或工作流走到人工审批节点后；
• 再调用后端受控接口完成。

下面给出一个更接近真实业务的例子：

from langchain.agents import create_agent
from langchain_core.tools import tool
 
@tool
def query_order(order_id: str) -> dict:
    """根据订单号查询订单状态和物流信息。"""
    return {
        "order_id": order_id,
        "status": "已出库",
        "logistics_status": "运输中",
        "eta": "2026-04-04"
    }
 
@tool
def query_inventory(sku: str) -> dict:
    """根据 SKU 查询当前可用库存。"""
    return {
        "sku": sku,
        "available": 23,
        "warehouse": "华东一号仓"
    }
 
@tool
def draft_delay_notice(order_id: str, reason: str) -> str:
    """生成延迟发货通知草稿，不会真正发送。"""
    return f"订单 {order_id} 延迟通知草稿：由于 {reason}，预计发货时间将顺延 1 天。"
 
agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[query_order, query_inventory, draft_delay_notice],
    system_prompt="""
你是订单运营助手。
1. 涉及订单、库存等事实信息时，必须优先调用工具。
2. 不要编造库存数字或发货状态。
3. 涉及通知用户时，只生成草稿，不得声称已经发送。
"""
)
 
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "请帮我看订单 ORD20260403001 是否会延迟，如果延迟顺便生成一份通知草稿。"
    }]
})
 
print(result)

• Tool 是模型接触真实世界的接口层；
• 好工具不仅要功能正确，还要让模型容易理解和正确使用；
• 参数 Schema、描述和返回格式会直接影响工具调用质量；
• `ToolRuntime` 和 `Command` 让工具具备读取和更新状态的能力；
• 高风险工具必须加人工确认或工作流控制；
• 统一监控和错误处理，是工具工程化的关键。

1. 实现 3 个工具：天气查询、订单查询、库存查询，并为每个工具编写清晰的 docstring 与参数 Schema。

2. 设计一个“邮件发送”双阶段流程：Agent 只能生成草稿，用户确认后才能真正发送。

3. 将一个原始 JSON 接口返回值，重构为更适合模型理解的文本或结构化对象输出。

4. 使用 `@wrap_tool_call` 编写一个工具监控中间件，记录工具名、参数和执行时长。

5. 为你的业务设计一个不超过 8 个工具的 Agent 工具集，并说明每个工具的边界。

• LangChain 官方文档：Tools
• LangChain 官方文档：Agents
• LangChain 官方文档：Custom middleware