AI SDK工具包修复网络请求错误处理

简介

AI SDK 团队发布了 @ai-sdk/tool-web-fetch 的 1.0.10 版本，这是一个针对网页抓取工具的补丁更新。该版本主要修复了当重定向响应包含无效 Location 头时，工具会抛出异常的问题。现在，工具会返回一个 network_error 结果，而不是直接抛出错误，这提高了工具的健壮性和错误处理的连贯性。

AI SDK 工具（tool）机制：在 Vercel AI SDK 中，工具是带有 description、inputSchema 与 execute 函数的对象，模型通过结构化调用决定何时使用它，SDK 负责参数校验与结果回传。@ai-sdk/tool-web-fetch 属于预置工具包，把"抓取网页正文"这一常见能力封装为可直接挂载到 tools 参数的工具。其设计惯例是：可恢复的失败（网络不可达、DNS 失败、无效重定向）以带类型的错误结果返回给模型，由模型决定重试或换源；只有编程错误才抛出异常。理解这一约定，才能明白为何"不抛异常而返回 network_error"是一次语义层面的修正，而非单纯的 bug 修补。

修复内容

根据 GitHub 发布说明，本次补丁（提交 dffe405）修改了 tool-web-fetch 的行为：当遇到带有无效 Location 头的重定向时，不再抛出异常，而是返回 network_error 结果。这意味着开发者在使用该工具进行网页抓取时，可以更优雅地处理网络错误，避免因未捕获的异常导致程序中断。

重定向与 Location 头：HTTP 重定向（状态码如 301、302、307、308）依赖响应头中的 Location 字段告诉客户端下一个请求地址。按 RFC 9110 规范，该值应为合法的 URI 引用；但现实中服务器可能返回空值、相对路径、含非法字符或不可解析的字符串。fetch 规范要求客户端在无法解析 Location 时以网络错误（TypeError）失败，因此抓取工具若直接透传底层异常，就会把"服务器配置问题"升级为"程序崩溃"。本补丁的关键在于把这类解析失败归类为可预期的 network_error 结果，让调用方用统一的错误分支处理，而不是依赖 try/catch 兜底。

依赖更新

此次发布还更新了相关依赖，包括 ai@7.0.160 等。这些依赖更新可能包含其他修复或改进，但发布说明中未详细列出。开发者应确保其项目中的依赖版本兼容。

总结

这是一个小型但重要的修复，提升了 tool-web-fetch 在网络请求异常情况下的稳定性。对于依赖该工具进行网页抓取的 AI 应用来说，这一改动可以减少因网络问题导致的崩溃，建议开发者升级到最新版本。