AI Agent / 系统课时
自定义工具开发
自定义工具开发
给 Agent 增加工具时,需要同时定义模型能看到的工具描述和应用要执行的处理函数。本课把两者放在同一份注册表里,用订单查询练习参数校验与错误处理。
让工具描述和执行约束一致
工具名应稳定,描述应说明何时需要查询。业务输入在宿主程序中仍需重新校验。下面的注册器专门支持“所有字段必填、字段类型均为字符串、拒绝额外字段”的对象形状。这足以表示示例订单查询。需要数字范围、嵌套对象等其他约束时,应换用支持相应关键字的完整校验器。
python
import json
TOOLS = {}
def register_string_tool(name, description, field_descriptions):
fields = dict(field_descriptions)
def register(handler):
if name in TOOLS:
raise ValueError(f"重复注册工具 {name}")
parameters = {
"type": "object",
"properties": {
field: {"type": "string", "description": hint}
for field, hint in fields.items()
},
"required": list(fields),
"additionalProperties": False,
}
TOOLS[name] = {
"definition": {
"type": "function",
"function": {
"name": name, "description": description,
"strict": True, "parameters": parameters,
},
},
"fields": frozenset(fields),
"handler": handler,
}
return handler
return register
@register_string_tool("get_order_status", "查询已有订单的状态", {"order_id": "订单号"})
def get_order_status(order_id):
orders = {"A1001": "PAID", "A1002": "PENDING"}
if order_id not in orders:
return {"error": "order_not_found"}
return {"order_id": order_id, "status": orders[order_id]}
def call_tool(name, arguments):
tool = TOOLS.get(name)
if tool is None:
return {"error": "unknown_tool"}
if not isinstance(arguments, dict) or arguments.keys() != tool["fields"]:
return {"error": "invalid_fields"}
if any(not isinstance(value, str) for value in arguments.values()):
return {"error": "invalid_type"}
return tool["handler"](**arguments)
for args in ({"order_id": "A1001"}, {}, {"order_id": 1001},
{"order_id": "A1001", "admin": "yes"}, {"order_id": "A9999"}):
print(json.dumps(call_tool("get_order_status", args), ensure_ascii=False))合法订单返回 PAID。缺字段和额外字段返回 invalid_fields,数字参数返回 invalid_type,不存在的订单返回 order_not_found。本例的订单表是本地测试数据,接入真实订单前还需核对当前账户是否有权访问该订单。
接入 Agent 运行时
Chat Completions 的 tools 参数使用每条记录的 definition,包括外层类型和内层函数定义。接到模型请求后先解析 JSON,再进入 call_tool。执行结果交给上一课的工具消息构造步骤。strict 约束模型生成的参数结构,应用内的检查仍用于拦截非法值、越权和其他入口传来的数据。
真实工具应在外部调用上设定超时,按错误类别决定重试,并记录可追踪的调用 ID。写入工具需要检查业务权限,在适用的场景校验确认凭证和幂等键。返回给模型的内容应保留对处理有用的信息,避免暴露密钥或内部堆栈。
按自己的节奏,确认真正理解。