AgentKit搭建智能体工具调用异常处理方案

工具调用失败常因Schema校验不通过：必填字段缺失或类型不匹配（如字符串传入float字段）会静默拒绝；需检查Pydantic Model类型标注，打印实际输入对比；超时需工具内加timeout或配置retry_policy；兜底响应链需设置fallback_tool并实现无依赖的handle_tool_failure工具。

确认工具调用失败是否由Schema校验触发

打开你注册工具时定义的Pydantic Model类，查看每个字段是否都标注了类型，以及是否带有Field(...)或Field(default=None)。AgentKit在调用前，会严格校验输入字典是否与该Schema完全匹配。

在工具函数内部的第一行，插入这样一段代码：print(f"Received input: {input_dict}")。接着，运行一次会触发失败的请求，然后仔细对比打印出来的实际参数与Model的定义。这里有个常见的坑需要注意，前端可能会传递一个像"threshold": "0.5"这样的字符串参数，然而Schema却要求是float类型。

捕获并重试超时类工具调用

AgentKit默认不内置网络超时控制，若你的工具封装了HTTP请求或数据库查询，需手动加装timeout逻辑。

方法一：用requests.get(url, timeout=8)替代裸调用，捕获requests.exceptions.Timeout后返回结构化错误字典{"error": "timeout", "detail": "API响应超时"}；

方法二：在AgentKit配置中启用retry_policy，设置max_retries=2和backoff_factor=1.5，但注意这仅对框架层可识别的ToolExecutionError生效，原始网络异常仍需工具内处理。

构建工具调用失败的兜底响应链

第一步：在AgentKit的AgentRunner初始化时，传入fallback_tool="handle_tool_failure"参数；

第二步：定义handle_tool_failure工具，它接收原始失败工具名、输入参数、错误消息三字段，返回自然语言解释（如“查设备状态失败，请稍后重试”）；

第三步：确保该工具本身无外部依赖、无IO操作、执行耗时<50ms——否则兜底链自身可能再次失败，导致整个智能体流程中断。