Mastra mit Bright Data für webfähige KI-Agenten integrieren

In diesem Tutorial lernen Sie:

• Was Mastra als Lösung zum Aufbau von KI-Agenten ist und welche Vorteile es bietet.
• Warum Mastra-KI-Agenten deutlich leistungsfähiger werden, wenn sie das Web erkunden können.
• Wie Sie einen Mastra-KI-Agenten mit Webzugriff dank der Integration von Bright Data-Tools erstellen.
• (Optional) Wie Sie Mastra mit dem Bright Data Web MCP verbinden.

Legen wir los!

Was ist Mastra?

Mastra ist ein modernes TypeScript-Framework zum Aufbau KI-gestützter Agenten und Anwendungen. Es bietet eine API zum Erstellen und Verwalten von Agenten, Workflows, RAG, Memory, MCP und Observability in einem einheitlichen System.

Mastra ist Open Source und weit verbreitet, mit über 23,8k GitHub-Stars. Das spiegelt ein starkes Community-Vertrauen und ein schnell wachsendes Ökosystem wider.

Die wichtigsten Funktionen der Lösung sind:

• Agents: Entwickeln Sie autonome KI-Agenten, die denken, Tools verwenden und iterieren, um komplexe nutzerdefinierte Aufgaben zu lösen.
• Workflows: Orchestrieren Sie mehrstufige Prozesse mit strukturierter graphbasierter Ausführung, Verzweigungen, parallelen Schritten und deterministischer Steuerungslogik.
• RAG: Verbinden Sie Agenten mit externen Wissensquellen für fundierte, kontextbewusste Antworten mithilfe von Retrieval-Augmented-Generation-Pipelines.
• Memory: Verwalten Sie Kurz- und Langzeitkontext, damit Agenten Gespräche in Erinnerung behalten und die Kontinuität über Interaktionen hinweg verbessern können.
• Tools: Erweitern Sie die Fähigkeiten von Agenten mit externen APIs, Funktionen und Integrationen, die reale Aktionen und dynamischen Datenzugriff ermöglichen.
• MCP: Integrieren Sie Model Context Protocol-Server, um Tools, Agenten und strukturierte Ressourcen systemübergreifend bereitzustellen und zu nutzen.
• Observability: Verfolgen, bewerten und debuggen Sie das Agentenverhalten mithilfe von Logs, Traces, Metriken und Performance-Evaluierungs-Tools.

Erfahren Sie mehr in der offiziellen Dokumentation.

Warum Mastra-KI-Agenten mit Websuche und Scraping-Tools erweitern

Mastra ist ein umfangreiches Framework zum Aufbau KI-gesteuerter Anwendungen und Agenten. Selbst gut konzipierte KI-Systeme können jedoch driften oder minderwertige Ausgaben liefern, wenn sie auf veraltete oder unvollständige Informationen angewiesen sind.

Dies ist eine grundlegende Einschränkung von LLMs, die auf statischen Datensätzen trainiert werden und daher keine Echtzeit-Wahrnehmung besitzen. Infolgedessen können sie halluzinieren oder Entscheidungen auf Basis veralteter Kontextinformationen treffen, was Genauigkeit und Zuverlässigkeit mindert.

Um dieses Problem zu lösen, benötigen KI-Anwendungen Zugang zu einer Echtzeit-Webdaten-Infrastruktur. Genau hier kommt Bright Data ins Spiel!

Die Lösung: Bright Data-Tools für Mastra

Bright Data unterstützt Mastra durch die folgenden offiziellen Tools:

• webSearch: Führt Websuchen über Suchmaschinen wie Google, Bing, Yandex und andere durch. Es liefert strukturierte SERP-Ergebnisse im JSON-Format, die für KI-Agenten aufbereitet sind. Unterstützt durch Bright Data’s SERP API.
• webFetch: Ruft Inhalte von beliebigen Webseiten mithilfe von Bright Data’s Web Unlocker API ab. Es umgeht Bot-Schutz und CAPTCHA-Systeme, um auf Live-Webdaten aus jeder Domain zuzugreifen.

Mit dieser Open-Source-Integration erhalten Mastra-Anwendungen Zugang zu einer produktionsreifen Webdaten-Infrastruktur. Damit können Agenten neue Quellen entdecken, Echtzeitinformationen abrufen und die Lücke zwischen Trainingsdaten und aktueller Realität schließen.

Was Bright Data auszeichnet, ist seine umfangreiche globale Infrastruktur mit über 400 Millionen Residential-IPs in 195 Ländern. Sie ermöglicht unbegrenzte Parallelität bei einer Verfügbarkeit von 99,99 % und einer Erfolgsrate von 99,95 %.

So erstellen Sie einen Mastra-KI-Agenten mit Bright Data für Webdatenzugriff

Dieser Schritt-für-Schritt-Abschnitt führt Sie durch die Einrichtung eines neuen Mastra-KI-Agenten, der mit Bright Data-Tools integriert ist.

Folgen Sie den nachstehenden Anweisungen!

Voraussetzungen

Um dieses Tutorial zu absolvieren, stellen Sie sicher, dass Sie folgendes haben:

• Git lokal installiert.
• Node.js v22.13.0 oder höher installiert (die neueste LTS-Version wird empfohlen).
• Einen API-Schlüssel von einem von Mastra unterstützten KI-Modellanbieter (in diesem Fall verwenden wir einen OpenAI-API-Schlüssel).
• Ein Bright Data-Konto mit einem eingerichteten API-Schlüssel. Um ein Bright Data-Konto zu erstellen und einen API-Schlüssel zu konfigurieren, folgen Sie dem offiziellen Dokumentationsleitfaden.

Schritt #1: Ein neues Mastra-Projekt initialisieren

Hinweis: Falls Sie bereits ein Mastra-Projekt haben, können Sie diesen Schritt überspringen.

Erstellen Sie zunächst ein neues Mastra-Projekt namens mastra-bright-data-web-access-agent mithilfe des create-mastra-Dienstprogramms:

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

Wenn Sie dazu aufgefordert werden, wählen Sie Ihren KI-Anbieter aus.

Wählen Sie in diesem Fall „OpenAI”, dann die Option zur manuellen Eingabe eines API-Schlüssels. Fügen Sie Ihren OpenAI-API-Schlüssel ein, wenn Sie dazu aufgefordert werden:

Anschließend werden Sie gefragt, ob Sie die Mastra-Observability aktivieren möchten. Entscheiden Sie nach Ihren Präferenzen und fahren Sie dann mit den verbleibenden Einrichtungsschritten fort.

Nach Abschluss der Einrichtung wechseln Sie in Ihr Projektverzeichnis:

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

Sie sollten nun eine Projektstruktur ähnlich der folgenden sehen:

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  

Der Ordner enthält das Standard-Mastra-Wetter-KI-Agentenprojekt. Dies ist eine minimale Vorlage, die zeigt, wie man Agenten, Tools, Scorer und Workflows in Mastra erstellt.

Erkunden Sie die Dateien und machen Sie sich mit ihnen vertraut. Öffnen Sie zum Beispiel die .env-Datei. Sie sollten Ihren während der Einrichtung konfigurierten OpenAI-API-Schlüssel sehen. Sie können den Agenten auch direkt ausführen mit:

npm run dev

Gut gemacht! Ihr Mastra-Projekt ist nun eingerichtet und bereit, mit Bright Data-Tools erweitert zu werden.

Schritt #2: Die Bright Data-Tools installieren und konfigurieren

Installieren Sie zunächst die Mastra-Bright-Data-Tools zusammen mit der erforderlichen zod-Abhängigkeit:

npm install @mastra/brightdata zod

Das @mastra/brightdata-Paket umschließt das Bright Data JavaScript SDK und stellt seine Methoden für Scraping und Websuche als Mastra-kompatible Tools bereit.

Das Bright Data JavaScript SDK benötigt die Umgebungsvariable BRIGHTDATA_API_TOKEN zum Funktionieren. Fügen Sie diese zu Ihrer .env-Datei hinzu:

BRIGHTDATA_API_TOKEN="<YOUR_BRIGHT_DATA_API_KEY>"

Ersetzen Sie den Platzhalter <YOUR_BRIGHT_DATA_API_KEY> durch Ihren tatsächlichen Bright Data-API-Schlüssel. Der API-Schlüssel wird vom SDK verwendet, um Anfragen an die Bright Data-APIs zu authentifizieren.

Nach der Konfiguration können die @mastra/brightdata-Tools eine Verbindung zu Ihrem Bright Data-Konto herstellen. Bei der ersten Verwendung richtet das Bright Data SDK automatisch die erforderlichen APIs in Ihrem Bright Data-Dashboard ein, einschließlich der benötigten Web Unlocker API- und SERP API-Zonen:

Schritt #3: Die Bright Data-Tools hinzufügen

An diesem Punkt haben Sie die Bright Data Mastra-Tools installiert. Nun müssen Sie sie konfigurieren und Ihrem KI-Agenten zugänglich machen.

Erstellen Sie dazu eine neue Datei web-access.ts innerhalb von 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
})

Dieser Code ruft createBrightDataTools() aus dem @mastra/brightdata-Paket mit einer benutzerdefinierten Konfiguration auf. Beachten Sie, dass der erforderliche Bright Data-API-Schlüssel automatisch aus der Umgebungsvariable BRIGHTDATA_API_TOKEN gelesen wird. Ebenso werden die Zonennamen automatisch abgeleitet oder standardmäßig erstellt. Bei Bedarf können Sie sowohl den API-Schlüssel als auch die Zonen über zusätzliche Optionen in createBrightDataTools() explizit konfigurieren.

Die Funktion createBrightDataTools() generiert zwei Mastra-kompatible Tools:

• webSearch: Verwendet Bright Data’s SERP API, um Ihrem KI-Agenten Websuchfunktionen zu ermöglichen.
• webFetch: Ruft Bright Data’s Web Unlocker API auf, um Inhalte von beliebigen Webseiten abzurufen und zu scrapen.

Hinweis: Alternativ können Sie diese Tools auch einzeln mit createBrightDataSearchTool() und createBrightDataFetchTool() erstellen und konfigurieren. Dieser Ansatz wird empfohlen, wenn Sie eine granularere Steuerung bevorzugen.

Durch den Export dieser Tools können Sie sie später in Ihre Agentendefinition importieren, um Webzugriff zu aktivieren. Gut! Die Bright Data-Tools sind nun bereit für den Einsatz in einem Mastra-KI-Agenten.

Schritt #4: Den Web-Access-KI-Agenten erstellen

Jetzt ist es an der Zeit, einen Mastra-Agenten zu erstellen, der mit den Bright Data-Tools verbunden ist. Fügen Sie dazu eine Datei web-access-agent.ts unter dem Pfad src/mastra/agents/ hinzu und füllen Sie sie wie folgt aus:

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

Dieses Snippet definiert einen Mastra-KI-Agenten mit Websuche- und Scraping-Fähigkeiten, die von Bright Data unterstützt werden. Es befähigt den Agenten, aktuelle Online-Informationen abzurufen und Webseiten zu scrapen. Beachten Sie, dass es auch Memory-Unterstützung enthält, damit der Agent den Kontext über Interaktionen hinweg beibehalten kann.

Hervorragend! Der von Bright Data unterstützte Mastra-KI-Agent ist bereit.

Schritt #5: Den Agenten zum Index hinzufügen

Der letzte Schritt zum Abschluss der Mastra-Anwendung besteht darin, den webAccessAgent in der Datei src/mastra/index.ts zu registrieren:

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

Das obige Snippet initialisiert eine Mastra-Anwendung, indem der zuvor definierte Web-Access-KI-Agent registriert wird. Anschließend wird ein zusammengesetzter Speicher konfiguriert, damit das Agenten-Memory in einer lokalen mastra.db-Datei mit einem LibSQL-Store persistiert wird. Außerdem wird strukturiertes Logging über Pino aktiviert und Observability mit Exportern sowie Filterung sensibler Daten für Monitoring und Nachverfolgbarkeit eingerichtet.

Hinweis: Um Ihre Mastra-Anwendung schlank zu halten, sollten Sie die anfänglichen wetterbezogenen Tools, Workflows und Scorer entfernen.

Schritt #6: Den Web-Access-Agenten testen

Starten Sie Ihre Mastra-Anwendung mit:

npm run dev

Sie sollten eine ähnliche Ausgabe wie diese sehen:

Dies zeigt an, dass der lokale Mastra-Server unter http://localhost:4111 läuft. Öffnen Sie diese URL in Ihrem Browser, und Sie sollten das Mastra-Dashboard sehen:

Navigieren Sie zum Bereich „Tools”, und Sie sehen die beiden Bright Data-Tools, die aus src/mastra/tools/web-access.ts bereitgestellt werden:

Gehen Sie dann auf die Agentenseite und klicken Sie auf den Eintrag „Web Access Agent”:

Dadurch wird die Prompt-Benutzeroberfläche des Agenten geöffnet, in der Sie mit ihm chatten können. Um die Web-Erkundungsfähigkeiten des Agenten zu überprüfen, starten Sie einen Prompt wie diesen:

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.

Führen Sie ihn aus, und Sie sollten eine ähnliche Ausgabe wie diese erhalten:

Beachten Sie, dass Mastra die Websuch-Tools dreimal aufgerufen hat, um relevante Google-Suchanfragen durchzuführen. Diese liefern strukturierte SERP-Ergebnisse im JSON-Format, die von Google gescrapt wurden:

Aus diesen Ergebnissen wählt der Agent die relevantesten Links aus und verwendet webFetch, um deren Inhalte zu scrapen. Abschließend aggregiert er alles zu einem strukturierten Markdown-Bericht, der die heutigen Börsennachrichten zusammenfasst.

Et voilà! Dank der Bright Data-Integration verfügt Ihr Mastra-KI-Agent nun über unternehmenstaugliche Websuche- und Scraping-Fähigkeiten, die fundiertere Antworten ermöglichen. Probieren Sie verschiedene Prompts aus und testen Sie alle unterstützten Szenarien und Anwendungsfälle!

[Extra] Einen Mastra-KI-Agenten mit dem Bright Data Web MCP verbinden

Denken Sie daran, dass Mastra auch MCP-Integration unterstützt. Sie können Ihren Mastra-KI-Agenten also mit dem Bright Data Web MCP verbinden.

Der Web MCP-Server bietet Zugang zu über 70 Tools für Websuche, Scraping, Datenextraktion, Datenfeed-Abruf und Browser-Automatisierung. Beachten Sie, dass er mit einem kostenlosen Tarif (5.000 Anfragen/Monat) erhältlich ist.

Um MCP in Mastra zu verwenden, installieren Sie zunächst die erforderliche Abhängigkeit:

npm install @mastra/mcp@latest

Fügen Sie dann eine Datei src/mastra/mcp/bright-data-mcp-client.ts mit folgendem Inhalt hinzu:

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

Hierdurch wird der Bright Data MCP über das @brightdata/mcp-Paket gestartet. Der Server authentifiziert die Verbindung zu Ihrem Konto mithilfe der Umgebungsvariable API_TOKEN, die über BRIGHTDATA_API_TOKEN in der .env-Datei auf Ihren Bright Data-API-Schlüssel gesetzt werden sollte.

Beachten Sie, dass die Einstellung 'PRO_MODE': 'true' optional ist. Wenn aktiviert, bietet sie Zugang zum vollständigen Satz von über 70 Tools, kann jedoch auch nutzungsbasierte Kosten verursachen.

Verwenden Sie in Ihrer Mastra-Agentendatei Tools eines MCP-Servers, indem Sie den MCPClient importieren und .listTools() im Parameter tools aufrufen:

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

Wenn Sie die Mastra-Anwendung nun starten, sehen Sie die Bright Data Web MCP-Tools:

Web MCP stellt im Pro-Modus über 70 Tools bereit, oder die 5 Tools, die im Rapid-Modus (kostenloser Tarif) verfügbar sind.

Mission erfüllt! Ihr Mastra-KI-Agent ist nun über MCP mit der Bright Data-Infrastruktur verbunden.

Fazit

In diesem Blogbeitrag haben Sie verstanden, was Mastra ist und welche wichtigen Funktionen es bietet. Insbesondere haben Sie gesehen, wie und warum Sie es mithilfe der offiziellen Bright Data-Tools oder über Web MCP erweitern können.

Diese Integration hebt Mastra-Agenten auf ein völlig neues Niveau. KI-Agenten können nun Websuchen durchführen, strukturierte Daten entdecken und extrahieren sowie mit realen Websites interagieren.

Erstellen Sie noch heute ein kostenloses Bright Data-Konto und beginnen Sie, unsere KI-fähigen Webdaten-Tools zu integrieren!