Integre Mastra com Bright Data para Agentes de IA Web

Neste tutorial, você aprenderá:

O que é o Mastra como solução para criação de agentes de IA e o que ele oferece.
Por que os agentes de IA do Mastra se tornam muito mais poderosos quando podem explorar a web.
Como construir um agente de IA com o Mastra com acesso à web graças à integração com as ferramentas da Bright Data.
(Opcional) Como conectar o Mastra ao Web MCP da Bright Data.

Vamos começar!

O que é o Mastra?

Mastra é um framework TypeScript moderno para criação de agentes e aplicações com inteligência artificial. Ele fornece uma API para construir e gerenciar agentes, workflows, RAG, memória, MCP e observabilidade em um sistema unificado.

O histórico de estrelas do Mastra no GitHub

O Mastra é open source e amplamente adotado, com mais de 23,8 mil estrelas no GitHub. Isso reflete a forte confiança da comunidade e o rápido crescimento do ecossistema.

Os principais recursos oferecidos pela solução são:

Agentes: Crie agentes de IA autônomos que raciocinam, utilizam ferramentas e iteram para concluir tarefas complexas definidas pelo usuário.
Workflows: Orquestre processos de várias etapas usando execução estruturada baseada em grafos, com ramificações, etapas paralelas e lógica determinística controlada.
RAG: Conecte agentes a fontes de conhecimento externas para respostas fundamentadas e sensíveis ao contexto, usando pipelines de geração com recuperação aumentada.
Memória: Mantenha contexto de curto e longo prazo para que os agentes se lembrem de conversas e melhorem a continuidade entre interações.
Ferramentas: Amplie as capacidades dos agentes com APIs externas, funções e integrações, habilitando ações no mundo real e acesso a dados dinâmicos.
MCP: Integre servidores do Model Context Protocol para expor e consumir ferramentas, agentes e recursos estruturados entre sistemas.
Observabilidade: Rastreie, avalie e depure o comportamento dos agentes usando logs, rastreamentos, métricas e ferramentas de avaliação de desempenho.

Saiba mais na documentação oficial.

Por que Estender os Agentes de IA do Mastra com Ferramentas de Busca e Scraping na Web

O Mastra é um framework rico para criação de aplicações e agentes orientados por IA. No entanto, até sistemas de IA bem projetados podem produzir resultados imprecisos ou de baixa qualidade quando dependem de informações desatualizadas ou incompletas.

Essa é uma limitação central dos LLMs, que são treinados em conjuntos de dados estáticos e, portanto, não possuem consciência em tempo real. Como resultado, podem alucinar ou tomar decisões com base em contexto obsoleto, reduzindo a precisão e a confiabilidade.

Para resolver isso, as aplicações de IA precisam de acesso a uma infraestrutura de dados web em tempo real. É exatamente aqui que a Bright Data entra!

A Solução: Ferramentas da Bright Data para o Mastra

A Bright Data oferece suporte ao Mastra por meio das seguintes ferramentas oficiais:

webSearch: Realiza buscas na web em mecanismos como Google, Bing, Yandex e outros. Retorna resultados SERP estruturados em formato JSON, prontos para agentes de IA. Desenvolvido pela SERP API da Bright Data.
webFetch: Recupera conteúdo de qualquer página da web usando a Web Unlocker API da Bright Data. Contorna proteções contra bots e sistemas de CAPTCHA para acessar dados ao vivo de qualquer domínio.

Com essa integração open source, as aplicações Mastra ganham acesso a uma infraestrutura de dados web de nível produção. Isso permite que os agentes descubram fontes atualizadas, recuperem informações em tempo real e fechem a lacuna entre os dados de treinamento e a realidade atual.

O que diferencia a Bright Data é sua extensa infraestrutura global com mais de 400 milhões de IPs residenciais em 195 países. Ela permite concorrência ilimitada mantendo 99,99% de uptime e taxa de sucesso de 99,95%.

Como Construir um Agente de IA com o Mastra Conectado à Bright Data para Acesso a Dados Web

Esta seção passo a passo irá guiá-lo pelo processo de configuração de um novo agente de IA Mastra integrado às ferramentas da Bright Data.

Siga as instruções abaixo!

Pré-requisitos

Para seguir este tutorial, certifique-se de ter:

Git instalado localmente.
Node.js v22.13.0 ou superior instalado (recomenda-se a versão LTS mais recente).
Uma chave de API de um provedor de modelos de IA compatível com o Mastra (neste caso, utilizaremos uma chave de API da OpenAI).
Uma conta na Bright Data com uma chave de API configurada. Para criar uma conta na Bright Data e configurar uma chave de API, siga o guia da documentação oficial.

Passo #1: Inicializar um Novo Projeto Mastra

Observação: Se você já possui um projeto Mastra configurado, pode pular esta etapa.

Comece criando um novo projeto Mastra chamado mastra-bright-data-web-access-agent usando o utilitário create-mastra:

npx create-mastra@latest mastra-bright-data-web-access-agent

Quando solicitado, selecione seu provedor de IA.

Selecionando o provedor de IA para o seu projeto Mastra

Neste caso, escolha “OpenAI”, depois selecione a opção de inserir uma chave de API manualmente. Cole sua chave de API da OpenAI quando solicitado:

Em seguida, será perguntado se deseja habilitar a observabilidade do Mastra. Escolha conforme sua preferência e continue pelas etapas restantes da configuração.

Após a conclusão da configuração, navegue até o diretório do projeto:

cd mastra-bright-data-web-access-agent

Você deverá ver uma estrutura de projeto semelhante a esta:

mastra-bright-data-web-access-agent/    
├── .agents/           # Internal Mastra directory for agent skills, etc.
├── node_modules/
└── src/
│    └── mastra/
│        ├── index.ts              # Entry point that initializes the Mastra setup
│        ├── agents/
│        │   └── weather-agent.ts  # Defines the default Weather AI agent
│        ├── scorers/
│        │   └── weather-scorer.ts  # Scoring logic to evaluate or rank agent outputs
│        ├── tools/
│        │   └── weather-tool.ts    # External tool integrations used by the agent
│        └── workflows/
│            └── weather-workflow.ts  # Logic combining tools and agents
├── .env               # Environment variables (API keys, secrets, etc.)
├── .gitignore            
├── AGENTS.md          # Docs describing available agents and their behavior
├── package-lock.json     
├── package.json          
├── README.md          # Main project documentation
└── skills-lock.json

A pasta contém o projeto padrão do agente de clima do Mastra. Trata-se de um template mínimo projetado para demonstrar como construir agentes, ferramentas, scorers e workflows no Mastra.

Explore os arquivos e familiarize-se com eles. Por exemplo, abra o arquivo .env. Você deverá ver sua chave de API da OpenAI configurada durante a instalação. Considere também executar o agente com:

npm run dev

Muito bem! Seu projeto Mastra está configurado e pronto para ser estendido com as ferramentas da Bright Data.

Passo #2: Instalar e Configurar as Ferramentas da Bright Data

Comece instalando as ferramentas Mastra da Bright Data junto com a dependência necessária zod:

npm install @mastra/brightdata zod

O pacote @mastra/brightdata encapsula o SDK JavaScript da Bright Data e expõe seus métodos de scraping e busca na web como ferramentas compatíveis com o Mastra.

O SDK JavaScript da Bright Data requer a variável de ambiente BRIGHTDATA_API_TOKEN para funcionar. Adicione-a ao seu arquivo .env:

BRIGHTDATA_API_TOKEN="<YOUR_BRIGHT_DATA_API_KEY>"

Substitua o placeholder <YOUR_BRIGHT_DATA_API_KEY> pela sua chave de API real da Bright Data. A chave de API é usada pelo SDK para autenticar requisições às APIs da Bright Data.

Uma vez configuradas, as ferramentas @mastra/brightdata poderão se conectar à sua conta Bright Data. No primeiro uso, o SDK da Bright Data provisionará automaticamente as APIs necessárias no seu painel da Bright Data, incluindo as zonas necessárias da Web Unlocker API e da SERP API:

Observe as zonas do SDK configuradas pelo SDK da Bright Data

Passo #3: Adicionar as Ferramentas da Bright Data

Neste ponto, você instalou as ferramentas Mastra da Bright Data. Agora, é necessário configurá-las e disponibilizá-las para o seu agente de IA.

Para isso, crie um novo arquivo web-access.ts dentro de src/mastra/tools/:

// src/mastra/tools/web-access.ts

import { createBrightDataTools } from '@mastra/brightdata'

// create the web search and web fetch tools using the BrightData client options
export const { webSearch, webFetch } = createBrightDataTools({
  verbose: true, // enable verbose logging for debugging purposes
})

Este código chama createBrightDataTools() do pacote @mastra/brightdata com uma configuração personalizada. Note que a chave de API da Bright Data necessária é lida automaticamente da variável de ambiente BRIGHTDATA_API_TOKEN. Da mesma forma, os nomes das zonas são inferidos automaticamente ou criados por padrão. Se necessário, você pode configurar explicitamente tanto a chave de API quanto as zonas por meio de opções adicionais em createBrightDataTools().

A função createBrightDataTools() gera duas ferramentas compatíveis com o Mastra:

webSearch: Usa a SERP API da Bright Data para habilitar capacidades de busca na web para o seu agente de IA.
webFetch: Aciona a Web Unlocker API da Bright Data para buscar e fazer scraping de conteúdo de qualquer site.

Observação: Como alternativa, você também pode criar e configurar essas ferramentas individualmente com createBrightDataSearchTool() e createBrightDataFetchTool(). Essa é a abordagem recomendada se preferir um controle mais granular.

Exportar essas ferramentas permite importá-las posteriormente na definição do agente para habilitar o acesso à web. Ótimo! As ferramentas da Bright Data estão prontas para uso em um agente de IA Mastra.

Passo #4: Criar o Agente de IA com Acesso à Web

Agora é hora de criar um agente Mastra conectado às ferramentas da Bright Data. Para isso, adicione um arquivo web-access-agent.ts no caminho src/mastra/agents/ e preencha-o conforme abaixo:

// src/mastra/agents/web-access-agent.ts

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: `
    You are a helpful, general-purpose assistant with Bright Data web access capabilities.

    Goals:
    - Answer user questions by combining reasoning with fresh, tool-based information.
    - Prefer tools when information may be outdated or when factual accuracy is required.
    - Clearly reference tool outputs so users can trace where information comes from.

    Tool usage guidelines:
    - Start with the webSearch tool to gather relevant sources and context.
    - Use the webFetch tool to retrieve and analyze detailed content from specific pages.
`,
  model: 'openai/gpt-5-mini',
  tools: {
    webFetch,
    webSearch,
  },
  memory: new Memory(),
})

Este trecho define um agente de IA Mastra com capacidades de busca e scraping na web, sustentadas pela Bright Data. Ele capacita o agente a recuperar informações online atualizadas e fazer scraping de páginas web. Note que também inclui suporte a memória, para que o agente possa manter contexto entre interações.

Fantástico! O agente de IA Mastra com Bright Data está pronto.

Passo #5: Adicionar o Agente ao Índice

A última etapa para concluir a aplicação Mastra é registrar o webAccessAgent no arquivo src/mastra/index.ts:

// src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import { Observability, MastraStorageExporter, MastraPlatformExporter, SensitiveDataFilter } from '@mastra/observability'
import { webAccessAgent } from './agents/web-access-agent'

export const mastra = new Mastra({
  agents: { webAccessAgent },
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    }
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(),
          new MastraPlatformExporter(),
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(),
        ],
      },
    },
  }),
})

O trecho acima inicializa uma aplicação Mastra registrando o agente de IA com acesso à web definido anteriormente. Em seguida, configura o armazenamento composto para que a memória do agente seja persistida em um arquivo local mastra.db usando um armazenamento LibSQL. Também habilita o registro estruturado via Pino e configura a observabilidade com exporters e filtragem de dados sensíveis para monitoramento e rastreabilidade.

Observação: Para manter sua aplicação Mastra enxuta, considere remover as ferramentas, workflows e scorers relacionados ao clima da configuração inicial.

Passo #6: Testar o Agente com Acesso à Web

Execute sua aplicação Mastra com:

npm run dev

Você deverá ver uma saída semelhante a esta:

Isso indica que o servidor local do Mastra está rodando em http://localhost:4111. Abra essa URL no seu navegador e você verá o painel do Mastra:

Navegue até a seção “Tools” e você verá as duas ferramentas da Bright Data expostas pelo arquivo src/mastra/tools/web-access.ts:

As ferramentas da Bright Data definidas em

Em seguida, acesse a página de Agentes e clique na entrada “Web Access Agent”:

Isso abrirá a interface de prompt do agente, onde você poderá conversar com ele. Para verificar as capacidades de exploração web do agente, envie um prompt como:

Search for the latest stock market news on Google. Select the most relevant articles, extract and analyze their content, and return a structured Markdown report summarizing the key information, including links to learn more.

Execute-o e você deverá ver uma saída como esta:

Observe que o Mastra chamou as ferramentas de busca na web três vezes para realizar consultas relevantes no Google. Essas consultas retornam resultados SERP estruturados em JSON, extraídos do Google:

Os resultados estruturados em JSON retornados pela ferramenta

A partir desses resultados, o agente seleciona os links mais relevantes e usa o webFetch para fazer scraping do conteúdo. Por fim, agrega tudo em um relatório Markdown estruturado com um resumo das notícias do mercado de ações do dia.

Et voilà! Graças à integração com a Bright Data, seu agente de IA Mastra agora possui capacidades empresariais de busca e scraping na web, permitindo respostas mais fundamentadas. Experimente diferentes prompts e teste todos os cenários e casos de uso suportados!

[Extra] Conectar um Agente de IA Mastra ao Web MCP da Bright Data

Lembre-se de que o Mastra também oferece suporte à integração MCP. Assim, você pode conectar seu agente de IA Mastra ao Web MCP da Bright Data.

O servidor Web MCP fornece acesso a mais de 70 ferramentas para busca na web, scraping, extração de dados, recuperação de feeds de dados e automação de navegador. Lembre-se de que ele vem com um plano gratuito (5 mil requisições/mês).

Para usar MCP no Mastra, primeiro instale a dependência necessária:

npm install @mastra/mcp@latest

Em seguida, adicione um arquivo src/mastra/mcp/bright-data-mcp-client.ts contendo:

// src/mastra/mcp/bright-data-mcp-client.ts

import { MCPClient } from '@mastra/mcp'

export const brightDataMcpClient = new MCPClient({
  id: 'bright-data-mcp-client',
  servers: {
    'bright-data': {
      command: 'npx',
      args: ['-y', '@brightdata/mcp'],
      env: {
       'API_TOKEN': process.env.BRIGHTDATA_API_TOKEN || '',
       'PRO_MODE': 'true' // remove to enable free mode
      },
    },
  },
})

Isso inicia o MCP da Bright Data via o pacote @brightdata/mcp. O servidor autentica a conexão com sua conta usando a variável de ambiente API_TOKEN, que deve ser definida com sua chave de API da Bright Data por meio de BRIGHTDATA_API_TOKEN no arquivo .env.

Note que a configuração 'PRO_MODE': 'true' é opcional. Quando habilitada, fornece acesso ao conjunto completo de mais de 70 ferramentas, mas pode incorrer em cobranças baseadas em uso.

No arquivo do seu agente Mastra, use ferramentas de um servidor MCP importando o MCPClient e chamando .listTools() no parâmetro tools:

// src/mastra/agents/web-access-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { brightDataMcpClient } from '../mcp/bright-data-mcp-client'

export const webAccessAgent = new Agent({
  id: 'web-access-agent',
  name: 'Web Access Agent',
  // omitted for brevity...
  tools: {
    ...await brightDataMcpClient.listTools(),
  },
  memory: new Memory(),
})

Se você executar a aplicação Mastra agora, verá as ferramentas do Web MCP da Bright Data:

Observe as ferramentas do Web MCP da Bright Data

O Web MCP expõe mais de 70 ferramentas quando configurado no modo Pro, ou as 5 ferramentas disponíveis no modo Rapid (nível gratuito).

Missão cumprida! Seu agente de IA Mastra agora está conectado à infraestrutura da Bright Data via MCP.

Conclusão

Neste artigo, você entendeu o que é o Mastra e os principais recursos que ele oferece. Em particular, viu como e por que estendê-lo usando as ferramentas oficiais da Bright Data ou via Web MCP.

Essa integração eleva os agentes Mastra a um novo patamar. Os agentes de IA agora podem realizar buscas na web, descobrir e extrair dados estruturados e interagir com sites do mundo real.

Crie uma conta gratuita na Bright Data hoje mesmo e comece a integrar nossas ferramentas de dados web prontas para IA!

Contate-nos Teste grátis