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 章的文本客户端。
保持错误码稳定,异常内容、内部路径及凭据留在受控诊断链路,必要时脱敏。业务工具仍要核对具体资源权限。若加入带副作用的工具,先定义参数、身份、审批和幂等入口,再注册经过这些检查的处理函数。下一课用积分转移说明这些约束。
按自己的节奏,确认真正理解。