Integra Mastra con Bright Data para agentes de IA web

En este tutorial aprenderás:

Qué es Mastra como solución para construir agentes de IA y qué ventajas ofrece.
Por qué los agentes de IA de Mastra se vuelven mucho más potentes cuando pueden explorar la web.
Cómo construir un agente de IA con Mastra que tenga acceso a la web gracias a la integración con las herramientas de Bright Data.
(Opcional) Cómo conectar Mastra al Web MCP de Bright Data.

¡Comencemos!

¿Qué es Mastra?

Mastra es un moderno framework de TypeScript para construir agentes y aplicaciones potenciados por IA. Proporciona una API para crear y gestionar agentes, flujos de trabajo, RAG, memoria, MCP y observabilidad en un sistema unificado.

El historial de estrellas de Mastra en GitHub

Mastra es de código abierto y ampliamente adoptado, con más de 23.8k estrellas en GitHub. Esto refleja una gran confianza de la comunidad y un rápido crecimiento del ecosistema.

Las principales funcionalidades que ofrece la solución son:

Agentes: Construye agentes de IA autónomos que razonan, usan herramientas e iteran para completar tareas complejas definidas por el usuario.
Flujos de trabajo: Orquesta procesos de múltiples pasos mediante ejecución estructurada basada en grafos con ramificaciones, pasos paralelos y lógica determinista controlada.
RAG: Conecta agentes a fuentes de conocimiento externas para obtener respuestas contextualizadas y fundamentadas mediante pipelines de generación aumentada por recuperación.
Memoria: Mantén el contexto a corto y largo plazo para que los agentes recuerden conversaciones y mejoren la continuidad entre interacciones.
Herramientas: Amplía las capacidades de los agentes con APIs externas, funciones e integraciones, habilitando acciones en el mundo real y acceso dinámico a datos.
MCP: Integra servidores Model Context Protocol para exponer y consumir herramientas, agentes y recursos estructurados entre sistemas.
Observabilidad: Rastrea, evalúa y depura el comportamiento de los agentes mediante registros, trazas, métricas y herramientas de evaluación de rendimiento.

Descubre más en la documentación oficial.

Por qué ampliar los agentes de IA de Mastra con herramientas de búsqueda web y scraping

Mastra es un framework rico para construir aplicaciones y agentes impulsados por IA. Sin embargo, incluso los sistemas de IA bien diseñados pueden derivar o producir resultados de baja calidad cuando dependen de información desactualizada o incompleta.

Esta es una limitación fundamental de los LLM, que se entrenan con conjuntos de datos estáticos y, por tanto, carecen de conciencia en tiempo real. Como resultado, pueden alucinar o tomar decisiones basadas en un contexto obsoleto, reduciendo la precisión y la fiabilidad.

Para resolver esto, las aplicaciones de IA necesitan acceso a una infraestructura de datos web en tiempo real. ¡Aquí es exactamente donde entra Bright Data!

La solución: herramientas de Bright Data para Mastra

Bright Data es compatible con Mastra a través de las siguientes herramientas oficiales:

webSearch: Realiza búsquedas web en motores como Google, Bing, Yandex y otros. Devuelve resultados SERP estructurados en formato JSON, listos para agentes de IA. Impulsado por la SERP API de Bright Data.
webFetch: Recupera contenido de cualquier página web utilizando la Web Unlocker API de Bright Data. Supera la protección antibot y los sistemas CAPTCHA para acceder a datos web en vivo desde cualquier dominio.

Con esta integración de código abierto, las aplicaciones de Mastra obtienen acceso a una infraestructura de datos web de nivel productivo. Esto permite a los agentes descubrir fuentes actualizadas, recuperar información en tiempo real y cerrar la brecha entre los datos de entrenamiento y la realidad actual.

Lo que distingue a Bright Data es su extensa infraestructura global de más de 400 millones de IPs residenciales distribuidas en 195 países. Permite concurrencia ilimitada manteniendo un tiempo de actividad del 99.99% y una tasa de éxito del 99.95%.

Cómo construir un agente de IA con Mastra conectado a Bright Data para acceso a datos web

Esta sección paso a paso te guiará por el proceso de configurar un nuevo agente de IA con Mastra integrado con las herramientas de Bright Data.

¡Sigue las instrucciones a continuación!

Requisitos previos

Para completar este tutorial, asegúrate de tener:

Git instalado localmente.
Node.js v22.13.0 o posterior instalado (se recomienda la última versión LTS).
Una clave API de un proveedor de modelos de IA compatible con Mastra (en este caso, utilizaremos una clave API de OpenAI).
Una cuenta de Bright Data con una clave API configurada. Para crear una cuenta de Bright Data y configurar una clave API, consulta la guía de la documentación oficial.

Paso #1: Inicializar un nuevo proyecto de Mastra

Nota: Si ya tienes un proyecto de Mastra en marcha, puedes omitir este paso.

Comienza creando un nuevo proyecto de Mastra llamado mastra-bright-data-web-access-agent usando la utilidad create-mastra:

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

Cuando se te solicite, selecciona tu proveedor de IA.

Seleccionar el proveedor de IA para tu proyecto de Mastra

En este caso, elige "OpenAI", luego selecciona la opción para introducir una clave API manualmente. Pega tu clave API de OpenAI cuando se te solicite:

A continuación, se te preguntará si deseas habilitar la observabilidad de Mastra. Elige según tu preferencia y continúa con los pasos de configuración restantes.

Una vez completada la configuración, navega al directorio de tu proyecto:

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

Ahora deberías ver una estructura de proyecto similar 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

La carpeta contiene el proyecto de agente meteorológico de Mastra por defecto. Es una plantilla mínima diseñada para demostrar cómo construir agentes, herramientas, scorers y flujos de trabajo en Mastra.

Explora los archivos y familiarízate con ellos. Por ejemplo, abre el archivo .env. Deberías ver tu clave API de OpenAI configurada durante la instalación. Considera también ejecutar el agente con:

npm run dev

¡Excelente! Tu proyecto de Mastra ya está configurado y listo para ampliarse con las herramientas de Bright Data.

Paso #2: Instalar y configurar las herramientas de Bright Data

Comienza instalando las herramientas de Mastra para Bright Data junto con la dependencia zod necesaria:

npm install @mastra/brightdata zod

El paquete @mastra/brightdata envuelve el SDK de JavaScript de Bright Data y expone sus métodos de scraping y búsqueda web como herramientas compatibles con Mastra.

El SDK de JavaScript de Bright Data requiere la variable de entorno BRIGHTDATA_API_TOKEN para funcionar. Agrégala a tu archivo .env:

BRIGHTDATA_API_TOKEN="<YOUR_BRIGHT_DATA_API_KEY>"

Reemplaza el marcador <YOUR_BRIGHT_DATA_API_KEY> con tu clave API real de Bright Data. La clave API es utilizada por el SDK para autenticar las solicitudes a las APIs de Bright Data.

Una vez configurado, las herramientas de @mastra/brightdata podrán conectarse a tu cuenta de Bright Data. En el primer uso, el SDK de Bright Data aprovisionará automáticamente las APIs necesarias en tu panel de control de Bright Data, incluyendo las zonas requeridas de Web Unlocker API y SERP API:

Observa las zonas del SDK configuradas por el SDK de Bright Data

Paso #3: Añadir las herramientas de Bright Data

En este punto, has instalado las herramientas de Mastra para Bright Data. Ahora necesitas configurarlas y exponerlas a tu agente de IA.

Para ello, crea un nuevo archivo 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 llama a createBrightDataTools() del paquete @mastra/brightdata con una configuración personalizada. Ten en cuenta que la clave API de Bright Data requerida se lee automáticamente desde la variable de entorno BRIGHTDATA_API_TOKEN. De igual manera, los nombres de las zonas se infieren automáticamente o se crean por defecto. Si es necesario, puedes configurar explícitamente tanto la clave API como las zonas mediante opciones adicionales en createBrightDataTools().

La función createBrightDataTools() genera dos herramientas compatibles con Mastra:

webSearch: Utiliza la SERP API de Bright Data para habilitar capacidades de búsqueda web en tu agente de IA.
webFetch: Llama a la Web Unlocker API de Bright Data para recuperar y hacer scraping de contenido de cualquier sitio web.

Nota: Como alternativa, también puedes crear y configurar estas herramientas individualmente con createBrightDataSearchTool() y createBrightDataFetchTool(). Este es el enfoque recomendado si prefieres un control más granular.

Exportar estas herramientas te permite importarlas más tarde en la definición de tu agente para habilitar el acceso a la web. ¡Perfecto! Las herramientas de Bright Data ya están listas para usarse en un agente de IA de Mastra.

Paso #4: Crear el agente de IA con acceso a la web

Ahora es el momento de crear un agente de Mastra conectado a las herramientas de Bright Data. Para ello, añade un archivo web-access-agent.ts en la ruta src/mastra/agents/ y complétalo como se indica a continuación:

// 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 fragmento define un agente de IA de Mastra con capacidades de búsqueda web y scraping respaldadas por Bright Data. Permite al agente recuperar información actualizada de la web y hacer scraping de páginas. Ten en cuenta que también incluye soporte de memoria, para que el agente pueda mantener el contexto entre interacciones.

¡Fantástico! El agente de IA de Mastra potenciado por Bright Data está listo.

Paso #5: Añadir el agente al índice

El último paso para completar la aplicación de Mastra es registrar el webAccessAgent en el archivo 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(),
        ],
      },
    },
  }),
})

El fragmento anterior inicializa una aplicación de Mastra registrando el agente de IA con acceso a la web definido previamente. Luego configura el almacenamiento compuesto para que la memoria del agente se persista en un archivo local mastra.db utilizando un almacén LibSQL. También habilita el registro estructurado mediante Pino y configura la observabilidad con exportadores y filtrado de datos sensibles para monitoreo y trazabilidad.

Nota: Para mantener tu aplicación de Mastra liviana, considera eliminar las herramientas, flujos de trabajo y scorers relacionados con el clima inicial.

Paso #6: Probar el agente con acceso a la web

Ejecuta tu aplicación de Mastra con:

npm run dev

Deberías ver una salida similar a esta:

Esto indica que el servidor local de Mastra está corriendo en http://localhost:4111. Abre esa URL en tu navegador y deberías ver el panel de control de Mastra:

Navega a la sección "Tools" y verás las dos herramientas de Bright Data expuestas desde src/mastra/tools/web-access.ts:

Las herramientas de Bright Data definidas en "src/mastra/tools/web-access.ts"

Luego, ve a la página de Agentes y haz clic en la entrada "Web Access Agent":

Esto abrirá la interfaz de prompts del agente, donde puedes chatear con él. Para verificar las capacidades de exploración web del agente, lanza un 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.

Ejecútalo y deberías ver una salida como esta:

Observa que Mastra llamó a las herramientas de búsqueda web tres veces para realizar consultas de búsqueda relevantes en Google. Estas devuelven resultados SERP estructurados en JSON, extraídos de Google:

Los resultados estructurados en JSON devueltos por la herramienta "webSearch" de Bright Data

A partir de estos resultados, el agente selecciona los enlaces más relevantes y usa webFetch para hacer scraping de su contenido. Finalmente, agrega todo en un informe Markdown estructurado que resume las noticias del mercado de valores del día.

¡Et voilà! Gracias a la integración con Bright Data, tu agente de IA de Mastra ahora tiene capacidades de búsqueda web y scraping de nivel empresarial, lo que permite respuestas más fundamentadas. ¡Prueba distintos prompts y explora todos los escenarios y casos de uso soportados!

[Extra] Conectar un agente de IA de Mastra al Web MCP de Bright Data

Recuerda que Mastra también es compatible con la integración MCP. Por lo tanto, puedes conectar tu agente de IA de Mastra al Web MCP de Bright Data.

El servidor Web MCP proporciona acceso a más de 70 herramientas para búsqueda web, scraping, extracción de datos, recuperación de feeds de datos y automatización de navegadores. Recuerda que incluye un plan gratuito (5k solicitudes/mes).

Para usar MCP en Mastra, primero instala la dependencia necesaria:

npm install @mastra/mcp@latest

Luego, añade un archivo src/mastra/mcp/bright-data-mcp-client.ts con el siguiente contenido:

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

Esto lanza el MCP de Bright Data a través del paquete @brightdata/mcp. El servidor autentica la conexión a tu cuenta usando la variable de entorno API_TOKEN, que debe estar configurada con tu clave API de Bright Data mediante BRIGHTDATA_API_TOKEN en el archivo .env.

Ten en cuenta que la configuración 'PRO_MODE': 'true' es opcional. Cuando está habilitada, proporciona acceso al conjunto completo de más de 70 herramientas, pero también puede generar cargos basados en el uso.

En el archivo de tu agente de Mastra, usa las herramientas de un servidor MCP importando el MCPClient y llamando a .listTools() en el 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(),
})

Si ahora ejecutas la aplicación de Mastra, verás las herramientas del Web MCP de Bright Data:

Observa las herramientas del Web MCP de Bright Data

El Web MCP expone más de 70 herramientas en modo Pro, o las 5 herramientas disponibles en el modo Rapid (nivel gratuito).

¡Misión cumplida! Tu agente de IA de Mastra ya está conectado a la infraestructura de Bright Data a través de MCP.

Conclusión

En esta entrada del blog, comprendiste qué es Mastra y las funcionalidades clave que ofrece. En particular, viste cómo y por qué ampliarlo usando las herramientas oficiales de Bright Data o a través del Web MCP.

Esta integración lleva a los agentes de Mastra a un nivel completamente nuevo. Los agentes de IA ahora pueden realizar búsquedas web, descubrir y extraer datos estructurados e interactuar con sitios web del mundo real.

¡Crea una cuenta gratuita de Bright Data hoy mismo y comienza a integrar nuestras herramientas de datos web listas para IA!

Contactar Ventas Prueba gratuita