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。写入工具需要检查业务权限,在适用的场景校验确认凭证和幂等键。返回给模型的内容应保留对处理有用的信息,避免暴露密钥或内部堆栈。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

自定义工具开发

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通