@ai-sdk/perplexity 3.0.63 → 3.1.1

package/docs/70-perplexity.mdx

@@ -1,11 +1,13 @@
 ---
 title: Perplexity
-description: Learn how to use Perplexity's Sonar API with the AI SDK.
+description: Learn how to use Perplexity's Agent API with the AI SDK.
 ---
 
 # Perplexity Provider
 
-The [Perplexity](https://sonar.perplexity.ai) provider offers access to Sonar API - a language model that uniquely combines real-time web search with natural language processing. Each response is grounded in current web data and includes detailed citations, making it ideal for research, fact-checking, and obtaining up-to-date information.
+The [Perplexity](https://www.perplexity.ai) provider offers access to the
+[Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart). The Agent API
+can route across models, search the web, call tools, and return cited answers.
 
 API keys can be obtained from the [Perplexity Platform](https://docs.perplexity.ai).
 
@@ -76,11 +78,20 @@ import { perplexity } from '@ai-sdk/perplexity';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: perplexity('sonar-pro'),
+  model: perplexity('low'),
   prompt: 'What are the latest developments in quantum computing?',
 });
 ```
 
+The Agent API provides the `fast`, `low`, `medium`, `high`, and `xhigh`
+presets. You can also pass an Agent API model ID directly, such as
+`perplexity/sonar`.
+
+Starting with version 3.1.0, language generation uses the Agent API
+exclusively. Legacy Sonar model IDs and provider options are not mapped; see
+[Migrating from Sonar to the Agent API](#migrating-from-sonar-to-the-agent-api)
+before upgrading.
+
 ### Sources
 
 Websites that have been used to generate the response are included in the `sources` property of the result:
@@ -90,27 +101,101 @@ import { perplexity } from '@ai-sdk/perplexity';
 import { generateText } from 'ai';
 
 const { text, sources } = await generateText({
-  model: perplexity('sonar-pro'),
+  model: perplexity('low'),
   prompt: 'What are the latest developments in quantum computing?',
 });
 
 console.log(sources);
 ```
 
-### Provider Options & Metadata
+### Agent Tools
+
+Pass native Agent API tools through `providerOptions.perplexity.tools`:
+
+```ts
+import {
+  perplexity,
+  type PerplexityLanguageModelOptions,
+} from '@ai-sdk/perplexity';
+import { generateText } from 'ai';
+
+const { text, sources } = await generateText({
+  model: perplexity('low'),
+  prompt: 'Summarize recent US federal AI policy from official sources.',
+  providerOptions: {
+    perplexity: {
+      tools: [
+        {
+          type: 'web_search',
+          filters: {
+            search_domain_filter: [
+              'whitehouse.gov',
+              'congress.gov',
+              'federalregister.gov',
+            ],
+            search_recency_filter: 'month',
+          },
+          max_results: 10,
+          search_context_size: 'medium',
+        },
+      ],
+    } satisfies PerplexityLanguageModelOptions,
+  },
+});
+```
+
+Supported native tools are `web_search`, `fetch_url`, `people_search`,
+`finance_search`, `sandbox`, `mcp`, and `connector`. Agent API presets include
+preconfigured tools that remain enabled; the `tools` option can add explicit
+tools or supply tools when using a direct model ID.
+
+Search and fetch results are exposed as AI SDK sources. Other native tool traces,
+including finance, sandbox, and MCP results, are available in `response.body`
+and raw stream chunks (`includeRawChunks: true`). They are not exposed as
+AI SDK client tool calls. Accounts with zero data retention may reject
+file-capable tools such as `finance_search` and `sandbox`.
+
+AI SDK function tools can be passed through the top-level `tools` option:
+
+```ts
+import { perplexity } from '@ai-sdk/perplexity';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: perplexity('low'),
+  prompt: 'What is the weather in San Francisco?',
+  tools: {
+    weather: tool({
+      description: 'Get the weather for a city',
+      inputSchema: z.object({ city: z.string() }),
+      execute: async ({ city }) => ({ city, temperature: 18 }),
+    }),
+  },
+});
+```
+
+### Provider Options and Metadata
 
 The Perplexity provider includes additional metadata in the response through `providerMetadata`.
 Additional configuration options are available through `providerOptions`.
 
 ```ts
+import {
+  perplexity,
+  type PerplexityLanguageModelOptions,
+} from '@ai-sdk/perplexity';
+import { generateText } from 'ai';
+
 const result = await generateText({
-  model: perplexity('sonar-pro'),
+  model: perplexity('low'),
   prompt: 'What are the latest developments in quantum computing?',
   providerOptions: {
     perplexity: {
-      return_images: true, // Enable image responses (Tier-2 Perplexity users only)
-      search_recency_filter: 'week', // Filter search results by recency
-    },
+      max_steps: 5,
+      store: true,
+      reasoning: { effort: 'low' },
+    } satisfies PerplexityLanguageModelOptions,
   },
 });
 
@@ -118,87 +203,161 @@ console.log(result.providerMetadata);
 // Example output:
 // {
 //   perplexity: {
-//     usage: { citationTokens: 5286, numSearchQueries: 1 },
-//     images: [
-//       { imageUrl: "https://example.com/image1.jpg", originUrl: "https://elsewhere.com/page1", height: 1280, width: 720 },
-//       { imageUrl: "https://example.com/image2.jpg", originUrl: "https://elsewhere.com/page2", height: 1280, width: 720 }
-//     ]
+//     usage: { citationTokens: null, numSearchQueries: 1 },
+//     images: null,
+//     cost: { totalCost: 0.006, currency: 'USD', ... },
+//     toolCalls: { search_web: { invocation: 1 } },
 //   },
 // }
 ```
 
 #### Provider Options
 
-The following provider-specific options are available:
+The following Agent API options are available:
+
+- **instructions** _string_
+
+  Top-level instructions for the Agent API run.
+
+- **tools** _array_
+
+  Native Agent API tools and their configuration.
 
-- **return_images** _boolean_
+- **models** _string[]_
 
-  Enable image responses. When set to `true`, the response may include relevant images. This feature is only available to Perplexity Tier-2 users and above.
+  A fallback model list for Agent API routing.
 
-- **search_recency_filter** _string_
+- **max_steps** _number_
 
-  Filter search results by recency. Possible values: `'hour'`, `'day'`, `'week'`, `'month'`. If not specified, defaults to all time.
+  The maximum number of agentic steps.
+
+- **max_tool_calls** _number_
+
+  The maximum number of native tool calls. Setting this to `0` disables all
+  preset tools.
+
+- **previous_response_id** _string_
+
+  Continue a conversation from an earlier Agent API response.
+
+- **store** _boolean_
+
+  Whether the response can be retrieved later. Setting `store: false` hides it
+  from retrieval; it does not disable persistence, and the response can still
+  be used as a `previous_response_id` continuation source. See Perplexity's
+  [conversation state documentation](https://docs.perplexity.ai/docs/agent-api/conversation-state)
+  for retention behavior and account-specific zero data retention restrictions.
+
+- **language_preference** _string_
+
+  Preferred response language as an ISO 639-1 language code.
+
+- **reasoning** _object_
+
+  Reasoning configuration. `effort` supports `'minimal'`, `'low'`, `'medium'`,
+  `'high'`, and `'xhigh'`.
+
+- **skills** _array_
+
+  Agent API skill configuration.
 
 <Note>
-  Any other [Perplexity API
-  parameters](https://docs.perplexity.ai/api-reference/chat-completions) can
-  also be passed through `providerOptions.perplexity`.
+  See the [Perplexity Agent API
+  documentation](https://docs.perplexity.ai/docs/agent-api/quickstart) for
+  details about native request fields.
 </Note>
 
 #### Provider Metadata
 
 The response metadata includes:
 
-- `usage`: Object containing `citationTokens` and `numSearchQueries` metrics
-- `images`: Array of image objects when `return_images` is enabled (Tier-2 users only). Each image contains `imageUrl`, `originUrl`, `height`, and `width`.
+- `usage`: `citationTokens` (always `null` for Agent API responses) and the
+  number of search queries
+- `cost`: Token, tool, and total costs returned by Perplexity
+- `toolCalls`: Invocation counts grouped by native tool
+- `images`: Always `null`; the Agent API does not return Sonar image results
 
-### PDF Support
+### Structured Output
 
-The Perplexity provider supports reading PDF files.
-You can pass PDF files as part of the message content using the `file` type:
+`Output.object` and `Output.array` send an Agent API JSON schema response
+format. JSON output without a schema is not supported.
 
-```ts
-const result = await generateText({
-  model: perplexity('sonar-pro'),
-  messages: [
-    {
-      role: 'user',
-      content: [
-        {
-          type: 'text',
-          text: 'What is this document about?',
-        },
-        {
-          type: 'file',
-          data: fs.readFileSync('./data/ai.pdf'),
-          mediaType: 'application/pdf',
-          filename: 'ai.pdf', // optional
-        },
-      ],
-    },
-  ],
-});
-```
+### Input Images
 
-You can also pass the URL of a PDF:
+Image URL and data inputs are converted to Agent API `input_image` parts.
+The Agent API does not provide a Sonar-equivalent PDF input field, so PDF file
+parts are not supported.
 
-```ts
-{
-  type: 'file',
-  data: new URL('https://example.com/document.pdf'),
-  mediaType: 'application/pdf',
-  filename: 'document.pdf', // optional
-}
-```
-
-The model will have access to the contents of the PDF file and
-respond to questions about it.
+### Migrating from Sonar to the Agent API
 
 <Note>
-  For more details about Perplexity's capabilities, see the [Perplexity chat
-  completion docs](https://docs.perplexity.ai/api-reference/chat-completions).
+  Version 3.1.0 is a breaking migration from Sonar Chat Completions to the
+  Agent API. It does not provide legacy model aliases, translate Sonar provider
+  options, or emit migration warnings at runtime.
+</Note>
+
+<Note type="warning">
+  Perplexity supports Sonar Chat Completions only until September 27, 2026.
+  Upgrade language-generation applications to the Agent API before that date;
+  staying on version 3.0.63 or earlier does not preserve service after the
+  Sonar shutdown.
 </Note>
 
+Replace each Sonar model ID with an Agent API preset or direct Agent API model
+ID. These presets are suggested starting points, not equivalent aliases: a
+preset can select different models and tools, so cost, latency, and output can
+change.
+
+| Sonar model           | Suggested Agent API starting point |
+| --------------------- | ---------------------------------- |
+| `sonar`               | `fast`                             |
+| `sonar-pro`           | `low`                              |
+| `sonar-reasoning`     | `medium`                           |
+| `sonar-reasoning-pro` | `medium`                           |
+| `sonar-deep-research` | `high`                             |
+
+For example:
+
+```ts
+// 3.0.63 and earlier (Sonar)
+perplexity('sonar-pro');
+
+// 3.1.0 and later (Agent API)
+perplexity('low');
+```
+
+Move Sonar search and reasoning options to their Agent API locations:
+
+| Sonar provider option                    | Agent API option                       |
+| ---------------------------------------- | -------------------------------------- |
+| Domain, recency, and date filters        | `tools[].filters` on `web_search`      |
+| `num_search_results`                     | `tools[].max_results`                  |
+| `web_search_options.search_context_size` | `tools[].search_context_size`          |
+| `web_search_options.user_location`       | `tools[].user_location`                |
+| `reasoning_effort`                       | `reasoning.effort`                     |
+| `disable_search`                         | Omit `web_search` for direct model IDs |
+
+Preset tools cannot be removed individually. Use a direct model ID without a
+`web_search` tool when search must be disabled, or set `max_tool_calls: 0` to
+disable all preset tool calls.
+
+The Agent API has no equivalent for Sonar PDF or video inputs, image or video
+results, `search_language_filter`, or `stream_mode`. Related questions require
+prompting or structured output. Remove these options during migration.
+
+Language requests now use `/v1/agent`. Custom `baseURL` proxies must route that
+path. Raw responses and streams use the Agent API's typed output and SSE event
+formats, and Perplexity provider metadata, usage, cost, and source identifiers
+can differ. The embeddings API is unchanged.
+
+For PDF inputs, extract the document text before sending it to the Agent API,
+or choose another provider that supports PDF input. Move image/video retrieval
+and language-filtered search to a separate service if your application requires
+those features. Rework consumers of raw Sonar stream events for typed Agent
+events. See Perplexity's [migration
+guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to)
+for the full API-level comparison.
+
 ## Embedding Models
 
 You can create models that call the [Perplexity embeddings API](https://docs.perplexity.ai/docs/embeddings/quickstart)
@@ -274,13 +433,13 @@ The following optional provider options are available for embedding models:
 
 ## Model Capabilities
 
-| Model                 | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
-| --------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
-| `sonar-deep-research` | <Cross size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
-| `sonar-reasoning-pro` | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
-| `sonar-reasoning`     | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
-| `sonar-pro`           | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
-| `sonar`               | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+| Model    | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
+| -------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `fast`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `low`    | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `medium` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `high`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `xhigh`  | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
 
 <Note>
   Please see the [Perplexity docs](https://docs.perplexity.ai) for detailed API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/perplexity",
-  "version": "3.0.63",
+  "version": "3.1.1",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.17",
-    "@ai-sdk/provider-utils": "4.0.54"
+    "@ai-sdk/provider": "3.0.18",
+    "@ai-sdk/provider-utils": "4.0.56"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/convert-perplexity-usage.ts

@@ -1,11 +1,20 @@
-import type { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { JSONObject, LanguageModelV3Usage } from '@ai-sdk/provider';
 
 export function convertPerplexityUsage(
   usage:
     | {
-        prompt_tokens?: number | null | undefined;
-        completion_tokens?: number | null | undefined;
-        reasoning_tokens?: number | null | undefined;
+        input_tokens?: number | null;
+        output_tokens?: number | null;
+        total_tokens?: number | null;
+        input_tokens_details?: {
+          cached_tokens?: number | null;
+          cache_creation_input_tokens?: number | null;
+          cache_read_input_tokens?: number | null;
+        } | null;
+        output_tokens_details?: {
+          reasoning_tokens?: number | null;
+        } | null;
+        [key: string]: unknown;
       }
     | undefined
     | null,
@@ -27,23 +36,28 @@ export function convertPerplexityUsage(
     };
   }
 
-  const promptTokens = usage.prompt_tokens ?? 0;
-  const completionTokens = usage.completion_tokens ?? 0;
-  const reasoningTokens = usage.reasoning_tokens ?? 0;
+  const inputTokens = usage.input_tokens ?? 0;
+  const outputTokens = usage.output_tokens ?? 0;
+  const cacheReadTokens =
+    usage.input_tokens_details?.cache_read_input_tokens ??
+    usage.input_tokens_details?.cached_tokens ??
+    0;
+  const cacheWriteTokens =
+    usage.input_tokens_details?.cache_creation_input_tokens ?? 0;
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens ?? 0;
 
   return {
     inputTokens: {
-      total: promptTokens,
-      noCache: promptTokens,
-      cacheRead: undefined,
-      cacheWrite: undefined,
+      total: inputTokens,
+      noCache: Math.max(0, inputTokens - cacheReadTokens - cacheWriteTokens),
+      cacheRead: cacheReadTokens,
+      cacheWrite: cacheWriteTokens,
     },
     outputTokens: {
-      // Perplexity reports reasoning tokens separately from completion tokens.
-      total: completionTokens + reasoningTokens,
-      text: completionTokens,
+      total: outputTokens,
+      text: Math.max(0, outputTokens - reasoningTokens),
       reasoning: reasoningTokens,
     },
-    raw: usage,
+    raw: usage as JSONObject,
   };
 }

package/src/convert-to-perplexity-input.ts

@@ -0,0 +1,199 @@
+import {
+  UnsupportedFunctionalityError,
+  type LanguageModelV3Prompt,
+  type LanguageModelV3ToolResultOutput,
+  type SharedV3Warning,
+} from '@ai-sdk/provider';
+import { convertUint8ArrayToBase64 } from '@ai-sdk/provider-utils';
+import type {
+  PerplexityAgentInput,
+  PerplexityAgentInputContent,
+} from './perplexity-language-model-prompt';
+
+function serializeToolOutput(output: LanguageModelV3ToolResultOutput): string {
+  switch (output.type) {
+    case 'text':
+    case 'error-text':
+      return output.value;
+    case 'json':
+    case 'error-json':
+      return JSON.stringify(output.value);
+    case 'execution-denied':
+      return output.reason ?? 'Tool call execution denied.';
+    case 'content': {
+      if (output.value.some(part => part.type !== 'text')) {
+        throw new UnsupportedFunctionalityError({
+          functionality: 'file and custom tool result content',
+        });
+      }
+      return output.value
+        .map(part => (part.type === 'text' ? part.text : ''))
+        .join('');
+    }
+    default: {
+      const _exhaustiveCheck: never = output;
+      throw new Error(`Unsupported tool output: ${_exhaustiveCheck}`);
+    }
+  }
+}
+
+function getTopLevelMediaType(mediaType: string): string {
+  const slashIndex = mediaType.indexOf('/');
+  return slashIndex === -1 ? mediaType : mediaType.substring(0, slashIndex);
+}
+
+function getThoughtSignature(
+  providerOptions:
+    | Record<string, Record<string, unknown> | undefined>
+    | undefined,
+): string | undefined {
+  const thoughtSignature = providerOptions?.perplexity?.thoughtSignature;
+  return typeof thoughtSignature === 'string' ? thoughtSignature : undefined;
+}
+
+export function convertToPerplexityInput(prompt: LanguageModelV3Prompt): {
+  input: PerplexityAgentInput;
+  warnings: SharedV3Warning[];
+} {
+  const input: PerplexityAgentInput = [];
+  const warnings: SharedV3Warning[] = [];
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        input.push({ type: 'message', role: 'system', content });
+        break;
+      }
+
+      case 'user': {
+        const convertedContent: PerplexityAgentInputContent[] = content.map(
+          part => {
+            switch (part.type) {
+              case 'text':
+                return { type: 'input_text', text: part.text };
+              case 'file': {
+                if (getTopLevelMediaType(part.mediaType) !== 'image') {
+                  throw new UnsupportedFunctionalityError({
+                    functionality: `file part media type ${part.mediaType}`,
+                  });
+                }
+
+                if (part.data instanceof URL) {
+                  return {
+                    type: 'input_image',
+                    image_url: part.data.toString(),
+                  };
+                }
+
+                const mediaType =
+                  part.mediaType === 'image/*' ? 'image/jpeg' : part.mediaType;
+
+                return {
+                  type: 'input_image',
+                  image_url: `data:${mediaType};base64,${
+                    typeof part.data === 'string'
+                      ? part.data
+                      : convertUint8ArrayToBase64(part.data)
+                  }`,
+                };
+              }
+            }
+          },
+        );
+
+        const isTextOnly = convertedContent.every(
+          part => part.type === 'input_text',
+        );
+        input.push({
+          type: 'message',
+          role: 'user',
+          content: isTextOnly
+            ? convertedContent
+                .map(part => (part.type === 'input_text' ? part.text : ''))
+                .join('')
+            : convertedContent,
+        });
+        break;
+      }
+
+      case 'assistant': {
+        const text = content
+          .filter(part => part.type === 'text')
+          .map(part => part.text)
+          .join('');
+
+        if (text.length > 0) {
+          input.push({ type: 'message', role: 'assistant', content: text });
+        }
+
+        for (const part of content) {
+          switch (part.type) {
+            case 'text':
+              break;
+            case 'tool-call':
+              input.push({
+                type: 'function_call',
+                call_id: part.toolCallId,
+                name: part.toolName,
+                arguments: JSON.stringify(part.input ?? {}),
+                thought_signature: getThoughtSignature(part.providerOptions),
+              });
+              break;
+            case 'tool-result':
+              input.push({
+                type: 'function_call_output',
+                call_id: part.toolCallId,
+                name: part.toolName,
+                output: serializeToolOutput(part.output),
+                thought_signature: getThoughtSignature(part.providerOptions),
+              });
+              break;
+            case 'reasoning':
+              warnings.push({
+                type: 'unsupported',
+                feature: 'reasoning content in prompt',
+              });
+              break;
+            case 'file':
+              throw new UnsupportedFunctionalityError({
+                functionality: `assistant ${part.type} parts`,
+              });
+            default: {
+              const _exhaustiveCheck: never = part;
+              throw new Error(
+                `Unsupported assistant part: ${_exhaustiveCheck}`,
+              );
+            }
+          }
+        }
+        break;
+      }
+
+      case 'tool': {
+        for (const part of content) {
+          if (part.type === 'tool-approval-response') {
+            throw new UnsupportedFunctionalityError({
+              functionality: 'tool approval responses',
+            });
+          }
+
+          input.push({
+            type: 'function_call_output',
+            call_id: part.toolCallId,
+            name: part.toolName,
+            output: serializeToolOutput(part.output),
+            thought_signature: getThoughtSignature(part.providerOptions),
+          });
+        }
+        break;
+      }
+
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  return { input, warnings };
+}

package/src/index.ts

@@ -3,6 +3,11 @@ export type {
   PerplexityProvider,
   PerplexityProviderSettings,
 } from './perplexity-provider';
+export type { PerplexityLanguageModelOptions } from './perplexity-language-model-options';
+export type {
+  PerplexityAgentPreset,
+  PerplexityLanguageModelId,
+} from './perplexity-options';
 export type {
   PerplexityEmbeddingModelId,
   PerplexityEmbeddingModelOptions,