[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Execution, Tool Timeout

Tool Error Handling

一句话定义

Tool Error Handling 是工具执行失败时的处理策略。不是简单地返回”出错了”，而是要分类错误、决定是否重试、格式化错误信息让 LLM 能理解和处理。

核心原理

错误分类

错误类型	例子	处理策略
参数错误	格式不对	返回错误，让 LLM 修复参数
超时	执行太慢	重试或降级
权限不足	无权访问	返回错误，不要重试
资源不存在	记录不存在	返回错误，让 LLM 告知用户
服务不可用	API 挂了	重试或 Fallback
未知错误	其他异常	返回错误信息

Python 实现

class ToolErrorHandler:
    def __init__(self, max_retries: int = 2):
        self.max_retries = max_retries

    async def handle(self, tool: Tool, args: dict, context: ExecutionContext) -> ToolResult:
        last_error = None

        for attempt in range(self.max_retries + 1):
            try:
                result = await execute_tool(tool, args, context)
                return result
            except ValidationError as e:
                # 参数错误，不重试
                return ToolResult(error=f"参数错误: {e}")
            except TimeoutError as e:
                last_error = f"超时 ({tool.timeout}s)"
                if attempt < self.max_retries:
                    continue
            except PermissionError as e:
                # 权限错误，不重试
                return ToolResult(error=f"权限不足: {e}")
            except Exception as e:
                last_error = str(e)
                if attempt < self.max_retries:
                    await asyncio.sleep(2 ** attempt)
                    continue

        return ToolResult(error=f"工具执行失败: {last_error}")

错误信息格式化

def format_error_for_llm(error: Exception, tool_name: str) -> str:
    """格式化错误信息让 LLM 能理解"""
    return f"""
工具 {tool_name} 执行失败。
错误类型: {type(error).__name__}
错误信息: {str(error)}
请根据错误信息决定下一步操作。
"""

常见坑

1. 不分类错误: 所有错误都重试
2. 错误信息太技术化: LLM 看不懂
3. 不反馈给 LLM: 错误后直接放弃，不让 LLM 处理
4. 无限重试: 没有最大重试次数

参考资料

• Tool Execution
• Retry Policy