跳至主要內容

建立可搜尋網路的 Agent

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

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

先決條件
「先決條件」的直接連結

  • 已安裝 Node.js v22.13.0 或更新版本
  • 具備支援的 Model Provider 所提供的 API 金鑰
  • 已有 Mastra 專案（請依照安裝指南設定新專案）

使用原生搜尋工具
「使用原生搜尋工具」的直接連結

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

  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」，並詢問：「What happened last week in AI news?」

使用搜尋 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」，並詢問：「What happened last week in AI news?」

On this page