> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Perplexity Tools

`@mastra/perplexity` 包将 [Perplexity Search API](https://docs.perplexity.ai/docs/search/quickstart) 封装为与 Mastra 兼容的 Tool。它提供一个 factory function，返回使用 [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool) 创建的 Tool，并包含完整的 Zod 输入/输出 schema。

若要使用由 Perplexity 驱动的 chat completion 或 Agent 式 Workflow，请使用 Mastra 内置的 [Perplexity 模型 Provider](https://mastra.zisheng.pro/models/providers/perplexity) 或 [Perplexity Agent Provider](https://mastra.zisheng.pro/models/providers/perplexity-agent)。这些 Provider 与此 Search Tool 各自独立。

## 安装

安装此包与 Zod：

**npm**:

```sh
npm install @mastra/perplexity zod
```

**pnpm**:

```sh
pnpm add @mastra/perplexity zod
```

**Yarn**:

```sh
yarn add @mastra/perplexity zod
```

**Bun**:

```sh
bun add @mastra/perplexity zod
```

## 使用示例

下列示例会使用缺省设置创建搜索 Tool。根据缺省，此 Tool 会从环境中读取 `PERPLEXITY_API_KEY`（若无则使用 `PPLX_API_KEY`）。明确传入 `{ apiKey }` 即可覆写此值。

```typescript
import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool()
```

若要明确传入 API key：

```typescript
import { createPerplexitySearchTool } from '@mastra/perplexity'

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

## 设置

所有 factory function 都接受 `PerplexityClientOptions` 对象：

**apiKey** (`string`): Perplexity API key。未设置时会依序使用 PERPLEXITY\_API\_KEY 与 PPLX\_API\_KEY 环境变量。

**baseUrl** (`string`): 覆写 API base URL。 (Default: `'https://api.perplexity.ai'`)

**fetch** (`typeof fetch`): 自定义 fetch 实现，适用于测试、重试或插桩。

## 方法

### Factory function

#### `createPerplexityTools(config?)`

返回一个包含所有 Perplexity Tool 的对象，这些 Tool 会共用传入的设置。

```typescript
import { createPerplexityTools } from '@mastra/perplexity'

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

返回值：`{ perplexitySearch }`

#### `createPerplexitySearchTool(config?)`

创建一个使用 Perplexity Search API 搜索网络的 Tool。它会返回经过排序的结果，其中包含标题、URL、摘要与选填的发布日期。

此 Tool 会以 ID `perplexity-search` 注册。

```typescript
import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool()
```

##### 输入

**query** (`string`): 搜索查找。

**maxResults** (`number`): 返回结果的数量上限（1–20）。

**searchDomainFilter** (`string[]`): 依网域限制（或排除）结果。在网域前加上 - 即可排除（例如 -pinterest.com）。同一次调用中不可混用允许清单与拒绝清单项目。

**searchRecencyFilter** (`'hour' | 'day' | 'week' | 'month' | 'year'`): 只返回指定近期时间范围内的结果。

**searchAfterDateFilter** (`string`): 只返回在此日期当天或之后发布的结果。格式：m/d/yyyy。

**searchBeforeDateFilter** (`string`): 只返回在此日期当天或之前发布的结果。格式：m/d/yyyy。

##### 输出

**query** (`string`): 原始搜索查找。

**results** (`SearchResult[]`): 搜索结果数组。

**results.title** (`string`): 结果标题。

**results.url** (`string`): 结果 URL。

**results.snippet** (`string`): 内容摘要。

**results.date** (`string`): 发布日期（如有）。

## Agent 示例

下列示例会在 Agent 上注册搜索 Tool，让它在回答前取得最新的Web结果。

```typescript
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(),
  },
})
```

## 环境变量

| 变量                   | 说明                                                              |
| -------------------- | --------------------------------------------------------------- |
| `PERPLEXITY_API_KEY` | 你的 Perplexity API key。若未将 `apiKey` 传给 factory function，则缺省使用此值。 |
| `PPLX_API_KEY`       | 未设置 `PERPLEXITY_API_KEY` 时使用的备援值。                               |

## 相关内容

- [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool)
- [Perplexity Search 快速入门](https://docs.perplexity.ai/docs/search/quickstart)
- [Perplexity Agent 快速入门](https://docs.perplexity.ai/docs/agent/quickstart)
- [Perplexity 模型 Provider](https://mastra.zisheng.pro/models/providers/perplexity)
- [Perplexity Agent Provider](https://mastra.zisheng.pro/models/providers/perplexity-agent)