Skip to main content

构建一个可以上网搜索的智能代理

🌐 Building an Agent that can search the web

在构建网页搜索代理时，你需要考虑两种主要策略：

🌐 When building a web search agent, you have two main strategies to consider:

  1. 来自大型语言模型的原生搜索工具：某些语言模型提供开箱即用的集成网页搜索功能。
  2. 实现自定义搜索工具：开发你自己的与搜索提供商 API 的集成，以处理查询并获取结果。

先决条件
Direct link to 先决条件

🌐 Prerequisites

  • 已安装 Node.js v22.13.0 或更高版本
  • 来自支持的模型提供商的 API 密钥
  • 一个现有的 Mastra 项目（按照安装指南设置新项目）

使用本地搜索工具
Direct link to 使用本地搜索工具

🌐 Using native search tools

一些大型语言模型提供商内置了网页搜索功能，可以直接使用，无需额外的 API 集成。OpenAI 的 GPT-4o-mini 和 Google 的 Gemini 2.5 Flash 都提供了模型在生成过程中可以调用的本地搜索工具。

🌐 Some LLM providers include built-in web search capabilities that can be used directly without additional API integrations. OpenAI's GPT-4o-mini and Google's Gemini 2.5 Flash both offer native search tools that the model can invoke during generation.

  1. 安装依赖

    🌐 Install dependencies

    npm install @ai-sdk/openai

  2. 创建一个新文件 src/mastra/agents/searchAgent.ts 并定义你的代理：

    🌐 Create a new file src/mastra/agents/searchAgent.ts and define your 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.1",
    });

  3. 设置工具：

    🌐 Setup the 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.1",
      tools: {
        webSearch: openai.tools.webSearch()
      }
    });

  4. 在你的 src/mastra/index.ts 文件中，注册代理：

    🌐 In your src/mastra/index.ts file, register the 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 中测试你的代理：

    🌐 You can test your agent with Studio using the mastra dev command:

    mastra dev

    在 Studio 内，导航到 "搜索代理" 并询问它："上周 AI 新闻发生了什么？"

    🌐 Inside Studio navigate to the "Search Agent" and ask it: "What happened last week in AI news?"

使用搜索 API
Direct link to 使用搜索 API

🌐 Using Search APIs

为了更好地控制搜索行为，你可以将外部搜索 API 集成为自定义工具。Exa 是专门为 AI 应用构建的搜索引擎，提供语义搜索、可配置过滤器（类别、字段、日期范围）以及获取完整页面内容的能力。搜索 API 被封装在一个 Mastra 工具中，该工具定义了输入 schema、输出格式和执行逻辑。

🌐 For more control over search behavior, you can integrate external search APIs as custom tools. Exa is a search engine built specifically for AI applications, offering semantic search, configurable filters (category, domain, date range), and the ability to retrieve full page contents. The search API is wrapped in a Mastra tool that defines the input schema, output format, and execution logic.

  1. 安装依赖

    🌐 Install dependencies

    npm install exa-js

  2. 创建一个新文件 src/mastra/agents/searchAgent.ts 并定义你的代理：

    🌐 Create a new file src/mastra/agents/searchAgent.ts and define your 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.1",
    });

  3. 设置工具

    🌐 Setup the 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. 添加到你的代理

    🌐 Add to your 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.1",
      tools: {
        webSearch,
      },
    });

  5. 在你的 src/mastra/index.ts 文件中，注册代理：

    🌐 In your src/mastra/index.ts file, register the 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 中测试你的代理：

    🌐 You can test your agent with Studio using the mastra dev command:

    mastra dev

    在 Studio 内，导航到 "搜索代理" 并询问它："上周 AI 新闻发生了什么？"

    🌐 Inside Studio navigate to the "Search Agent" and ask it: "What happened last week in AI news?"

目录