Skip to main content
Use Perplexity’s models for research and Q&A with built-in web search. Sonar can perform provider-side search without an application search tool. Search availability and returned citations depend on the selected model and request.
Provider boundary checked 2026-10-04: Perplexity ended Sonar Chat Completions support on September 27, 2026. Its synchronous and streaming requests continue through a gradual server-side conversion to Agent API requests. Agentium v4’s adapter still calls the Chat Completions surface; it does not implement the new Agent API contract. Review Perplexity’s migration guidance before a new integration. The examples below document this v4 compatibility behavior.
Agentium supports two modes for the Perplexity provider: The adapter tries native initialization first and falls back to the OpenAI-compatible SDK if that fails. Install and verify the native SDK when your application depends on its search configuration. These examples make live requests when run; this documentation check only verifies their types.

Setup


Factory

string
required
Model ID (e.g., "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro").
PerplexityConfig
Optional configuration object.

PerplexityConfig


Supported models

The adapter passes model IDs through to the provider; this table describes example families, not account-access guarantees. Check the provider catalog before selecting a deployment model.

Basic Example

Use an Agent for a bounded text answer. Save this as research.ts and run npx tsx research.ts after setting the key:

Search Options (Native SDK)

Search options require the @perplexity-ai/perplexity_ai package. They are silently ignored in OpenAI-compat fallback mode.
Configure search behavior via the search field in PerplexityConfig:

PerplexitySearchOptions


Citations & Search Results

Agent.run() returns RunOutput, which has no raw field. If your application needs the native response’s structured citation metadata, call the provider’s generate() directly and validate ModelResponse.raw before reading it. This is one model request, without an Agent tool loop or Agent memory.
The raw shape is provider-owned and can change. Absence of citations is not a successful citation assertion; check required fields in your application when sources are mandatory.

Academic research agent

Use native searchMode: "academic" when scholarly retrieval fits the task. In v4, native request construction forwards search options but does not forward application function-tool definitions. Do not expect a configured saveNote tool to run in this mode; persist the validated result in application code after the model response.

Use a reasoning/search model when the provider supports it. The returned answer is not a promise of access to private internal reasoning:

Full example

This example restricts native search domains and prints the usage recorded for the completed Agent run. It does not guess dollar costs from a text-token-only pricing table; search/request charges can also matter.
Expect answer text and recorded usage; exact values depend on the response. Use the cost guide with current matching rates if you need estimates, and provider billing for authoritative charges.

Environment Variables


Cross-References

  • DeepSeek — Reasoning models without web search
  • xAI — Grok with optional live search
  • Tools — Build an explicit search tool for another model when application tool execution is required
  • OpenAI-Compatible — How the fallback mode works