Perplexity tools

The @mastra/perplexity package wraps the Perplexity Search API as a Mastra-compatible tool. It exposes a factory function that returns a tool created with createTool() and full Zod input/output schemas.

For chat completions or agentic workflows powered by Perplexity, use Mastra's built-in Perplexity model provider or Perplexity Agent provider. Those are separate from this Search tool.

Installation

Install the package alongside Zod:

npm

npm install @mastra/perplexity zod

pnpm

pnpm add @mastra/perplexity zod

Yarn

yarn add @mastra/perplexity zod

Bun

bun add @mastra/perplexity zod

Usage example

The following example creates the search tool with the default configuration. By default, the tool reads PERPLEXITY_API_KEY (with PPLX_API_KEY as a fallback) from the environment. Pass { apiKey } explicitly to override.

src/mastra/tools/index.ts

import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool()

To pass an API key explicitly:

src/mastra/tools/index.ts

import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool({ apiKey: 'pplx-...' })

Configuration

All factory functions accept a PerplexityClientOptions object:

apiKey?:

string

Perplexity API key. Falls back to the PERPLEXITY_API_KEY then PPLX_API_KEY environment variables.

baseUrl?:

string

= 'https://api.perplexity.ai'

Override the API base URL.

fetch?:

typeof fetch

Custom fetch implementation. Useful for tests, retries, or instrumentation.

Methods

Factory functions

createPerplexityTools(config?)

Returns an object containing all Perplexity tools that share the supplied configuration.

import { createPerplexityTools } from '@mastra/perplexity'

const tools = createPerplexityTools({ apiKey: 'pplx-...' })
// tools.perplexitySearch

Returns: { perplexitySearch }

createPerplexitySearchTool(config?)

Creates a tool that searches the web using the Perplexity Search API. Returns ranked results with titles, URLs, snippets, and optional publication dates.

The tool is registered with the ID perplexity-search.

import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool()

Input

query:

string

The search query.

maxResults?:

number

Maximum number of results to return (1-20).

searchDomainFilter?:

string[]

Restrict (or exclude) results by domain. Prefix a domain with - to exclude it (for example, -pinterest.com). Do not mix allow- and deny-list entries in the same call.

searchRecencyFilter?:

'hour' | 'day' | 'week' | 'month' | 'year'

Only return results from within the given recency window.

searchAfterDateFilter?:

string

Only return results published on or after this date. Format: m/d/yyyy.

searchBeforeDateFilter?:

string

Only return results published on or before this date. Format: m/d/yyyy.

Output

query:

string

The original search query.

results:

SearchResult[]

Array of search results.

SearchResult

title:

string

Result title.

url:

string

Result URL.

snippet:

string

Content snippet.

date?:

string

Publication date when available.

Agent example

The following example registers the search tool on an agent so it can fetch fresh web results before answering.

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createPerplexitySearchTool } from '@mastra/perplexity'

const agent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'You are a research assistant. Use the perplexity-search tool to find up-to-date information from the web before answering.',
  tools: {
    search: createPerplexitySearchTool(),
  },
})

Environment variables

Variable	Description
PERPLEXITY_API_KEY	Your Perplexity API key. Used as the default when apiKey isn't passed to a factory function.
PPLX_API_KEY	Fallback used when PERPLEXITY_API_KEY is unset.

Related

• createTool()
• Perplexity Search quickstart
• Perplexity Agent quickstart
• Perplexity model provider
• Perplexity Agent provider