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

# 建立可搜尋網路的 Agent

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

1. **使用 LLM 的原生搜尋工具**：部分語言模型提供整合式網路搜尋功能，無須額外設定即可使用。
2. **實作自訂搜尋工具**：自行整合搜尋供應商的 API，以處理查詢並擷取結果。

## 先決條件

- 已安裝 Node.js `v22.13.0` 或更新版本
- 具備支援的 [Model Provider](https://mastra.zisheng.pro/zh-TW/models) 所提供的 API 金鑰
- 已有 Mastra 專案（請依照[安裝指南](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)設定新專案）

## 使用原生搜尋工具

部分 LLM Provider 內建網路搜尋功能，不必整合額外的 API 即可直接使用。OpenAI 與 Google 的模型都提供原生搜尋工具，模型可在生成內容時呼叫這些工具。

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

   ```bash
   mastra dev
   ```

   在 Studio 中前往 **「Search Agent」**，並詢問：「What happened last week in AI news?」

## 使用搜尋 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/zh-TW/docs/studio/overview) 中測試 Agent：

   ```bash
   mastra dev
   ```

   在 Studio 中前往 **「Search Agent」**，並詢問：「What happened last week in AI news?」