Giving a Mastra agent web access with Bright Data

Bright Data just published a guide to giving Mastra agents web access: Integrate Mastra with Bright Data for Web-Aware AI Agents. It walks through wiring webSearch and webFetch into an agent with @mastra/brightdata. Two lines of setup and your agent can read the live web instead of guessing from training data that froze months ago.

There are two parts worth understanding that come after: how the agent uses the tools, and whether to use the typed tools or the Web MCP.

What the agent does between search and answer

Bright Data's tutorial ends with the prompt: "Search for the latest stock market news, extract and analyze the content, and return a structured Markdown report." The agent calls webSearch three times, picks the best links, fetches them, and writes the report.

The agent gets there by running a loop. It decides when to search, reads the structured results back, decides which pages to open, fetches those, and only then synthesizes. The runtime drives the cycle, and the tools just do what they're told.

What comes back is shaped for the model. webSearch returns parsed organic results (link, title, description) instead of a wall of HTML, so the model can rank and choose without burning tokens on page chrome:

// @mastra/brightdata — createBrightDataSearchTool output
{
  query: "latest stock market news",
  results: [
    { link: "https://…", title: "…", description: "…" },
    // …
  ],
  currentPage: 1
}

Then webFetch returns the chosen page as clean Markdown, so the model reads the content without wading through HTML:

// @mastra/brightdata — createBrightDataFetchTool output
{ url: "https://…", content: "# Markets today\n\n…" }

That division of labor is the whole design. Search is for discovery and ranking, fetch for reading. The model orchestrates between them. Bright Data's infrastructure handles the part that breaks in production (bot detection, CAPTCHAs, geo-blocks), so the loop doesn't stall on a page that won't load.

The demo also wires up memory:

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { webFetch, webSearch } from '../tools/web-access'
 
export const webAccessAgent = new Agent({
  id: 'web-access-agent',
  name: 'Web Access Agent',
  instructions: '…',
  model: 'openai/gpt-5-mini',
  tools: { webFetch, webSearch },
  memory: new Memory(),
})

A single stock-news prompt doesn't lean on new Memory(), since one turn has nothing to remember. It's there for the second turn. Ask a follow-up like "now compare that to last week," and the agent has the prior report, the links it already fetched, and the reasoning that got there. Without memory, every turn restarts cold and re-fetches the same pages. With it, the loop compounds: research from turn one becomes context for turn two. Memory is what turns search into research.

Tools or MCP: how to wire in access

Bright Data's tutorial shows two ways to give the agent web access and leaves the choice to you.

The typed tools package (@mastra/brightdata) gives you exactly two tools: webSearch and webFetch. They ship with full Zod input/output schemas, so the model gets a small, predictable surface and you get type safety end to end:

import { createBrightDataTools } from '@mastra/brightdata'
 
export const { webSearch, webFetch } = createBrightDataTools()

The Web MCP connects the same agent to Bright Data's MCP server, which exposes 70+ tools (search, scraping, structured data feeds, browser automation) discovered at runtime:

import { MCPClient } from '@mastra/mcp'
 
export const brightDataMcpClient = new MCPClient({
  servers: {
    'bright-data': {
      command: 'npx',
      args: ['-y', '@brightdata/mcp'],
      env: { API_TOKEN: process.env.BRIGHTDATA_API_TOKEN || '' },
    },
  },
})
// tools: { ...await brightDataMcpClient.listTools() }

It's the same agent loop with a very different tool surface:

Start with the typed tools. Two well-described tools mean the model rarely picks the wrong one, the schemas are stable, and you can read every line of the surface you're exposing. Reach for the Web MCP when the job outgrows search-and-read — product feeds, LinkedIn data, or full browser automation, without writing a wrapper per endpoint.

A small surface keeps the agent reliable, while a broad one makes it more capable. Most projects start with the first and grow into the second.

Get started

Bright Data's tutorial has the full setup, step by step. The short version:

npm install @mastra/brightdata zod

Wire webSearch and webFetch in, set BRIGHTDATA_API_TOKEN, and the agent can see the live web. The @mastra/brightdata reference has the full API.