> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 构建可搜索网页的 Agent

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

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

## 前提条件

- 已安装 Node.js `v22.13.0` 或更高版本
- 受支持的 [Model Provider](https://mastra.zisheng.pro/models) 提供的 API 密钥
- 现有的 Mastra 项目（按照[安装指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)设置新项目）

## 使用原生搜索 Tool

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

1. 安装依赖项

   **OpenAI**:

   **npm**:

   ```bash
   npm install @ai-sdk/openai
   ```

   **pnpm**:

   ```bash
   pnpm add @ai-sdk/openai
   ```

   **Yarn**:

   ```bash
   yarn add @ai-sdk/openai
   ```

   **Bun**:

   ```bash
   bun add @ai-sdk/openai
   ```

   **Gemini**:

   ```bash
   npm install @ai-sdk/openai
   ```

   **Tab 3**:

   ```bash
   pnpm add @ai-sdk/openai
   ```

   **Tab 4**:

   ```bash
   yarn add @ai-sdk/openai
   ```

   **Tab 5**:

   ```bash
   bun add @ai-sdk/openai
   ```

   **Tab 6**:

   **npm**:

   ```bash
   npm install @ai-sdk/google
   ```

   **pnpm**:

   ```bash
   pnpm add @ai-sdk/google
   ```

   **Yarn**:

   ```bash
   yarn add @ai-sdk/google
   ```

   **Bun**:

   ```bash
   bun add @ai-sdk/google
   ```

   **Tab 7**:

   ```bash
   npm install @ai-sdk/google
   ```

   **Tab 8**:

   ```bash
   pnpm add @ai-sdk/google
   ```

   **Tab 9**:

   ```bash
   yarn add @ai-sdk/google
   ```

   **Tab 10**:

   ```bash
   bun add @ai-sdk/google
   ```

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

   **OpenAI**:

   ```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',
   })
   ```

   **Gemini**:

   ```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: 'google/gemini-2.5-flash',
   })
   ```

3. 设置 Tool：

   **OpenAI**:

   ```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(),
     },
   })
   ```

   **Gemini**:

   ```ts
   import { google } from '@ai-sdk/google'
   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: 'google/gemini-2.5-flash',
     tools: {
       webSearch: google.tools.googleSearch({
         mode: 'MODE_DYNAMIC',
       }),
     },
   })
   ```

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

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

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

5. 你可以使用 `mastra dev` 命令，在 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 中测试 Agent：

   ```bash
   mastra dev
   ```

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

## 使用搜索 API

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

1. 安装依赖项

   **npm**:

   ```bash
   npm install exa-js
   ```

   **pnpm**:

   ```bash
   pnpm add exa-js
   ```

   **Yarn**:

   ```bash
   yarn add exa-js
   ```

   **Bun**:

   ```bash
   bun add exa-js
   ```

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

   ```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

   ```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

   ```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：

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

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

6. 你可以使用 `mastra dev` 命令，在 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 中测试 Agent：

   ```bash
   mastra dev
   ```

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