AI SDK Perplexity 5.0.0 Major Update: Migrating from Sonar to Agent API

Vercel's popular open-source project AI SDK has released @ai-sdk/perplexity@5.0.0. This is a major update containing breaking changes, with the core change being a complete migration of language generation capabilities from Perplexity's Sonar Chat Completions API to the new Agent API. For developers relying on the Perplexity integration, this upgrade means adjustments to API call patterns, model identifiers, and response data structures.

Core Change: Goodbye Sonar, Hello Agent API

The most critical breaking change in this release is the complete switch of the underlying API. The previous version used the Sonar Chat Completions API for text generation, while version 5.0.0 adopts the Agent API, replacing the original Sonar model IDs and provider options with Agent API presets, models, and tools.

The impact of this change is broad. The official release notes explicitly state that the new API modifies request and response metadata, raw stream events, usage, and cost data structures. More importantly, the new version no longer supports Sonar's PDF input capability and no longer returns image and video results. This means that if your application previously relied on Sonar for processing PDF documents or retrieving multimedia results, you'll need to re-evaluate your technical approach after upgrading to 5.0.0.

The Trade-offs of Migration

The shift from the Chat Completions paradigm to the Agent API fundamentally reflects the evolution of Perplexity's product direction — moving from pure conversational completion toward an Agent-centric orchestration capability with tool-calling support. Developers gain more granular control over presets and tools, at the cost of losing compatibility with some existing input/output formats. This kind of trade-off is quite common in the rapidly iterating AI infrastructure landscape.

The Sonar Chat Completions API was Perplexity's early external interface, following an OpenAI Chat Completions-compatible request/response format where developers could initiate conversations using familiar messages arrays and receive citation-backed answers. Its core model series (e.g., sonar-small, sonar-large) essentially layered real-time web search capabilities on top of large language models. The Agent API represents Perplexity's next-generation interface paradigm: instead of single-turn or multi-turn conversation completion, it encapsulates "search," "tool calls," and "reasoning" capabilities as composable modules, unified through platform-side Agent orchestration. This design allows Perplexity to flexibly combine different retrieval tools on the server side (such as financial data sources, academic databases, etc.) without exposing all capabilities as client-side parameter options — at the cost of clients no longer being able to directly control the underlying model's behavioral details.

Patch Improvements: More Robust Text Recovery and Citation Handling

Beyond the main change, 5.0.0 also includes several patch fixes for Agent API adaptation, focused on two areas: text integrity and citation attribution.

On the text processing side, the new version can recover missing text from Agent API terminal events and output items, including incomplete responses, while avoiding duplication of content already received via deltas. To achieve this, the SDK tracks each content part of each message individually, ensuring accurate text concatenation in streaming scenarios.

On the tool tracking side, the SDK can now accept Agent API native tool traces — such as finance results — without incorrectly treating them as web search results to be validated. These traces are preserved intact in both raw responses and stream chunks, providing better support for applications that need to handle structured tool output.

In streaming scenarios, servers typically push generated content in batches (deltas) to clients via Server-Sent Events (SSE) or similar protocols. When network anomalies occur or the model terminates early, clients may only receive partial deltas, resulting in incomplete concatenated text. The Agent API's terminal events mechanism works like a "final snapshot" — sending the complete output state at stream end, which the SDK can use to fill in fragments missing due to packet loss or premature truncation. Tracking each content part of each message individually handles cases with multiple tool calls or parallel multi-segment outputs: text fragments from different sources may arrive out of order, and tracking by part ID independently ensures the final concatenation order is correct, avoiding duplicate appending of content already received via deltas during terminal events.

Enhanced Citation and Source Attribution

Citation handling is a major focus of this patch release, and is especially important for services like Perplexity that market themselves on "answers with sources."

The new version retains URL citation annotations as sources in Agent API streaming output, covering both completed and incomplete terminal responses. More precisely, the SDK guarantees that each Agent API source URL is emitted only once, while preserving search result IDs for citation association — even if a URL was crawled or annotated before it officially appeared in search results, it can still be correctly matched.

These improvements may seem minor but directly affect the quality of answers seen by end users. Poor citation deduplication and ID association can result in the same source being listed repeatedly, or citations not matching their content, damaging product credibility.

In Perplexity's responses, "citations" typically exist in two forms: inline citation annotations embedded in the body text, marking which URL a passage came from; and a sources list summarized at the end of the response, listing all referenced web pages. The search result ID is the key connecting these two: each search result has a unique internal identifier in the API, and inline annotations point to specific entries in the source list by referencing that ID. When a URL is pre-fetched (for example, when the system has pre-retrieved page content and generated annotations before the formal search results list is generated), if the ID mapping relationship is not correctly maintained, dangling annotations can occur — where a citation exists but no corresponding entry can be found in the source list. This fix ensures ID association consistency throughout streaming scenarios.

Practical Impact for Developers

Overall, @ai-sdk/perplexity@5.0.0 is a "two steps forward, one step back" upgrade. It keeps AI SDK's Perplexity integration in sync with Perplexity's Agent API direction, gaining stronger tool-calling and citation handling capabilities; but the breaking changes and feature removals (PDF input, image and video results) also require existing projects to conduct proper regression testing before upgrading.

Vercel's AI SDK has accumulated over 27k stars and 5.2k forks on GitHub, making it one of the mainstream toolchains for building AI applications. For projects in production environments, it's recommended to first verify the request/response format changes of the new API on a test branch, confirm whether usage and cost calculation logic needs to be updated accordingly, and then consider the official upgrade.