AI Agent / 系统课时
把 Python 函数注册为工具
把 Python 函数注册为工具
普通 Python 函数只有程序员知道怎样调用,模型并不知道函数名称代表什么、需要哪些参数。把函数注册为工具,就是为它补齐稳定名称、结构化参数模式和用途描述,同时保留一个可以直接执行和验证的 Python 实现。
学习目标
- 理解工具名称、参数模式和描述分别解决什么问题
- 使用
@tool与 Pydantic 模型注册结构化 Python 工具 - 在接入模型前直接调用工具,验证参数校验和业务实现
工具注册要补齐三类信息
模型选择工具时看到的不是函数源码,而是一个机器可读的接口。名称应该稳定并能区分业务动作;描述要说明什么时候应该调用以及工具能返回什么;参数模式则定义字段名称、类型和含义,使模型能够生成结构化参数。
例如订单查询工具如果只叫 query,模型很难区分它是在查订单、用户还是库存。参数如果只暴露一个没有说明的 str,模型也不知道应该填订单号还是自然语言问题。因此,工具接口应尽量采用业务语义明确的名称和字段,而不是把这些信息藏在函数内部。
注册一个结构化查询工具
下面使用 langchain_core.tools.tool 注册订单查询函数,并用 Pydantic 明确定义输入模式。示例不依赖模型 API,因此可以先单独验证工具本身是否正确。
from pydantic import BaseModel, Field
from langchain_core.tools import tool
class OrderQuery(BaseModel):
order_id: str = Field(
description="业务订单号,例如 A1001"
)
ORDERS = {
"A1001": "shipped",
"A1002": "processing",
}
@tool("lookup_order", args_schema=OrderQuery)
def lookup_order(order_id: str) -> str:
"""按订单号查询订单状态;仅用于已有订单。"""
status = ORDERS.get(order_id)
if status is None:
return f"order_id={order_id},status=not_found"
return f"order_id={order_id},status={status}"
print(f"name={lookup_order.name}")
print(f"description={lookup_order.description}")
result = lookup_order.invoke({"order_id": "A1001"})
print(f"result={result}")预期输出
name=lookup_order
description=按订单号查询订单状态;仅用于已有订单。
result=order_id=A1001,status=shippedOrderQuery 就是工具的参数契约。order_id 的类型限制输入必须是字符串,Field 中的描述则给调用方补充字段语义。函数体仍然是普通业务代码,因此既可以通过工具对象执行,也能独立测试其中的查询逻辑。
描述要帮助模型做选择
工具描述不需要写成长篇操作手册,但必须说明用途边界。相比“查询信息”,示例中的“按订单号查询订单状态;仅用于已有订单”明确告诉模型输入对象和适用场景,也降低了把它误用于创建订单或搜索商品的概率。
名称同样应该保持稳定。一旦提示词、状态记录或监控系统开始引用工具名,随意把 lookup_order 改成其他名称会形成接口变更。对于多个相似工具,可以让动词和业务对象同时出现在名称中,例如查询订单与取消订单应使用两个不同的工具,而不是依赖一个含义模糊的万能函数。
先验证工具再交给模型
注册成功并不代表模型一定会调用它。工具注册解决的是“这个能力如何被描述和执行”,而模型绑定、工具选择以及执行后如何回到智能体循环属于后续编排问题。
在进入智能体之前,至少应像示例一样直接执行一次 invoke。这样可以先确认参数名称与 Pydantic 模型一致、函数能处理合法输入、返回值具有稳定语义。如果工具自身都无法独立通过验证,把它交给模型只会把参数错误和业务异常隐藏到更复杂的智能体运行链路中。
一个可用的 LangGraph 工具起点并不是复杂的代理逻辑,而是一个边界清楚的函数接口:名称可区分、描述能指导选择、参数模式足够明确,并且函数本身能够在不依赖模型的情况下独立验证。