第五课Tool Router 入门面向 Agent 开发这节课你会学什么这一课讲的是为什么 Tool Router 是 Agent 系统里最贴近“真正行动能力”的核心部分以及怎么搭一个最小可用的工具分发系统。学完这一课你应该能理解这些概念tool 是什么tool schema 是什么tool registry 是什么tool router 是什么参数校验返回值标准化错误处理timeout权限边界最后你会做一个小练习写一个最小 Tool Router让 Agent 能按工具名调用不同工具。1. 为什么 Agent 一定会走到 Tool Router如果一个 Agent 只能聊天那它只是“会说”。如果它要真正做事就必须调用工具例如search搜索资料read_file读取文件write_file写入文件run_python执行代码browser_open打开网页所以 Agent 的工作流程经常会变成用户输入任务 ↓ 模型判断该用什么工具 ↓ 程序调用对应工具 ↓ 拿到工具结果 ↓ 继续让模型处理问题来了工具越来越多怎么办工具参数格式不一致怎么办工具结果格式五花八门怎么办工具报错怎么办某些工具不能随便调用怎么办这时就需要一个中间层Tool Router2. 什么是 ToolTool工具可以理解成Agent 可以调用的一项外部能力。它通常有三部分名字输入参数执行逻辑例如一个搜索工具名字search输入query,top_k输出搜索结果列表一个读文件工具名字read_file输入path输出文件内容所以你可以把 Tool 理解成Agent 对外部世界的一次标准化动作。3. 什么是 Tool SchemaTool Schema就是工具的“参数合同”。它描述这个工具需要什么参数每个参数是什么类型哪些参数必填是否允许额外字段例如search的参数 Schema{type:object,properties:{query:{type:string},top_k:{type:integer,default:5}},required:[query],additionalProperties:false}这表示输入必须是对象query必须是字符串top_k如果提供必须是整数不允许乱加其他字段所以tool 真正干活的能力tool schema 对工具输入的规则说明4. 什么是 Tool RegistryTool Registry可以理解成工具目录或工具注册表。它的作用是记录系统里有哪些工具每个工具叫什么每个工具的 Schema 是什么每个工具对应哪个执行函数你可以把它想成一本电话簿search - search_tool read_file - read_file_tool write_file - write_file_tool当系统收到{tool_name:search,arguments:{query:AI agent papers}}它就可以去 registry 里查有没有search这个工具它的参数该怎么校验该调用哪个函数5. 什么是 Tool RouterTool Router可以理解成工具分发器。它做的事通常是接收工具名去 registry 查找工具校验参数调用工具统一返回结果处理错误和超时你可以把它想成快递分拣中心registry 负责记录“有哪些工具”router 负责“把这次调用分发给正确工具”所以registry 工具目录router 工具分发器schema 工具合同6. Tool Router 为什么是第一阶段最贴近 Agent 的核心因为很多“会不会做 Agent”的差别不在模型而在工具系统。一个真正可用的 Agent不只是输入 - 模型 - 文本输出而是输入 - 模型决定工具 - router 分发 - 工具执行 - 结果回流所以 Tool Router 是从“会聊天”走向“会行动”的关键一步。7. 一个工具至少应该包含什么一个最小工具通常至少包含name工具名description工具用途说明schema参数结构定义handler真正执行逻辑例如可以想象成tool{name:search,description:Search information from the web,schema:{...},handler:some_function,}当然实际工程里更适合用类或 dataclass 来表达。8. 先做一个最简单的工具函数先不急着做 router先定义最简单工具。defecho_tool(input_text:str)-str:returninput_text这是一个“原样返回输入”的工具。再写一个简单计算工具defadd_tool(a:int,b:int)-int:returnab这两个工具已经有了“输入 - 输出”的基本结构。但它们还不够工程化因为参数格式没统一没有 schema没有注册系统没有错误处理9. 用统一输入风格包装工具为了让 router 更容易处理工具通常不直接收散乱参数而是统一收一个字典。例如defecho_tool(args:dict)-str:returnargs[text]defadd_tool(args:dict)-int:returnargs[a]args[b]这样所有工具都长成类似形式tool_handler(args:dict)-Any这有利于统一调度。10. 第一个 Tool Schema 例子10.1echo工具 Schemaecho_schema{type:object,properties:{text:{type:string}},required:[text],additionalProperties:False,}10.2add工具 Schemaadd_schema{type:object,properties:{a:{type:integer},b:{type:integer}},required:[a,b],additionalProperties:False,}这些 Schema 的作用是echo工具必须传textadd工具必须传a和b不允许多出奇怪字段11. 为什么参数校验必须在 Router 里做你可以把参数校验放在工具内部但更推荐放在 Router 层统一做。原因是工具本身专注“执行逻辑”Router 负责“入口把关”可以统一报错格式可以统一记录日志可以避免每个工具都重复写一遍校验所以更合理的分工是tool干活router调度 校验 兜底12. 返回值标准化是什么不同工具如果直接返回原始结果很快会乱。例如echo返回字符串add返回整数search返回列表read_file返回文件内容字符串如果每个工具格式都不同后面的 Agent 主循环会变复杂。所以通常要做返回值标准化例如统一返回{ok:True,tool_name:echo,data:hello}或者失败时{ok:False,tool_name:echo,error:missing field: text}这样上层程序就能统一处理而不是每个工具都单独分支。13. 为什么错误处理必须标准化工具出错是非常正常的参数不合法文件不存在网络失败权限不够工具超时未知异常如果不统一错误格式就会出现某些工具抛异常某些工具返回字符串error某些工具返回None这样上层非常难处理。所以 Tool Router 应该尽量统一成一种返回格式例如{ok:False,tool_name:read_file,error:file not found}这会让整个系统稳定很多。14. timeout超时timeout超时的意思是一个工具最多运行多久。有些工具会卡住例如搜索 API 没返回浏览器页面一直在加载外部命令挂住某个模型服务太慢如果不设超时一个工具就可能拖死整个 Agent。所以 Router 层通常要考虑给每个工具设置超时超时后统一报错不要无限等待在异步工具里常见做法是awaitasyncio.wait_for(tool_handler(args),timeout5)15. 权限边界是什么不是所有工具都应该随便调用。例如read_file可能只能读特定目录write_file可能只能写工作区run_shell可能风险很高browser_open可能只允许访问白名单域名所以你要理解一个很重要的概念Tool Router 不只是分发器还是权限边界的一部分。它可以负责检查工具是否允许当前任务调用检查参数是否访问了危险路径拒绝高风险请求给出统一错误信息这对真正的 Agent 系统非常关键。16. 一个最小 Tool Router 的结构长什么样一个最小 Tool Router通常会包含这些步骤输入tool_name和arguments去 registry 查找工具如果没找到返回错误用 schema 校验参数执行 handler统一包装返回值捕获异常并包装错误这就是它的核心流程。17. 第一个最小 Registry 版本先不用类先用字典表示 registry。registry{echo:{schema:echo_schema,handler:echo_tool,},add:{schema:add_schema,handler:add_tool,},}这个结构已经表达了工具名工具 Schema工具执行函数后面你再扩展descriptiontimeoutpermission leveltags就可以变成更完整的工具注册系统。18. 用jsonschema做参数校验安装pipinstalljsonschema然后校验参数fromjsonschemaimportvalidate validate(instance{text:hello},schemaecho_schema)如果数据符合 Schema不会报错。如果不符合就会抛ValidationError。19. 第一个最小 Router 函数下面先写一个最小版本。fromjsonschemaimportvalidatefromjsonschema.exceptionsimportValidationErrordefroute_tool_call(tool_name:str,arguments:dict)-dict:iftool_namenotinregistry:return{ok:False,tool_name:tool_name,error:fUnknown tool:{tool_name},}toolregistry[tool_name]try:validate(instancearguments,schematool[schema])exceptValidationErrorase:return{ok:False,tool_name:tool_name,error:fInvalid arguments:{e.message},}try:resulttool[handler](arguments)return{ok:True,tool_name:tool_name,data:result,}exceptExceptionase:return{ok:False,tool_name:tool_name,error:fTool execution failed:{e},}这已经是一个最小可用的 Tool Router 了。20. 稍复杂代码逐段解释上面的route_tool_call(...)是这一课最关键的函数我们拆开看。20.1 检查工具是否存在iftool_namenotinregistry:return{ok:False,tool_name:tool_name,error:fUnknown tool:{tool_name},}解释如果 registry 里没有这个名字就直接返回错误不继续执行这一步相当于先确认系统里真的有这个工具。20.2 取出工具定义toolregistry[tool_name]解释从工具目录里拿到这个工具的完整定义后面就能访问它的 schema 和 handler20.3 校验参数validate(instancearguments,schematool[schema])解释instancearguments表示要校验的实际输入数据schematool[schema]表示这个工具自己的参数规则如果校验失败会抛异常所以要配合try/except。20.4 执行工具resulttool[handler](arguments)解释取出工具处理函数把参数字典传给它得到执行结果20.5 标准化返回值return{ok:True,tool_name:tool_name,data:result,}解释ok表示是否成功tool_name表示是哪个工具data表示成功结果这样上层就不需要猜这个工具返回了什么格式。21. 小项目最小 Tool Router现在把这一课串起来。21.1 文件tool_router_demo.pyfromjsonschemaimportvalidatefromjsonschema.exceptionsimportValidationErrordefecho_tool(args:dict)-str: 最简单的 echo 工具原样返回输入文本。 returnargs[text]defadd_tool(args:dict)-int: 最简单的计算工具返回 a b 的结果。 returnargs[a]args[b]echo_schema{type:object,properties:{text:{type:string}},required:[text],additionalProperties:False,}add_schema{type:object,properties:{a:{type:integer},b:{type:integer}},required:[a,b],additionalProperties:False,}registry{echo:{description:Return the input text as-is,schema:echo_schema,handler:echo_tool,},add:{description:Add two integers,schema:add_schema,handler:add_tool,},}defroute_tool_call(tool_name:str,arguments:dict)-dict: Tool Router 的核心函数。 它负责 1. 查找工具 2. 校验参数 3. 调用工具 4. 标准化返回结果 iftool_namenotinregistry:return{ok:False,tool_name:tool_name,error:fUnknown tool:{tool_name},}toolregistry[tool_name]try:validate(instancearguments,schematool[schema])exceptValidationErrorase:return{ok:False,tool_name:tool_name,error:fInvalid arguments:{e.message},}try:resulttool[handler](arguments)return{ok:True,tool_name:tool_name,data:result,}exceptExceptionase:return{ok:False,tool_name:tool_name,error:fTool execution failed:{e},}defmain(): 这里演示三种情况 1. 正常调用 echo 2. 正常调用 add 3. 非法参数调用 add print(调用 echo)print(route_tool_call(echo,{text:hello agent}))print(\n调用 add)print(route_tool_call(add,{a:3,b:5}))print(\n非法调用 add)print(route_tool_call(add,{a:3,b:five}))print(\n调用不存在的工具)print(route_tool_call(search,{query:AI agent}))if__name____main__:main()22. 这段代码里你已经学到了什么你已经练到了工具的最小抽象工具参数 Schemaregistry 结构router 分发逻辑参数校验标准化返回值工具错误处理未知工具处理这其实已经是一个“最小 Agent 工具系统”了。23. 如果工具是异步的怎么办很多真实工具不是同步函数而是异步函数比如搜索 API浏览器操作模型调用数据库查询它们更像这样asyncdefsearch_tool(args:dict)-dict:...那 Router 也要变成异步asyncdefroute_tool_call(tool_name:str,arguments:dict)-dict:...resultawaittool[handler](arguments)这就是为什么前面几课学的asyncio会和 Tool Router 自然接上。24. timeout 应该怎么接进 Router异步版本通常会这样写resultawaitasyncio.wait_for(tool[handler](arguments),timeout5)这表示最多等 5 秒超时就报错以后更完整的 registry 可以长这样registry{search:{schema:search_schema,handler:search_tool,timeout:10,}}然后 Router 根据不同工具的配置自动套不同超时。25. 权限边界应该怎么接进 Router以后你可以给工具加上权限级别例如registry{read_file:{schema:read_file_schema,handler:read_file_tool,permission:workspace,},run_shell:{schema:shell_schema,handler:run_shell_tool,permission:dangerous,},}然后 Router 根据当前模式决定是否允许调用是否需要用户确认是否拒绝执行所以从长期来看Tool Router 不只是调度层还是安全层协议层稳定性层26. 你应该怎么练第一次练习把echo和add跑通。第二次练习自己加一个multiply工具输入a,b输出乘积给它写 Schema注册到 registry第三次练习自己加一个read_file工具参数path输出文件内容做最简单的异常处理第四次练习把返回结果统一扩展成{ok:True,tool_name:...,data:...,error:None}失败时{ok:False,tool_name:...,data:None,error:...}第五次练习把 Router 改造成异步版本为后面接搜索 API 做准备。27. 这节课你真正应该记住的东西Tool 是 Agent 的行动能力。Tool Schema 是工具输入合同。Tool Registry 是工具目录。Tool Router 是工具分发器。Router 的职责不只是“找到工具”还包括参数校验错误处理返回值标准化超时控制权限边界工具系统如果没有 Schema很快就会失控。Tool Router 是从“会聊天的模型”走向“会干活的 Agent”的关键结构。