跳到主要内容

构建可搜索网页的 Agent

构建网页搜索 Agent 时，主要有两种策略可供选择：

  1. LLM 的原生搜索 Tool：某些语言模型内置开箱即用的网页搜索能力。
  2. 实现自定义搜索 Tool：自行与搜索 Provider API 集成，以处理查询并检索结果。

前提条件
前提条件的直接链接

  • 已安装 Node.js v22.13.0 或更高版本
  • 受支持的 Model Provider 提供的 API 密钥
  • 现有的 Mastra 项目（按照安装指南设置新项目）

使用原生搜索 Tool
使用原生搜索 Tool的直接链接

一些 LLM Provider 包含内置的网页搜索功能，无需额外集成 API 即可直接使用。OpenAI 和 Google 的模型都提供原生搜索 Tool，模型可以在生成过程中调用它们。

  1. 安装依赖项

    npm install @ai-sdk/openai

  2. 新建文件 src/mastra/agents/searchAgent.ts 并定义 Agent：

    src/mastra/agents/searchAgent.ts
    import { Agent } from '@mastra/core/agent'

    export const searchAgent = new Agent({
      id: 'search-agent',
      name: 'Search Agent',
      instructions: 'You are a search agent that can search the web for information.',
      model: 'openai/gpt-5.6-sol',
    })

  3. 设置 Tool：

    src/mastra/agents/searchAgent.ts
    import { openai } from '@ai-sdk/openai'
    import { Agent } from '@mastra/core/agent'

    export const searchAgent = new Agent({
      id: 'search-agent',
      name: 'Search Agent',
      instructions: 'You are a search agent that can search the web for information.',
      model: 'openai/gpt-5.6-sol',
      tools: {
        webSearch: openai.tools.webSearch(),
      },
    })

  4. 在 src/mastra/index.ts 文件中注册 Agent：

    src/mastra/index.ts
    import { Mastra } from '@mastra/core'
    import { searchAgent } from './agents/searchAgent'

    export const mastra = new Mastra({
      agents: { searchAgent },
    })

  5. 你可以使用 mastra dev 命令，在 Studio 中测试 Agent：

    mastra dev

    在 Studio 中转到 “Search Agent” 并询问：“上周 AI 新闻中发生了什么？”

使用搜索 API
使用搜索 API的直接链接

如需更精细地控制搜索行为，可以将外部搜索 API 集成为自定义 Tool。Exa 是一个专为 AI 应用构建的搜索引擎，提供语义搜索、可配置的筛选条件（类别、域名、日期范围），并且能够检索完整页面内容。搜索 API 封装在一个 Mastra Tool 中，该 Tool 定义输入 schema、输出格式和执行逻辑。

  1. 安装依赖项

    npm install exa-js

  2. 新建文件 src/mastra/agents/searchAgent.ts 并定义 Agent：

    src/mastra/agents/searchAgent.ts
    import { Agent } from '@mastra/core/agent'

    export const searchAgent = new Agent({
      id: 'search-agent',
      name: 'Search Agent',
      instructions: 'You are a search agent that can search the web for information.',
      model: 'openai/gpt-5.6-sol',
    })

  3. 设置 Tool

    src/mastra/tools/searchTool.ts
    import { createTool } from '@mastra/core/tools'
    import z from 'zod'
    import Exa from 'exa-js'

    export const exa = new Exa(process.env.EXA_API_KEY)

    export const webSearch = createTool({
      id: 'exa-web-search',
      description: 'Search the web',
      inputSchema: z.object({
        query: z.string().min(1).max(50).describe('The search query'),
      }),
      outputSchema: z.array(
        z.object({
          title: z.string().nullable(),
          url: z.string(),
          content: z.string(),
          publishedDate: z.string().optional(),
        }),
      ),
      execute: async inputData => {
        const { results } = await exa.searchAndContents(inputData.query, {
          livecrawl: 'always',
          numResults: 2,
        })

        return results.map(result => ({
          title: result.title,
          url: result.url,
          content: result.text.slice(0, 500),
          publishedDate: result.publishedDate,
        }))
      },
    })

  4. 添加到 Agent

    src/mastra/agents/searchAgent.ts
    import { webSearch } from './tools/searchTool'

    export const searchAgent = new Agent({
      id: 'search-agent',
      name: 'Search Agent',
      instructions: 'You are a search agent that can search the web for information.',
      model: 'openai/gpt-5.6-sol',
      tools: {
        webSearch,
      },
    })

  5. 在 src/mastra/index.ts 文件中注册 Agent：

    src/mastra/index.ts
    import { Mastra } from '@mastra/core'
    import { searchAgent } from './agents/searchAgent'

    export const mastra = new Mastra({
      agents: { searchAgent },
    })

  6. 你可以使用 mastra dev 命令，在 Studio 中测试 Agent：

    mastra dev

    在 Studio 中转到 “Search Agent” 并询问：“上周 AI 新闻中发生了什么？”

On this page