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. Native search tools from the LLM: Certain language models offer integrated web search capabilities that work out of the box.
  2. Implement a custom search tool: Develop your own integration with a search provider's API to handle queries and retrieve results.

Prerequisites​

  • Node.js v20.0 or later installed
  • An API key from a supported Model Provider
  • An existing Mastra project (Follow the installation guide to set up a new project)

Using native search tools​

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.

Install dependencies​

npm install @ai-sdk/openai

Define the Agent​

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({
name: "Search Agent",
instructions:
"You are a search agent that can search the web for information.",
model: 'openai/gpt-4o-mini',
});

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({
name: "Search Agent",
instructions:
"You are a search agent that can search the web for information.",
model: 'openai/gpt-4o-mini',
tools: {
webSearch: openai.tools.webSearch()
}
});

Register the Agent with Mastra​

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 },
});

Test your agent​

You can test your agent inside Mastra's Playground using the mastra dev command:

mastra dev

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

Using Search APIs​

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.

Install dependencies​

npm install exa-js

Define the Agent​

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({
  name: "Search Agent",
  instructions:
    "You are a search agent that can search the web for information.",
  model: "openai/gpt-4o-mini",
});

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 ({ context }) => {
    const { results } = await exa.searchAndContents(context.query, {
      livecrawl: "always",
      numResults: 2,
    });

    return results.map((result) => ({
      title: result.title,
      url: result.url,
      content: result.text.slice(0, 500),
      publishedDate: result.publishedDate,
    }));
  },
});

Add to your Agent​

src/mastra/agents/searchAgent.ts
import { webSearch } from "./tools/searchTool";

export const searchAgent = new Agent({
  name: "Search Agent",
  instructions:
    "You are a search agent that can search the web for information.",
  model: "openai/gpt-4o-mini",
  tools: {
    webSearch,
  },
});

Register the Agent with Mastra​

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 },
});

Test your agent​

You can test your agent inside Mastra's Playground using the mastra dev command:

mastra dev

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