把 Python 函数变成工具

学习目标

将一个普通函数包装成具有稳定契约的工具。
用工具白名单和参数校验控制执行范围。
把工具错误返回给决策层，而不是让整个任务崩溃。

前置要求：Python 函数、JSON 校验和模型适配层。本节只用本地数据，不调用模型或外部服务。

工具调用并不是模型执行了代码

模型通常生成一个工具调用提议，包括工具名、参数以及调用标识。应用收到提议后，检查是否允许，再调用实际函数。执行结果通过对应调用标识交还给模型，模型才能依据结果继续回答。

这条边界让程序保留控制权。即使模型提出一个不存在的工具，或把数量写成负数，执行层也必须能拒绝。不能把模型输出直接交给 eval、任意 shell 或任意网络地址。

好工具的输入和输出都具体

lookup_stock(product_id) 比 do_everything(query) 更容易理解和测试。名称表达动作，参数表达必要输入，描述说明适用范围与限制。返回值保持稳定结构，让成功、空结果和失败可以明确区分。

{
  "name": "lookup_stock",
  "description": "按商品 ID 查询当前库存，只读，不下单。",
  "inputSchema": {
    "type": "object",
    "properties": { "product_id": { "type": "string", "minLength": 1 } },
    "required": ["product_id"],
    "additionalProperties": false
  }
}

这里用 inputSchema 表达通用概念。真实模型服务的工具定义字段可能不同，应由适配层转换。

写一个可运行的分发器

保存为 tools.py，运行 python tools.py。

CATALOG = {"python-book": 3, "agent-book": 0}

def lookup_stock(args):
    if not isinstance(args, dict) or set(args) != {"product_id"}:
        return {"ok": False, "error": "invalid_fields"}
    product_id = args["product_id"]
    if not isinstance(product_id, str) or not product_id:
        return {"ok": False, "error": "invalid_product_id"}
    if product_id not in CATALOG:
        return {"ok": False, "error": "product_not_found"}
    return {"ok": True, "product_id": product_id, "stock": CATALOG[product_id]}

TOOLS = {"lookup_stock": lookup_stock}

def dispatch(call):
    if not isinstance(call, dict):
        return {"ok": False, "error": "invalid_call"}
    name = call.get("name")
    if not isinstance(name, str) or name not in TOOLS:
        return {"ok": False, "error": "unknown_tool"}
    return TOOLS[name](call.get("arguments"))

calls = [
    {"name": "lookup_stock", "arguments": {"product_id": "python-book"}},
    {"name": "lookup_stock", "arguments": {"product_id": "missing"}},
    {"name": "delete_database", "arguments": {}},
    {"name": "lookup_stock", "arguments": {"product_id": ["python-book"]}},
]
for call in calls:
    print(dispatch(call))