尧图网页设计 
Mastra Perplexity 集成指南为 AI Agent 接入实时网络搜索能力【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/perplexity是 Mastra 官方提供的网络搜索集成包它基于 Perplexity Search API 将实时 Web 搜索能力封装为可供 Agent 直接调用的工具Tool。本指南以该集成包的 CHANGELOG.md 为核心脉络结合 README 与 源码实现完整讲解安装、配置、参数细节、底层请求链路与版本演进读完后你可以直接在 Mastra Agent 中接入具备实时检索能力的搜索工具。集成包概览Search 工具是什么从 CHANGELOG 中可以看到该集成自0.1.0版本PR #15939正式引入核心交付物是createPerplexityTools(config?)一次创建一组工具返回{ perplexitySearch }createPerplexitySearchTool(config?)单独创建搜索工具工具 id 为perplexity-search底层请求函数perplexitySearchRequest(body, options?)及配套类型定义。这些导出均可在 src/index.ts 中确认其中createPerplexityTools的实际实现位于 src/tools.tsimport type { PerplexityClientOptions } from ./client.js; import { createPerplexitySearchTool } from ./search.js; export function createPerplexityTools(config?: PerplexityClientOptions) { return { perplexitySearch: createPerplexitySearchTool(config), }; }即createPerplexityTools只是对createPerplexitySearchTool的一次薄封装两者共享同一套配置类型PerplexityClientOptions可根据偏好选择“整组导入”或“单独导入”。安装与快速开始按 README 与 package.json 的说明安装npm install mastra/perplexity运行环境要求 Node.js22.13.0peer 依赖为mastra/core 1.0.0-0 2.0.0-0与zod 3.0.0 || 4.0.0因此必须搭配 Mastra 核心包与 zod 使用。包以type: module发布同时提供 ESMdist/index.js与 CJSdist/index.cjs双格式导出兼容import与require两种引入方式。使用前需要准备 Perplexity API Key可以在创建工具时显式传入也可以写入环境变量export PERPLEXITY_API_KEYyour_api_key_here创建搜索工具的最简写法出自 CHANGELOG 中的原始示例import { createPerplexityTools } from mastra/perplexity; const { perplexitySearch } createPerplexityTools({ apiKey: process.env.PERPLEXITY_API_KEY });配置选项与参数详解客户端配置 PerplexityClientOptions定义在 src/client.ts支持三个字段配置项类型默认值说明apiKeystring环境变量API Key未传入时依次回退到PERPLEXITY_API_KEY、PPLX_API_KEY环境变量baseUrlstringhttps://api.perplexity.ai覆盖 API 基地址用于代理或测试场景fetchtypeof fetch全局fetch自定义 fetch 实现便于测试、重试或链路插桩关于 API Key 的解析逻辑源码中resolveApiKey会按“显式参数 →PERPLEXITY_API_KEY→PPLX_API_KEY”的顺序取值三者皆缺失时抛出明确的错误提示client.ts避免携带无效凭据发起请求。搜索请求参数 PerplexitySearchRequest对应 API 层请求体snake_case同样定义于 client.ts参数类型说明querystring搜索查询词必填max_resultsnumber最多返回的结果条数max_tokens_per_pagenumber每页结果允许的最大 token 数search_domain_filterstring[]域名过滤以-前缀表示排除deny否则为限定allowsearch_recency_filterhour \| day \| week \| month \| year时间窗口过滤只返回该时段内的结果search_after_date_filterstring只返回该日期含之后发布的结果格式m/d/yyyysearch_before_date_filterstring只返回该日期含之前发布的结果格式m/d/yyyy工具层 Schema 约束zod 校验与纯 API 参数不同src/search.ts 中通过 zod 对工具输入做了更严格的约束Agent 侧输入参数采用 camelCasequery必填字符串maxResults整数范围1–20缺省时使用 API 默认值searchDomainFilter字符串数组不允许在同一次调用中混用 allow 与 deny 条目例如[mastra.ai, -pinterest.com]会直接校验失败错误信息为 “searchDomainFilter cannot mix allow and deny domain entries in the same call”searchRecencyFilter枚举hour/day/week/month/yearsearchAfterDateFilter/searchBeforeDateFilter日期字符串格式m/d/yyyy如1/1/2025。输出 Schema 则固定返回query与results数组每条结果包含title、url、snippet以及可选的date字段search.ts。底层实现一次搜索请求的完整链路从工具创建到拿到结果源码中实际发生了如下调用链Agent 调用工具 → createPerplexitySearchTool 的 execute → perplexitySearchRequest(body, config) → fetch(POST {baseUrl}/search) 携带 Bearer Token → 归一化响应 → 返回 { query, results }关键实现位于 src/client.ts请求方式为POSTURL 为${baseUrl 去尾部斜杠}/search默认即https://api.perplexity.ai/search请求头携带Content-Type: application/json与Authorization: Bearer ${apiKey}请求体按 snake_case 序列化max_results、search_domain_filter等非 2xx 响应会抛出包含状态码与响应体摘要的错误错误体超过 1000 字符时截断显示避免超大响应污染日志响应归一化results字段缺失时自动转换为空数组保证下游永远拿到结构化数据。工具层的execute会把 Agent 侧的 camelCase 输入映射为 API 的 snake_case 请求体再将响应中的每条结果透传为title/url/snippet/date见 search.ts。这些行为均有对应的单元测试验证例如 src/tests/search.test.ts 断言了参数透传、空结果归一化、403/500 错误传播、错误体截断以及 allow/deny 混用校验src/tests/client.test.ts 则验证了 API Key 缺失抛错、PPLX_API_KEY回退、显式apiKey优先级、自定义baseUrl拼接以及 429 错误信息格式。在 Mastra Agent 中接入搜索工具将搜索工具挂载到 Agent 上的推荐写法来自 READMEimport { Agent } from mastra/core/agent; import { createPerplexitySearchTool } from mastra/perplexity; export const researchAgent new Agent({ id: research-agent, name: Research Agent, model: openai/gpt-5.6-sol, instructions: Use web search to find current sources before answering., tools: { search: createPerplexitySearchTool(), }, });要点说明工具创建时不传apiKey也可行——只要环境中已设置PERPLEXITY_API_KEY或PPLX_API_KEYAgent 的instructions中明确要求“先搜索再回答”配合工具的description“Search the web for up-to-date information using the Perplexity Search API…”可以让模型在回答时效性问题时优先触发搜索该工具定位为“搜索并返回排名结果”标题、URL、摘要、发布日期因此更适合作为检索步骤嵌入多步 Agent 流程而非像对话式 sonar 模型那样直接生成融合回答——这一点在 search.test.ts 中也有体现工具描述不包含sonar字样。典型场景带过滤条件的时效性检索借助 Schema 中的过滤参数可以把工具限定在特定来源与时间窗口内例如只检索最近一个月内、来自特定站点、限定日期区间的信息import { createPerplexitySearchTool } from mastra/perplexity; const tool createPerplexitySearchTool({ apiKey: process.env.PERPLEXITY_API_KEY }); // Agent 或调用方传入的输入示例 const input { query: Mastra agent framework releases, maxResults: 8, searchRecencyFilter: month, searchDomainFilter: [mastra.ai, github.com], searchAfterDateFilter: 1/1/2026, };注意事项若使用searchDomainFilter排除站点如-pinterest.com请勿在同一数组中混入正向限定域名日期过滤格式必须为m/d/yyyy否则校验不通过未设置的过滤字段不会进入请求体测试中明确断言了“omits unset filter fields”因此无需为可选参数补默认值。版本演进与维护记录从 CHANGELOG.md 可以梳理出该集成的完整发布历史0.1.0 / 0.1.0-alpha.0初始发布新增createPerplexitySearchTool与createPerplexityTools接入 Perplexity Search API依赖mastra/core1.31.00.1.3 / 0.1.3-alpha.0针对 2026-06-17 “easy-day-js” 供应链安全事件的安全修复重新发布干净版本并将latestdist-tag 前移取代声明了恶意依赖的受影响版本依赖同步升级至mastra/core1.44.00.2.0版本号常规升级对应mastra/core1.45.00.2.1将CHANGELOG.md从 npm 分发文件files字段中移除以减小包体积并更新 README 保证信息准确当前版本依赖mastra/core1.64.0。值得一提的是当前 package.json 的files字段确实仅包含dist与 0.2.1 的变更记录一致说明发布产物中不再附带 CHANGELOG 文本。质量保障与工程配置该包还提供了一套完整的工程化配套详见 package.json 与目录结构构建基于tsdownpnpm build:lib支持--watch开发模式测试vitest run覆盖client.test.ts请求层与search.test.ts工具层两类用例静态检查oxlinteslint双重检查pnpm lint发布Apache-2.0 许可证包内含 ESM/CJS 双格式与 TypeScript 类型声明dist/index.d.ts。小结mastra/perplexity以极小的 API 面两个工厂函数、一个底层请求函数为 Mastra Agent 提供了完整的实时网络搜索能力支持域名 allow/deny 过滤、时效窗口与日期区间过滤、结果数量控制并通过 zod Schema 在工具层提前拦截非法输入。配合清晰的错误信息与充分的测试覆盖它可以直接嵌入研究型 Agent 的工作流中作为“先检索、再作答”的关键一步。若需深入了解各配置项与底层行为可继续阅读 search.ts、client.ts 及其对应的 测试用例。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Perplexity 集成指南：为 AI Agent 接入实时网络搜索能力
Mastra Perplexity 集成指南为 AI Agent 接入实时网络搜索能力【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/perplexity是 Mastra 官方提供的网络搜索集成包它基于 Perplexity Search API 将实时 Web 搜索能力封装为可供 Agent 直接调用的工具Tool。本指南以该集成包的 CHANGELOG.md 为核心脉络结合 README 与 源码实现完整讲解安装、配置、参数细节、底层请求链路与版本演进读完后你可以直接在 Mastra Agent 中接入具备实时检索能力的搜索工具。集成包概览Search 工具是什么从 CHANGELOG 中可以看到该集成自0.1.0版本PR #15939正式引入核心交付物是createPerplexityTools(config?)一次创建一组工具返回{ perplexitySearch }createPerplexitySearchTool(config?)单独创建搜索工具工具 id 为perplexity-search底层请求函数perplexitySearchRequest(body, options?)及配套类型定义。这些导出均可在 src/index.ts 中确认其中createPerplexityTools的实际实现位于 src/tools.tsimport type { PerplexityClientOptions } from ./client.js; import { createPerplexitySearchTool } from ./search.js; export function createPerplexityTools(config?: PerplexityClientOptions) { return { perplexitySearch: createPerplexitySearchTool(config), }; }即createPerplexityTools只是对createPerplexitySearchTool的一次薄封装两者共享同一套配置类型PerplexityClientOptions可根据偏好选择“整组导入”或“单独导入”。安装与快速开始按 README 与 package.json 的说明安装npm install mastra/perplexity运行环境要求 Node.js22.13.0peer 依赖为mastra/core 1.0.0-0 2.0.0-0与zod 3.0.0 || 4.0.0因此必须搭配 Mastra 核心包与 zod 使用。包以type: module发布同时提供 ESMdist/index.js与 CJSdist/index.cjs双格式导出兼容import与require两种引入方式。使用前需要准备 Perplexity API Key可以在创建工具时显式传入也可以写入环境变量export PERPLEXITY_API_KEYyour_api_key_here创建搜索工具的最简写法出自 CHANGELOG 中的原始示例import { createPerplexityTools } from mastra/perplexity; const { perplexitySearch } createPerplexityTools({ apiKey: process.env.PERPLEXITY_API_KEY });配置选项与参数详解客户端配置 PerplexityClientOptions定义在 src/client.ts支持三个字段配置项类型默认值说明apiKeystring环境变量API Key未传入时依次回退到PERPLEXITY_API_KEY、PPLX_API_KEY环境变量baseUrlstringhttps://api.perplexity.ai覆盖 API 基地址用于代理或测试场景fetchtypeof fetch全局fetch自定义 fetch 实现便于测试、重试或链路插桩关于 API Key 的解析逻辑源码中resolveApiKey会按“显式参数 →PERPLEXITY_API_KEY→PPLX_API_KEY”的顺序取值三者皆缺失时抛出明确的错误提示client.ts避免携带无效凭据发起请求。搜索请求参数 PerplexitySearchRequest对应 API 层请求体snake_case同样定义于 client.ts参数类型说明querystring搜索查询词必填max_resultsnumber最多返回的结果条数max_tokens_per_pagenumber每页结果允许的最大 token 数search_domain_filterstring[]域名过滤以-前缀表示排除deny否则为限定allowsearch_recency_filterhour \| day \| week \| month \| year时间窗口过滤只返回该时段内的结果search_after_date_filterstring只返回该日期含之后发布的结果格式m/d/yyyysearch_before_date_filterstring只返回该日期含之前发布的结果格式m/d/yyyy工具层 Schema 约束zod 校验与纯 API 参数不同src/search.ts 中通过 zod 对工具输入做了更严格的约束Agent 侧输入参数采用 camelCasequery必填字符串maxResults整数范围1–20缺省时使用 API 默认值searchDomainFilter字符串数组不允许在同一次调用中混用 allow 与 deny 条目例如[mastra.ai, -pinterest.com]会直接校验失败错误信息为 “searchDomainFilter cannot mix allow and deny domain entries in the same call”searchRecencyFilter枚举hour/day/week/month/yearsearchAfterDateFilter/searchBeforeDateFilter日期字符串格式m/d/yyyy如1/1/2025。输出 Schema 则固定返回query与results数组每条结果包含title、url、snippet以及可选的date字段search.ts。底层实现一次搜索请求的完整链路从工具创建到拿到结果源码中实际发生了如下调用链Agent 调用工具 → createPerplexitySearchTool 的 execute → perplexitySearchRequest(body, config) → fetch(POST {baseUrl}/search) 携带 Bearer Token → 归一化响应 → 返回 { query, results }关键实现位于 src/client.ts请求方式为POSTURL 为${baseUrl 去尾部斜杠}/search默认即https://api.perplexity.ai/search请求头携带Content-Type: application/json与Authorization: Bearer ${apiKey}请求体按 snake_case 序列化max_results、search_domain_filter等非 2xx 响应会抛出包含状态码与响应体摘要的错误错误体超过 1000 字符时截断显示避免超大响应污染日志响应归一化results字段缺失时自动转换为空数组保证下游永远拿到结构化数据。工具层的execute会把 Agent 侧的 camelCase 输入映射为 API 的 snake_case 请求体再将响应中的每条结果透传为title/url/snippet/date见 search.ts。这些行为均有对应的单元测试验证例如 src/tests/search.test.ts 断言了参数透传、空结果归一化、403/500 错误传播、错误体截断以及 allow/deny 混用校验src/tests/client.test.ts 则验证了 API Key 缺失抛错、PPLX_API_KEY回退、显式apiKey优先级、自定义baseUrl拼接以及 429 错误信息格式。在 Mastra Agent 中接入搜索工具将搜索工具挂载到 Agent 上的推荐写法来自 READMEimport { Agent } from mastra/core/agent; import { createPerplexitySearchTool } from mastra/perplexity; export const researchAgent new Agent({ id: research-agent, name: Research Agent, model: openai/gpt-5.6-sol, instructions: Use web search to find current sources before answering., tools: { search: createPerplexitySearchTool(), }, });要点说明工具创建时不传apiKey也可行——只要环境中已设置PERPLEXITY_API_KEY或PPLX_API_KEYAgent 的instructions中明确要求“先搜索再回答”配合工具的description“Search the web for up-to-date information using the Perplexity Search API…”可以让模型在回答时效性问题时优先触发搜索该工具定位为“搜索并返回排名结果”标题、URL、摘要、发布日期因此更适合作为检索步骤嵌入多步 Agent 流程而非像对话式 sonar 模型那样直接生成融合回答——这一点在 search.test.ts 中也有体现工具描述不包含sonar字样。典型场景带过滤条件的时效性检索借助 Schema 中的过滤参数可以把工具限定在特定来源与时间窗口内例如只检索最近一个月内、来自特定站点、限定日期区间的信息import { createPerplexitySearchTool } from mastra/perplexity; const tool createPerplexitySearchTool({ apiKey: process.env.PERPLEXITY_API_KEY }); // Agent 或调用方传入的输入示例 const input { query: Mastra agent framework releases, maxResults: 8, searchRecencyFilter: month, searchDomainFilter: [mastra.ai, github.com], searchAfterDateFilter: 1/1/2026, };注意事项若使用searchDomainFilter排除站点如-pinterest.com请勿在同一数组中混入正向限定域名日期过滤格式必须为m/d/yyyy否则校验不通过未设置的过滤字段不会进入请求体测试中明确断言了“omits unset filter fields”因此无需为可选参数补默认值。版本演进与维护记录从 CHANGELOG.md 可以梳理出该集成的完整发布历史0.1.0 / 0.1.0-alpha.0初始发布新增createPerplexitySearchTool与createPerplexityTools接入 Perplexity Search API依赖mastra/core1.31.00.1.3 / 0.1.3-alpha.0针对 2026-06-17 “easy-day-js” 供应链安全事件的安全修复重新发布干净版本并将latestdist-tag 前移取代声明了恶意依赖的受影响版本依赖同步升级至mastra/core1.44.00.2.0版本号常规升级对应mastra/core1.45.00.2.1将CHANGELOG.md从 npm 分发文件files字段中移除以减小包体积并更新 README 保证信息准确当前版本依赖mastra/core1.64.0。值得一提的是当前 package.json 的files字段确实仅包含dist与 0.2.1 的变更记录一致说明发布产物中不再附带 CHANGELOG 文本。质量保障与工程配置该包还提供了一套完整的工程化配套详见 package.json 与目录结构构建基于tsdownpnpm build:lib支持--watch开发模式测试vitest run覆盖client.test.ts请求层与search.test.ts工具层两类用例静态检查oxlinteslint双重检查pnpm lint发布Apache-2.0 许可证包内含 ESM/CJS 双格式与 TypeScript 类型声明dist/index.d.ts。小结mastra/perplexity以极小的 API 面两个工厂函数、一个底层请求函数为 Mastra Agent 提供了完整的实时网络搜索能力支持域名 allow/deny 过滤、时效窗口与日期区间过滤、结果数量控制并通过 zod Schema 在工具层提前拦截非法输入。配合清晰的错误信息与充分的测试覆盖它可以直接嵌入研究型 Agent 的工作流中作为“先检索、再作答”的关键一步。若需深入了解各配置项与底层行为可继续阅读 search.ts、client.ts 及其对应的 测试用例。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考