Perplexity
Use Perplexity’s models for research and Q&A with built-in web search. Perplexity models (Sonar) automatically search the web and provide grounded, cited answers — no separate search tool needed.
RadarOS supports two modes for the Perplexity provider:
| Mode | SDK | Search Options | Citations |
|---|
| Native (recommended) | @perplexity-ai/perplexity_ai | Full control (domain filter, recency, academic mode) | Typed in raw response |
| OpenAI-compat (fallback) | openai | Basic only | Not available |
The provider automatically selects native mode when the Perplexity SDK is installed, falling back to the OpenAI SDK otherwise.
Setup
Native SDK (recommended)
OpenAI-compat (fallback)
Environment
npm install @perplexity-ai/perplexity_ai
The native SDK unlocks search-specific parameters and typed citation responses.Uses the OpenAI SDK pointed at Perplexity’s OpenAI-compatible endpoint. Basic chat works, but search options and citations are not available. Get your API key from perplexity.ai/settings/api:export PERPLEXITY_API_KEY="..."
Factory
import { perplexity } from "@radaros/core";
const model = perplexity("sonar-pro");
Model ID (e.g., "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro").
Optional configuration object.
PerplexityConfig
| Field | Type | Description |
|---|
apiKey | string | API key override (default: PERPLEXITY_API_KEY env var) |
baseURL | string | Custom base URL (default: https://api.perplexity.ai) |
search | PerplexitySearchOptions | Search-specific options (native SDK only) |
Supported Models
| Model | Description | Best For |
|---|
sonar | Fast search-grounded model | Quick research queries |
sonar-pro | Enhanced search with more sources | Deep research, comprehensive answers |
sonar-deep-research | Multi-step deep research | Complex multi-source investigation |
sonar-reasoning-pro | Reasoning + search | Complex research requiring analysis |
Basic Example
Perplexity shines for research — answers are automatically web-grounded:
import { Agent, perplexity } from "@radaros/core";
const agent = new Agent({
name: "researcher",
model: perplexity("sonar-pro"),
instructions: "You are a research assistant. Provide thorough, well-sourced answers.",
});
const result = await agent.run("What are the latest FDA-approved treatments for Alzheimer's disease?");
console.log(result.text);
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:
import { perplexity } from "@radaros/core";
const model = perplexity("sonar-pro", {
search: {
searchMode: "academic",
searchRecencyFilter: "month",
searchDomainFilter: ["nature.com", "sciencedirect.com", "arxiv.org"],
returnImages: false,
returnRelatedQuestions: true,
searchContextSize: "high",
},
});
PerplexitySearchOptions
| Field | Type | Description |
|---|
searchMode | "web" | "academic" | "sec" | Search mode (default: web). academic searches scholarly sources, sec searches SEC filings. |
searchDomainFilter | string[] | Restrict search to specific domains |
searchRecencyFilter | "hour" | "day" | "week" | "month" | "year" | Only return results from the specified time window |
searchAfterDate | string | Only return results after this date (YYYY-MM-DD) |
searchBeforeDate | string | Only return results before this date (YYYY-MM-DD) |
returnImages | boolean | Include images in the response |
returnRelatedQuestions | boolean | Include related follow-up questions |
disableSearch | boolean | Disable search entirely (use as a pure LLM) |
searchContextSize | "low" | "medium" | "high" | Amount of search context to include (default: low) |
Citations & Search Results
When using the native SDK, the raw API response includes citations, search results, images, and related questions. Access them via result.raw:
import { Agent, perplexity } from "@radaros/core";
const agent = new Agent({
name: "cited-researcher",
model: perplexity("sonar-pro", {
search: { returnRelatedQuestions: true },
}),
instructions: "Provide well-sourced answers with citations.",
});
const result = await agent.run("What is the current population of Tokyo?");
console.log(result.text);
// Access citations from the raw response
const raw = result.raw as any;
if (raw?.citations) {
console.log("Sources:", raw.citations);
// ["https://worldpopulationreview.com/...", "https://en.wikipedia.org/..."]
}
if (raw?.search_results) {
for (const sr of raw.search_results) {
console.log(`- ${sr.title}: ${sr.url}`);
}
}
if (raw?.related_questions) {
console.log("Related:", raw.related_questions);
}
Academic Research Agent
Use searchMode: "academic" to search scholarly sources:
import { Agent, perplexity, defineTool } from "@radaros/core";
import { z } from "zod";
const agent = new Agent({
name: "academic-researcher",
model: perplexity("sonar-pro", {
search: {
searchMode: "academic",
searchRecencyFilter: "year",
searchContextSize: "high",
},
}),
instructions: "You are an academic research assistant. Cite your sources.",
tools: [
defineTool({
name: "saveNote",
description: "Save a research note",
parameters: z.object({ title: z.string(), content: z.string() }),
execute: async ({ title, content }) => `Saved: "${title}" (${content.length} chars)`,
}),
],
maxToolRoundtrips: 3,
});
const result = await agent.run(
"Find recent papers on CRISPR gene editing for sickle cell disease. Save key findings."
);
console.log(result.text);
Reasoning + Search
The sonar-reasoning-pro model combines chain-of-thought reasoning with web search:
import { Agent, perplexity } from "@radaros/core";
const agent = new Agent({
name: "analyst",
model: perplexity("sonar-reasoning-pro"),
instructions: "Analyze questions thoroughly with reasoning and evidence.",
});
const result = await agent.run(
"Compare the economic policies of the EU and US regarding AI regulation. Which approach is more likely to foster innovation?"
);
console.log(result.text);
Full Example
import { Agent, perplexity, CostTracker } from "@radaros/core";
const costTracker = new CostTracker({
pricing: {
"sonar": { promptPer1k: 0.001, completionPer1k: 0.001 },
"sonar-pro": { promptPer1k: 0.003, completionPer1k: 0.015 },
},
});
const agent = new Agent({
name: "fact-checker",
model: perplexity("sonar-pro", {
search: {
searchDomainFilter: ["reuters.com", "apnews.com", "bbc.com"],
searchRecencyFilter: "month",
},
}),
instructions: "Fact-check claims by searching the web. Provide sources for your findings.",
costTracker,
});
const result = await agent.run(
"Fact-check: 'The Great Wall of China is visible from space with the naked eye.'"
);
console.log(result.text);
console.log(`Cost: $${costTracker.getSummary().totalCost.toFixed(4)}`);
Environment Variables
| Variable | Description |
|---|
PERPLEXITY_API_KEY | Perplexity API key |
Cross-References
- DeepSeek — Reasoning models without web search
- xAI — Grok with optional live search
- Tools — Extend Perplexity with custom tools
- OpenAI-Compatible — How the fallback mode works