工具函数写了类型注解还不够。面向智能体时，应让参数名、描述、允许值和错误结果都清楚，避免模型用模糊字符串触发高风险操作。 示例只读查询人为构造的订单状态，不连接真实订单系统，代码未在你的模型上实测；涉及退款、删除或发信的工具还需要审批、授权、幂等与审计。
本篇验收要点：OrderQuery 使用 Pydantic 限定 order_id 格式和 detail 枚举，再通过 args_schema 绑定到工具。 工具对不存在订单返回结构化的 not_found 状态，对 Schema 不通过的输入不进入函数。
用 Schema 表达真实约束
from typing import Literal
from pydantic import BaseModel, Field
from langchain.tools import tool
class OrderQuery(BaseModel):
order_id: str = Field(pattern=r"^ORD-[0-9]{6}$")
detail: Literal["status", "eta"] = "status"
@tool(args_schema=OrderQuery)
def get_order(order_id: str, detail: str = "status") -> dict:
"""Read demo order status or ETA. This tool never changes an order."""
demo = {"ORD-000123": {"status": "shipped", "eta": "2026-10-03"}}
if order_id not in demo:
return {"status": "not_found", "order_id": order_id}
return {"status": "ok", detail: demo[order_id][detail]}
让错误可判断、不可伪装
“查不到”是业务结果，不应抛成系统故障；网络超时、认证失败和上游 5xx 才是可重试异常。返回对象带稳定状态码，智能体可以解释，程序也能分支处理。不要捕获所有异常后返回“成功”，否则会形成伪成功。
写操作增加四道门
若以后增加取消订单等写工具，至少检查当前用户是否拥有订单、使用幂等键、在执行前要求明确确认、执行后从权威系统回读状态。工具描述中写清副作用，不能只依赖模型自行判断权限。
读者下一步是从一个只读、无副作用的内部查询函数开始，为每个参数写出业务约束。
验证标准是合法订单号返回 ok，未知订单返回 not_found，非法格式或 detail 值在调用前被拒绝，而且日志不包含密钥或完整个人信息。
常见问题
工具描述和 Schema 哪个更重要？
两者都需要。描述帮助模型选工具，Schema 在程序侧拒绝不合格参数。
可以把异常文本直接返回给用户吗？
不要。对用户返回稳定错误码和可行动说明，完整堆栈保留在受控日志。
官方资料与适用边界
Ai菜鸟网。发布者：AI小管家，转载请注明出处：https://www.alyyhw.com/31170.html
