> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Perplexity with Mastra

> Use Perplexity's Agent API and the Search API in your Mastra agents and tools.

export const SonarDeprecationNotice = ({showGuideLink = true}) => <Warning>
    Sonar Chat Completions is now <a href="/docs/agent-api/quickstart">Agent API.</a> Sonar will be supported until September 27, 2026.{showGuideLink && <> Migration guide <a href="/docs/agent-api/migrate-from-sonar/overview">here</a>.</>}
  </Warning>;

<SonarDeprecationNotice />

## Overview

[Mastra](https://mastra.ai) is an open-source TypeScript framework for building AI agents and workflows. Wire Perplexity's [Agent API](/docs/agent-api/quickstart) into a Mastra `Agent` through the Open Responses provider, or expose the Search API as a Mastra-compatible tool.

<Info>
  **Mastra** provides a unified `Agent` interface, a model router, and a tools/MCP system for orchestrating LLM workflows. Learn more at [mastra.ai](https://mastra.ai).
</Info>

The Mastra ecosystem provides two Perplexity integrations:

* **Agent API** — Run the [Agent API](/docs/agent-api/quickstart) inside a Mastra `Agent` through the Open Responses provider.
* **Perplexity Search tool** — Expose the [Search API](/docs/search/quickstart) as a Mastra tool for ranked web results.

## API Key Setup

Both integrations read your Perplexity API key from the environment:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

The Search tool also accepts `PPLX_API_KEY` as a fallback.

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai/project/keys">
  Generate your API key from the Perplexity dashboard.
</Card>

## Agent API

<Warning>
  Mastra's built-in `perplexity` and `perplexity-agent` model-router providers target Sonar Chat Completions, which is now the [Agent API](/docs/agent-api/quickstart) — more models, tools, and research-backed presets. Reach it through [`@ai-sdk/open-responses`](https://ai-sdk.dev/providers/ai-sdk-providers/open-responses) as shown below, or see the [migration guide](/docs/agent-api/migrate-from-sonar/overview).
</Warning>

The [Agent API](/docs/agent-api/quickstart) speaks the [Open Responses](https://www.openresponses.org/) standard, so the `@ai-sdk/open-responses` provider connects to it directly. Point the provider at Perplexity's `/v1/responses` endpoint, then pass the model id to your Mastra `Agent`:

```bash theme={null}
npm install @mastra/core @ai-sdk/open-responses
```

```ts theme={null}
import { Agent } from "@mastra/core/agent";
import { createOpenResponses } from "@ai-sdk/open-responses";

const perplexity = createOpenResponses({
  name: "perplexity",
  url: "https://api.perplexity.ai/v1/responses",
  apiKey: process.env.PERPLEXITY_API_KEY,
});

const agent = new Agent({
  id: "research-agent",
  name: "Research Agent",
  instructions: "Answer questions clearly and concisely.",
  // Any Agent API model, e.g. openai/gpt-5.6-luna (faster) or openai/gpt-5.6-sol (higher quality).
  model: perplexity("openai/gpt-5.6-luna"),
});

const result = await agent.generate("Explain what the Perplexity Agent API is in two sentences.");
console.log(result.text);
```

The agent supports both `agent.generate(...)` and `agent.stream(...)`. See the [Agent API quickstart](/docs/agent-api/quickstart) for the full model list, built-in tools, and presets. For web-grounded answers, add the `web_search` tool (below).

## Web-Grounded Answers

Add the [`web_search`](/docs/agent-api/tools/web-search) tool to ground the agent's answers in real-time results from Perplexity's web search. The `@ai-sdk/open-responses` provider sends a fixed request body and does not expose the Agent API's built-in tools as first-class options, so enable `web_search` by adding it to the body in the provider's `fetch` hook — every call the agent makes through this provider is then grounded:

```ts theme={null}
import { Agent } from "@mastra/core/agent";
import { createOpenResponses } from "@ai-sdk/open-responses";

// The provider doesn't surface sources on the result, so capture them in the hook.
let sources = [];

const perplexity = createOpenResponses({
  name: "perplexity",
  url: "https://api.perplexity.ai/v1/responses",
  apiKey: process.env.PERPLEXITY_API_KEY,
  fetch: async (url, options) => {
    const body = JSON.parse(options.body as string);
    // Enable the built-in web_search tool by adding it to the request body.
    body.tools = [{ type: "web_search" }];
    const response = await fetch(url, { ...options, body: JSON.stringify(body) });

    // Sources arrive as a separate `search_results` item in the response `output` array.
    // (Skip for streaming, where the body is an event stream rather than JSON.)
    if (!body.stream) {
      const raw = await response.clone().json();
      sources = raw.output
        .filter((item) => item.type === "search_results")
        .flatMap((item) => item.results); // each: { title, url, snippet, date, ... }
    }

    return response;
  },
});

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

const result = await agent.generate("What are the latest breakthroughs in fusion energy this year?");
console.log(result.text);

for (const source of sources) {
  console.log(source.title, source.url);
}
```

The answer is grounded server-side, but `@ai-sdk/open-responses` does not surface the sources on the result — `result.sources` is empty — so the `fetch` hook reads the raw `search_results` items directly. See [Reading Sources from the Response](/docs/agent-api/prompt-guide) for the full response shape.

## Perplexity Search Tool

The `@mastra/perplexity` package wraps the [Search API](/docs/search/quickstart) as a Mastra-compatible tool. Use this when you want raw ranked web results to feed into an agent.

```bash theme={null}
npm install @mastra/perplexity zod
```

```ts theme={null}
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](https://mastra.ai/reference/tools/perplexity) for the full schema.

## Links & Resources

<CardGroup cols={2}>
  <Card title="Agent API Quickstart" icon="bolt" href="/docs/agent-api/quickstart">
    Build with Agent API models, tools, and presets.
  </Card>

  <Card title="Perplexity SDK" icon="code" href="/docs/sdk/overview">
    Install and configure the official Perplexity SDK.
  </Card>

  <Card title="Perplexity Search Tool" icon="search" href="https://mastra.ai/reference/tools/perplexity">
    Wrap the Perplexity Search API as a Mastra tool.
  </Card>

  <Card title="Mastra Docs" icon="book" href="https://mastra.ai/docs">
    Learn more about agents, tools, and workflows in Mastra.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Mastra documentation](https://mastra.ai/docs)
* Review our [FAQ](/docs/resources/faq)