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

# Perplexity tools

`@mastra/perplexity` 套件將 [Perplexity Search API](https://docs.perplexity.ai/docs/search/quickstart) 包裝成與 Mastra 相容的 Tool。它公開一個工廠函數，傳回以 [`createTool()`](https://mastra.zisheng.pro/zh-HK/reference/tools/create-tool) 建立並附有完整 Zod 輸入／輸出 Schema 的 Tool。

如要使用由 Perplexity 驅動的聊天補全或代理式 Workflow，請使用 Mastra 內置的 [Perplexity 模型 Provider](https://mastra.zisheng.pro/zh-HK/models/providers/perplexity) 或 [Perplexity Agent Provider](https://mastra.zisheng.pro/zh-HK/models/providers/perplexity-agent)。它們與此 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 金鑰：

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

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

## 配置

所有工廠函數都接受一個 `PerplexityClientOptions` 物件：

**apiKey** (`string`): Perplexity API 金鑰。依次回退至 PERPLEXITY\_API\_KEY 和 PPLX\_API\_KEY 環境變數。

**baseUrl** (`string`): 覆寫 API 基礎 URL。 (Default: `'https://api.perplexity.ai'`)

**fetch** (`typeof fetch`): 自訂 fetch 實作，適用於測試、重試或檢測。

## 方法

### 工廠函數

#### `createPerplexityTools(config?)`

傳回一個包含所有 Perplexity tools 的物件，這些 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，讓它在回答前可擷取最新的網絡結果。

```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 金鑰。未有將 `apiKey` 傳入工廠函數時，會用作預設值。 |
| `PPLX_API_KEY`       | 未有設定 `PERPLEXITY_API_KEY` 時使用的後備值。                |

## 相關內容

- [`createTool()`](https://mastra.zisheng.pro/zh-HK/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/zh-HK/models/providers/perplexity)
- [Perplexity Agent Provider](https://mastra.zisheng.pro/zh-HK/models/providers/perplexity-agent)