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

# 建立可搜尋網絡的 Agent

建立網絡搜尋 Agent 時，主要有兩種策略可供考慮：

1. **LLM 的原生搜尋 Tool**：部分語言模型提供開箱即用的整合式網絡搜尋功能。
2. **實作自訂搜尋 Tool**：自行與搜尋 Provider 的 API 整合，以處理查詢及擷取結果。

## 先決條件

- 已安裝 Node.js `v22.13.0` 或更新版本
- 由支援的[模型 Provider](https://mastra.zisheng.pro/zh-HK/models) 提供的 API 金鑰
- 現有的 Mastra 項目（按照[安裝指南](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)設定新項目）

## 使用原生搜尋 Tool

部分 LLM Provider 內置網絡搜尋功能，無需額外整合 API 即可直接使用。OpenAI 和 Google 的模型均提供原生搜尋 Tool，模型可在生成內容期間調用這些 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/zh-HK/docs/studio/overview) 中測試 Agent：

   ```bash
   mastra dev
   ```

   在 Studio 中前往 **「Search Agent」**，然後向它提問：「上星期 AI 新聞有甚麼新消息？」

## 使用搜尋 API

如要更精細地控制搜尋行為，你可以將外部搜尋 API 整合為自訂 Tool。[Exa](https://exa.ai/) 是專為 AI 應用程式而設的搜尋引擎，提供語意搜尋、可設定的篩選條件（類別、網域、日期範圍），以及擷取完整網頁內容的功能。搜尋 API 封裝在 Mastra Tool 中，由 Tool 定義輸入結構描述、輸出格式和執行邏輯。

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/zh-HK/docs/studio/overview) 中測試 Agent：

   ```bash
   mastra dev
   ```

   在 Studio 中前往 **「Search Agent」**，然後向它提問：「上星期 AI 新聞有甚麼新消息？」