跳到主要内容

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 实现，适用于测试、重试或插桩。

方法
方法的直接链接

Factory function
Factory function的直接链接

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，让它在回答前取得最新的Web结果。

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