Perplexity with Mastra

Use Perplexity models, the Agent API, and the Search API in your Mastra agents and tools.

Overview

Mastra is an open-source TypeScript framework for building AI agents and workflows. It ships first-class Perplexity integrations through its model router and tool system, so you can wire Perplexity into a Mastra Agent with a single string identifier or expose the Search API as a Mastra-compatible tool.

Mastra provides a unified Agent interface, a model router, and a tools/MCP system for orchestrating LLM workflows. Learn more at mastra.ai.

The Mastra ecosystem provides three Perplexity integrations:

• Perplexity model provider — Use Perplexity’s web-grounded models in a Mastra Agent.
• Perplexity Agent provider — Use the Agent API (OpenAI-compatible /chat/completions) through Mastra.
• Perplexity Search tool — Expose the Search API as a Mastra tool for ranked web results.

API Key Setup

All three integrations read your Perplexity API key from the environment:

export PERPLEXITY_API_KEY="your_api_key_here"

The Search tool also accepts PPLX_API_KEY as a fallback.

Get API Key

Generate your API key from the Perplexity dashboard.

Perplexity Model Provider

Use Perplexity’s web-grounded models inside a Mastra Agent through the model router.

npm install @mastra/core

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "research-agent",
  name: "Research Agent",
  instructions: "Answer questions with up-to-date information from the web.",
  model: "perplexity/sonar",
});

const result = await agent.generate("What launched at the latest Perplexity event?");
console.log(result.text);

The agent supports both agent.generate(...) and agent.stream(...). For the full list of Perplexity models available through the router, see the Mastra Perplexity provider docs.

Perplexity Agent Provider

The Agent provider routes through Perplexity’s OpenAI-compatible /chat/completions endpoint, giving you access to third-party models served by the Agent API.

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "agent-api",
  name: "Agent API",
  instructions: "Use the best available model for the task.",
  model: "perplexity-agent/<model-id>",
});

For finer control — for example, custom headers or a pinned base URL — pass an object instead of a string:

const agent = new Agent({
  id: "agent-api",
  name: "Agent API",
  instructions: "Use the best available model for the task.",
  model: {
    id: "perplexity-agent/<model-id>",
    url: "https://api.perplexity.ai/v1",
    apiKey: process.env.PERPLEXITY_API_KEY,
  },
});

See the Mastra Perplexity Agent provider docs for the full list of supported models and configuration options.

Perplexity Search Tool

The @mastra/perplexity package wraps the Search API as a Mastra-compatible tool. Use this when you want raw ranked web results — for chat completions or agentic workflows, prefer the model or Agent provider above.

npm install @mastra/perplexity zod

import { createPerplexitySearchTool } from "@mastra/perplexity";

const searchTool = createPerplexitySearchTool({
  apiKey: process.env.PERPLEXITY_API_KEY,
});

const results = await searchTool.execute({
  context: {
    query: "Latest advances in nuclear fusion",
    maxResults: 5,
    searchRecencyFilter: "month",
  },
});

for (const result of results) {
  console.log(result.title, result.url);
}

The tool ID is perplexity-search and supported input parameters include query, maxResults, searchDomainFilter, searchRecencyFilter, searchAfterDateFilter, and searchBeforeDateFilter. Each result includes title, url, snippet, and an optional date.

To register multiple Perplexity tools at once, use createPerplexityTools(config?). See the Mastra Perplexity tool reference for the full schema.

Links & Resources

Perplexity Model Provider

Use Perplexity models in a Mastra Agent.

Perplexity Agent Provider

Use the Perplexity Agent API through Mastra.

Perplexity Search Tool

Wrap the Perplexity Search API as a Mastra tool.

Mastra Docs

Learn more about agents, tools, and workflows in Mastra.

Support

Need help with the integration?

• Browse the Mastra documentation
• Review our FAQ