AI Agent / 系统课时

实现工具分发器

实现工具分发器

工具分发器负责把模型返回的工具名和参数转换成真实函数调用,并把成功、失败都归一为稳定结果。完成这一层后,Agent 不再需要为每个工具写一套分支逻辑,新增工具只需注册处理函数。

学习目标

  • 用注册表把工具名映射到可执行函数
  • 统一处理未知工具、执行异常和返回结果
  • 保持分发层只负责任务路由,不混入业务逻辑

分发器要解决什么

模型通常会给出类似 { name, arguments } 的调用请求。真正执行前,应用必须根据 name 找到对应函数,再把参数传入。最直接的连续 if...else 在工具数量增加后会迅速变难维护,因此更适合使用“工具注册表 + 通用分发函数”。

工具请求经过注册表分发到具体函数并归一返回结果

分发层的核心边界是:只做查找、调用、异常转换。参数是否合法、用户是否有权限,应该由执行前的校验层处理;具体业务规则则留在各工具函数内部。这样每层职责单一,错误也更容易定位。

用注册表完成路由

把代码保存为 tool_router.py,与前两课的文件放在同一目录。示例先用解析器校验一次天气调用,再用 Python 字典把工具名映射到处理函数。天气返回固定测试数据。已验证用户在本次请求中允许使用的工具由服务端传入。

python
import json

from tool_parser import parse_batch


def get_weather(*, city, unit):
    temperatures = {("上海", "celsius"): 23, ("上海", "fahrenheit"): 73.4}
    if (city, unit) not in temperatures:
        return {"city": city, "unit": unit, "status": "unavailable"}
    return {"city": city, "unit": unit, "temperature": temperatures[city, unit]}


HANDLERS = {"get_weather": get_weather}


def dispatch(call, allowed_names):
    handler = HANDLERS.get(call["name"])
    if handler is None:
        return {"ok": False, "error": {"code": "TOOL_NOT_FOUND"}}
    if call["name"] not in allowed_names:
        return {"ok": False, "error": {"code": "PERMISSION_DENIED"}}
    try:
        data = handler(**call["arguments"])
    except Exception:
        # 在内部按策略记录错误类别和关联 ID。
        return {"ok": False, "error": {"code": "TOOL_EXECUTION_FAILED"}}
    return {"ok": True, "data": data}


def format_result(call_id, result, protocol):
    content = json.dumps(result, ensure_ascii=False, allow_nan=False)
    if protocol == "chat":
        return {"role": "tool", "tool_call_id": call_id, "content": content}
    if protocol == "responses":
        return {"type": "function_call_output", "call_id": call_id, "output": content}
    raise ValueError("unsupported protocol")


if __name__ == "__main__":
    raw_call = {
        "id": "call_1", "type": "function", "function": {
            "name": "get_weather", "arguments": '{"city":"上海","unit":null}',
        },
    }
    call = parse_batch([raw_call], "chat")[0]
    result = dispatch(call, {"get_weather"})
    print(result["data"])
    print(format_result(call["id"], result, "chat")["tool_call_id"])
    print(format_result(call["id"], result, "responses")["call_id"])
    print(dispatch(call, set())["error"]["code"])

预期输出

text
{'city': '上海', 'unit': 'celsius', 'temperature': 23}
call_1
call_1
PERMISSION_DENIED

把结果关联回模型请求

Chat Completions 把助手的 tool_calls 消息加入历史,再为每项调用添加一条 role: "tool" 的结果。Responses 把 function_call_output 作为下一请求的输入项,并延续前一响应的上下文。若手动管理上下文,按模型要求一并传回前次输出项,包括适用的推理项。示例只组装结果,不依赖第 02 章的文本客户端。

保持错误码稳定,异常内容、内部路径及凭据留在受控诊断链路,必要时脱敏。业务工具仍要核对具体资源权限。若加入带副作用的工具,先定义参数、身份、审批和幂等入口,再注册经过这些检查的处理函数。下一课用积分转移说明这些约束。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现工具分发器

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

登录哪都通