> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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/zh-TW/reference/tools/create-tool) 建立的 Tool，並包含完整的 Zod 輸入／輸出 schema。

若要使用由 Perplexity 驅動的 chat completion 或 Agent 式 Workflow，請使用 Mastra 內建的 [Perplexity 模型 Provider](https://mastra.zisheng.pro/zh-TW/models/providers/perplexity) 或 [Perplexity Agent Provider](https://mastra.zisheng.pro/zh-TW/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 實作，適用於測試、重試或檢測。

## 方法

### 工廠函式

#### `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，讓它在回答前取得最新的網頁結果。

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