跳至主要內容

Perplexity Tools

@mastra/perplexity 套件會將 Perplexity Search API 包裝為相容於 Mastra 的 Tool。它提供一個 factory function，回傳以 createTool() 建立的 Tool，並包含完整的 Zod 輸入／輸出 schema。

若要使用由 Perplexity 驅動的 chat completion 或 Agent 式 Workflow，請使用 Mastra 內建的 Perplexity 模型 Provider 或 Perplexity Agent Provider。這些 Provider 與此 Search Tool 各自獨立。

安裝
「安裝」的直接連結

安裝此套件與 Zod：

npm install @mastra/perplexity zod

使用範例
「使用範例」的直接連結

下列範例會使用預設設定建立搜尋 Tool。根據預設，此 Tool 會從環境中讀取 PERPLEXITY_API_KEY（若無則使用 PPLX_API_KEY）。明確傳入 { apiKey } 即可覆寫此值。

src/mastra/tools/index.ts
import { createPerplexitySearchTool } from '@mastra/perplexity'

const searchTool = createPerplexitySearchTool()

若要明確傳入 API key：

src/mastra/tools/index.ts
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
= 'https://api.perplexity.ai'
覆寫 API base URL。

fetch?:

typeof fetch
自訂 fetch 實作，適用於測試、重試或檢測。

方法
「方法」的直接連結

工廠函式
「工廠函式」的直接連結

createPerplexityTools(config?)
「createperplexitytoolsconfig」的直接連結

回傳一個包含所有 Perplexity Tool 的物件，這些 Tool 會共用傳入的設定。

import { createPerplexityTools } from '@mastra/perplexity'

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

回傳值：{ perplexitySearch }

createPerplexitySearchTool(config?)
「createperplexitysearchtoolconfig」的直接連結

建立一個使用 Perplexity Search API 搜尋網路的 Tool。它會回傳經過排序的結果，其中包含標題、URL、摘要與選填的發布日期。

此 Tool 會以 ID perplexity-search 註冊。

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[]
搜尋結果陣列。
SearchResult

title:

string
結果標題。

url:

string
結果 URL。

snippet:

string
內容摘要。

date?:

string
發布日期（如有）。

Agent 範例
「Agent 範例」的直接連結

下列範例會在 Agent 上註冊搜尋 Tool，讓它在回答前取得最新的網頁結果。

src/mastra/agents/index.ts
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 時使用的備援值。
On this page