Skip to main content

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:
ModeSDKSearch OptionsCitations
Native (recommended)@perplexity-ai/perplexity_aiFull control (domain filter, recency, academic mode)Typed in raw response
OpenAI-compat (fallback)openaiBasic onlyNot available
The provider automatically selects native mode when the Perplexity SDK is installed, falling back to the OpenAI SDK otherwise.

Setup


Factory

import { perplexity } from "@radaros/core";

const model = perplexity("sonar-pro");
modelId
string
required
Model ID (e.g., "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro").
config
PerplexityConfig
Optional configuration object.

PerplexityConfig

FieldTypeDescription
apiKeystringAPI key override (default: PERPLEXITY_API_KEY env var)
baseURLstringCustom base URL (default: https://api.perplexity.ai)
searchPerplexitySearchOptionsSearch-specific options (native SDK only)

Supported Models

ModelDescriptionBest For
sonarFast search-grounded modelQuick research queries
sonar-proEnhanced search with more sourcesDeep research, comprehensive answers
sonar-deep-researchMulti-step deep researchComplex multi-source investigation
sonar-reasoning-proReasoning + searchComplex 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

FieldTypeDescription
searchMode"web" | "academic" | "sec"Search mode (default: web). academic searches scholarly sources, sec searches SEC filings.
searchDomainFilterstring[]Restrict search to specific domains
searchRecencyFilter"hour" | "day" | "week" | "month" | "year"Only return results from the specified time window
searchAfterDatestringOnly return results after this date (YYYY-MM-DD)
searchBeforeDatestringOnly return results before this date (YYYY-MM-DD)
returnImagesbooleanInclude images in the response
returnRelatedQuestionsbooleanInclude related follow-up questions
disableSearchbooleanDisable 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);

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

VariableDescription
PERPLEXITY_API_KEYPerplexity 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