> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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 `v22.13.0` or later installed
- An API key from a supported [Model Provider](https://mastra.ai/models)
- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) 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 and Google's models both offer native search tools that the model can invoke during generation.

1. Install dependencies

   **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. Create a new file `src/mastra/agents/searchAgent.ts` and define your 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.5',
   })
   ```

   **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. Setup the 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.5',
     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. In your `src/mastra/index.ts` file, register the agent:

   ```ts
   import { Mastra } from '@mastra/core'
   import { searchAgent } from './agents/searchAgent'

   export const mastra = new Mastra({
     agents: { searchAgent },
   })
   ```

5. You can test your agent with [Studio](https://mastra.ai/docs/studio/overview) using the `mastra dev` command:

   ```bash
   mastra dev
   ```

   Inside Studio 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](https://exa.ai/) 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**:

   ```bash
   npm install exa-js
   ```

   **pnpm**:

   ```bash
   pnpm add exa-js
   ```

   **Yarn**:

   ```bash
   yarn add exa-js
   ```

   **Bun**:

   ```bash
   bun add exa-js
   ```

2. Create a new file `src/mastra/agents/searchAgent.ts` and define your 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.5',
   })
   ```

3. Setup the 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. Add to your 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.5',
     tools: {
       webSearch,
     },
   })
   ```

5. In your `src/mastra/index.ts` file, register the agent:

   ```ts
   import { Mastra } from '@mastra/core'
   import { searchAgent } from './agents/searchAgent'

   export const mastra = new Mastra({
     agents: { searchAgent },
   })
   ```

6. You can test your agent with [Studio](https://mastra.ai/docs/studio/overview) using the `mastra dev` command:

   ```bash
   mastra dev
   ```

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