AI SDK Perplexity 5.0.0 重大更新：从 Sonar 迁移至 Agent API

Vercel 旗下热门开源项目 AI SDK 发布了 @ai-sdk/perplexity@5.0.0 版本。这是一次包含破坏性变更（Breaking Change）的重大更新，核心是将语言生成能力从 Perplexity 的 Sonar Chat Completions API 全面迁移到全新的 Agent API。对于依赖 Perplexity 集成的开发者而言，这次升级意味着接口调用方式、模型标识、返回数据结构都需要相应调整。

核心变更：告别 Sonar，拥抱 Agent API

此次版本最关键的破坏性变更（BREAKING）在于底层 API 的整体切换。旧版本基于 Sonar Chat Completions API 完成文本生成，而 5.0.0 版本改用 Agent API，并以 Agent API 的预设（presets）、模型（models）和工具（tools）取代了原有的 Sonar 模型 ID 与 provider options。

这一变化的影响面较广。官方在发布说明中明确指出，新 API 修改了请求与响应的元数据、原始流事件（raw stream events）、用量（usage）和成本（cost）数据结构。更需要注意的是，新版本不再支持 Sonar 的 PDF 输入能力，也不再返回图片和视频结果。这意味着如果你的应用此前依赖 Sonar 处理 PDF 文档或获取多媒体检索结果，升级到 5.0.0 后需要重新评估技术方案。

迁移带来的取舍

从 Chat Completions 范式转向 Agent API，本质上反映了 Perplexity 产品方向的演进——从单纯的对话补全，转向以 Agent（智能体）为核心的、可调用工具的编排能力。开发者获得了对预设与工具更细粒度的控制，代价则是失去了部分原有输入输出格式的兼容性。这种取舍在 AI 基础设施快速迭代的当下相当常见。

Sonar Chat Completions API 是 Perplexity 早期对外暴露的接口形态，遵循与 OpenAI Chat Completions 兼容的请求/响应格式，开发者可以用熟悉的 messages 数组发起对话并获取带引用的回答。其核心模型系列（如 sonar-small、sonar-large）本质上是在大语言模型之上叠加了实时网络检索能力。Agent API 则代表 Perplexity 的下一代接口范式：不再是单轮或多轮对话补全，而是将「搜索」「工具调用」「推理」等能力封装为可组合的模块，由平台侧以 Agent 编排的方式统一调度。这种设计让 Perplexity 能够在服务端灵活组合不同的检索工具（如金融数据源、学术数据库等），而不必将所有能力都暴露为用户侧的参数选项，代价是客户端无法再直接控制底层模型的细节行为。

补丁改进：更稳健的文本恢复与引用处理

除了主变更外，5.0.0 还包含了多项针对 Agent API 适配的补丁修复，集中在文本完整性和引用溯源两个方向。

在文本处理方面，新版本能够从 Agent API 的终端事件（terminal events）和输出项中恢复缺失的文本，包括未完成的响应（incomplete responses），同时避免重复已通过增量（deltas）接收的内容。为实现这一点，SDK 会单独追踪每条消息的各个内容片段，从而在流式输出场景下保证文本拼接的准确性。

在工具追踪方面，SDK 现在能够接受 Agent API 的原生工具轨迹（tool traces），例如金融数据（finance results），并且不会错误地将其当作网页搜索结果去校验。这些轨迹会被完整保留在原始响应和流式分块中，为需要处理结构化工具输出的应用提供了更好的支持。

流式输出（Streaming）场景下，服务端通常以 Server-Sent Events（SSE）或类似协议将生成内容分批（delta）推送给客户端。当网络异常或模型提前终止时，客户端可能只收到部分 delta，导致拼接后的文本不完整。Agent API 的终端事件（terminal events）机制类似于一个「最终快照」——在流结束时发送完整的输出状态，SDK 可以用它来补全因丢包或提前截断而缺失的片段。单独追踪每条消息的各个内容片段（content parts），则是为了处理多工具调用或多段并行输出的情况：不同来源的文本片段可能乱序到达，按片段 ID 独立追踪可以确保最终拼接顺序正确，避免将已经通过 delta 接收的内容在终端事件中重复追加。

引用与来源溯源的增强

引用（citation）处理是这次补丁的重点之一，对于 Perplexity 这类以「带来源的答案」为卖点的服务尤为重要。

新版本会将 URL 引用注解（URL citation annotations）作为来源（sources）保留在 Agent API 的流式输出中，涵盖已完成和未完成的终端响应两种情况。更精细的是，SDK 保证每个 Agent API 来源 URL 只发出一次，同时保留搜索结果 ID 以便进行引用关联——即便某个 URL 在正式出现在搜索结果之前，就已经被抓取或注解，也能正确对应。

这类改进看似琐碎，实则直接关系到最终用户看到的答案质量。引用去重和 ID 关联做得不好，就可能出现同一来源反复列出、或引用与内容对不上的问题，损害产品可信度。

在 Perplexity 的返回结果中，「引用」通常以两种形式存在：一是嵌入在正文中的内联注解（inline citation annotation），标注某段话来自哪个 URL；二是响应末尾汇总的来源列表（sources list），列出所有被引用的网页。搜索结果 ID（search result ID）是连接这两者的关键：每条搜索结果在 API 内部有一个唯一标识，内联注解通过引用该 ID 指向来源列表中的具体条目。当某个 URL 被提前抓取（例如在正式搜索结果列表生成之前，系统已经预取了该页面内容并生成注解）时，如果没有正确维护 ID 的映射关系，就会出现注解悬空——引用存在但来源列表中找不到对应条目的问题。此次修复保证了 ID 关联在流式场景下的全程一致性。

对开发者的实际影响

综合来看，@ai-sdk/perplexity@5.0.0 是一次「进两步、退一步」的升级。它让 AI SDK 对 Perplexity 的集成与后者的 Agent API 方向保持同步，获得了更强的工具调用与引用处理能力；但破坏性变更和功能删减（PDF 输入、图片视频结果）也要求现有项目在升级前做好回归测试。

Vercel 的 AI SDK 在 GitHub 上已积累超过 27k Star、5.2k Fork，是构建 AI 应用的主流工具链之一。对于生产环境中的项目，建议先在测试分支验证新 API 的请求响应格式变化，确认 usage 与 cost 统计逻辑是否需要同步调整，再考虑正式升级。