Vai al contenuto principale
L’integrazione Olostep Mastra porta potenti capacità di estrazione dati web agli agenti di Mastra.ai. Olostep è un’API di ricerca, scraping e crawling web — un’API per cercare, estrarre e strutturare dati web. Crea agenti AI intelligenti che possono autonomamente cercare, fare scraping, analizzare e strutturare dati da qualsiasi sito web. Installa da npm →

Caratteristiche

L’integrazione fornisce 4 potenti API per l’estrazione automatizzata di dati web:

Scrape Website

Estrai contenuti da qualsiasi URL singolo in più formati (Markdown, HTML, JSON, testo)

Batch Scrape URLs

Elabora fino a 100.000 URL in parallelo. Perfetto per l’estrazione di dati su larga scala

Create Crawl

Scopri e fai scraping autonomamente di interi siti web seguendo i link

Create Map

Estrai tutti gli URL da un sito web per l’analisi della struttura del sito e la scoperta di contenuti

Installazione

npm install @olostep/mastra-tools

Configurazione

1. Installa il Pacchetto

npm install @olostep/mastra-tools @mastra/core

2. Importa e Registra l’Integrazione

Nel tuo file di configurazione di Mastra:
import { Mastra } from '@mastra/core';
import { createOlostepIntegration } from '@olostep/mastra-tools';

// Crea l'integrazione Olostep
const olostep = createOlostepIntegration();

// Registra le API (questo le rende disponibili agli agenti)
olostep.registerApis();

// Aggiungi alla tua configurazione di Mastra
export const mastra = new Mastra({
  config: {
    integrations: [olostep],
    // ... altra configurazione
  },
});

3. Configura la Chiave API

Imposta la tua chiave API Olostep come variabile d’ambiente:
export OLOSTEP_API_KEY=your-api-key-here
Oppure nel tuo file .env:
OLOSTEP_API_KEY=your-api-key-here
Ottieni la tua chiave API dalla Dashboard di Olostep.

API Disponibili

L’integrazione espone 4 API che i tuoi agenti Mastra possono utilizzare:

scrapeWebsite

Estrai contenuti da un singolo URL. Supporta più formati e rendering JavaScript. Casi d’Uso:
  • Monitora pagine specifiche per cambiamenti
  • Estrai informazioni sui prodotti da siti e-commerce
  • Raccogli dati da articoli di notizie o post di blog
  • Recupera contenuti per aggregazione di contenuti
Parametri dello Schema:
apiKey
string
obbligatorio
La tua chiave API Olostep
url_to_scrape
string
obbligatorio
URL del sito web da fare scraping (deve includere http:// o https://)
formats
array
predefinito:"['markdown']"
Formati di output: [‘html’, ‘markdown’, ‘json’, ‘text’]
country
string
Codice del paese per contenuti specifici per località (es., “US”, “GB”, “CA”)
wait_before_scraping
number
Tempo di attesa in millisecondi per il rendering JavaScript (0-10000)
parser
string
ID parser opzionale per estrazione specializzata (es., “@olostep/amazon-product”)
Risposta:
  • id - ID dello scraping
  • url_to_scrape - URL fatto scraping
  • result.markdown_content - Contenuto Markdown
  • result.html_content - Contenuto HTML
  • result.json_content - Contenuto JSON
  • result.text_content - Contenuto testo
  • result.screenshot_hosted_url - URL dello screenshot (se disponibile)
  • result.markdown_hosted_url - URL Markdown ospitato
  • object - Tipo di oggetto (“scrape”)
  • created - Timestamp Unix
Esempio di Utilizzo:
// Nel tuo agente o flusso di lavoro
const result = await mastra.callApi({
  integrationName: 'olostep',
  api: 'scrapeWebsite',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      url_to_scrape: 'https://example.com',
      formats: ['markdown'],
      country: 'US',
    }
  }
});

batchScrape

Elabora più URL in parallelo (fino a 100.000 contemporaneamente). Perfetto per l’estrazione di dati su larga scala. Casi d’Uso:
  • Fai scraping di interi cataloghi di prodotti
  • Estrai dati da più risultati di ricerca
  • Elabora elenchi di URL da fogli di calcolo
  • Estrazione di contenuti in blocco
Parametri dello Schema:
apiKey
string
obbligatorio
La tua chiave API Olostep
batch_array
array
obbligatorio
Array di oggetti con campi url e opzionale custom_idEsempio: [{"url":"https://example.com","custom_id":"site1"}]
formats
array
predefinito:"['markdown']"
Formati di output per tutti gli URL
country
string
Codice del paese per scraping specifico per località
wait_before_scraping
number
Tempo di attesa in millisecondi per il rendering JavaScript
parser
string
ID parser opzionale per estrazione specializzata
Risposta:
  • batch_id - ID del batch (usalo per recuperare i risultati successivamente)
  • status - Stato dell’elaborazione
  • object - Tipo di oggetto (“batch”)
Esempio di Utilizzo:
const result = await mastra.callApi({
  integrationName: 'olostep',
  api: 'batchScrape',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      batch_array: [
        { url: 'https://example.com', custom_id: 'site1' },
        { url: 'https://test.com', custom_id: 'site2' },
      ],
      formats: ['markdown'],
    }
  }
});

createCrawl

Scopri e fai scraping autonomamente di interi siti web seguendo i link. Perfetto per siti di documentazione, blog e repository di contenuti. Casi d’Uso:
  • Fai crawling e archivia interi siti di documentazione
  • Estrai tutti i post di blog da un sito web
  • Crea basi di conoscenza da contenuti web
  • Monitora i cambiamenti nella struttura del sito
Parametri dello Schema:
apiKey
string
obbligatorio
La tua chiave API Olostep
start_url
string
obbligatorio
URL di partenza per il crawl (deve includere http:// o https://)
max_pages
number
predefinito:"10"
Numero massimo di pagine da fare crawling. Imposta a 1 per fare scraping solo dell’URL di partenza.
formats
array
predefinito:"['markdown']"
Formato per i contenuti fatti scraping
country
string
Codice del paese opzionale per crawling specifico per località
parser
string
ID parser opzionale per estrazione di contenuti specializzata
Risposta:
  • id - ID del crawl (usalo per recuperare i risultati successivamente)
  • object - Tipo di oggetto (“crawl”)
  • status - Stato del crawl
  • created - Timestamp Unix
Esempio di Utilizzo:
const result = await mastra.callApi({
  integrationName: 'olostep',
  api: 'createCrawl',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      start_url: 'https://docs.example.com',
      max_pages: 50,
      formats: ['markdown'],
    }
  }
});

createMap

Estrai tutti gli URL da un sito web per la scoperta di contenuti e l’analisi della struttura del sito. Casi d’Uso:
  • Crea sitemaps e diagrammi della struttura del sito
  • Scopri tutte le pagine prima di fare batch scraping
  • Trova pagine rotte o mancanti
  • Audit e analisi SEO
Parametri dello Schema:
apiKey
string
obbligatorio
La tua chiave API Olostep
url
string
obbligatorio
URL del sito web da cui estrarre i link (deve includere http:// o https://)
search_query
string
Query di ricerca opzionale per filtrare gli URL (es., “blog”)
top_n
number
Limita il numero di URL restituiti
include_urls
array
Pattern glob per includere percorsi specifici (es., [“/blog/**”])
exclude_urls
array
Pattern glob per escludere percorsi specifici (es., [“/admin/**”])
Risposta:
  • id - ID della mappa
  • object - Tipo di oggetto (“map”)
  • url - URL del sito web
  • total_urls - Totale degli URL trovati
  • urls - Array di URL scoperti
Esempio di Utilizzo:
const result = await mastra.callApi({
  integrationName: 'olostep',
  api: 'createMap',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      url: 'https://example.com',
      search_query: 'blog',
      top_n: 100,
      include_urls: ['/blog/**'],
    }
  }
});

Utilizzo con gli Agenti

Esempio di Agente Base

Crea un agente che possa fare scraping di siti web:
import { Agent } from '@mastra/core';
import { createOlostepIntegration } from '@olostep/mastra-tools';

const olostep = createOlostepIntegration();
olostep.registerApis();

const agent = new Agent({
  name: 'web-researcher',
  instructions: `
    Sei un assistente di ricerca web. Quando gli utenti ti chiedono di ottenere informazioni da un sito web,
    usa l'API Olostep scrapeWebsite per estrarre il contenuto, quindi riassumilo per loro.
  `,
  model: 'openai/gpt-4',
});

// L'agente può ora usare le API Olostep tramite il sistema API di Mastra

Esempio di Flusso di Lavoro dell’Agente

Crea un flusso di lavoro di ricerca che scopre e fa scraping di contenuti:
// 1. Mappa un sito web per scoprire gli URL
const mapResult = await mastra.callApi({
  integrationName: 'olostep',
  api: 'createMap',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      url: 'https://example.com',
      include_urls: ['/blog/**'],
    }
  }
});

// 2. Fai batch scraping degli URL scoperti
const batchResult = await mastra.callApi({
  integrationName: 'olostep',
  api: 'batchScrape',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      batch_array: mapResult.urls.slice(0, 10).map(url => ({ url })),
      formats: ['markdown'],
    }
  }
});

// 3. Elabora i risultati con il tuo agente
const summary = await agent.generate({
  messages: [{
    role: 'user',
    content: `Riassumi questo contenuto: ${batchResult.result.markdown_content}`
  }]
});

Casi d’Uso Popolari

Agente di Ricerca

Crea un agente che ricerca autonomamente argomenti:
Flusso di Lavoro:
  1. L’utente chiede: “Ricerca tendenze AI”
  2. L’agente utilizza createMap per scoprire pagine rilevanti
  3. L’agente utilizza batchScrape per estrarre contenuti
  4. L’agente analizza e riassume i risultati
  5. Restituisce un rapporto di ricerca strutturato
Flusso di Lavoro:
  1. Pianifica il monitoraggio giornaliero
  2. Usa scrapeWebsite per controllare le pagine dei concorrenti
  3. Confronta con i dati precedenti
  4. Avvisa su cambiamenti significativi
  5. Genera rapporti settimanali
Flusso di Lavoro:
  1. Usa createCrawl per scoprire tutti i post di blog
  2. Usa batchScrape per estrarre contenuti
  3. Elabora con AI per estrarre argomenti chiave
  4. Archivia nella base di conoscenza
  5. Genera un calendario dei contenuti

Intelligenza E-commerce

Monitora prodotti e prezzi:
Flusso di Lavoro dell'Agente:
1. Fai scraping delle pagine dei prodotti (scrapeWebsite)
2. Estrai dati strutturati (con parser)
3. Tieni traccia delle variazioni di prezzo
4. Genera avvisi
5. Aggiorna il database

Analisi SEO

Analizza la struttura e i contenuti del sito web:
Flusso di Lavoro dell'Agente:
1. Mappa la struttura del sito web (createMap)
2. Fai crawling delle sezioni importanti (createCrawl)
3. Analizza la qualità dei contenuti
4. Identifica opportunità SEO
5. Genera raccomandazioni

Parser Specializzati

Olostep fornisce parser pre-costruiti per siti web popolari. Usali con il parametro parser:

Google Search

@olostep/google-searchEstrai: risultati di ricerca, titoli, snippet, URL

Google Maps

@olostep/google-mapsEstrai: informazioni aziendali, recensioni, valutazioni, posizione

Utilizzo dei Parser

Aggiungi l’ID del parser al parametro parser:
const result = await mastra.callApi({
  integrationName: 'olostep',
  api: 'scrapeWebsite',
  payload: {
    data: {
      apiKey: process.env.OLOSTEP_API_KEY,
      url_to_scrape: 'https://www.amazon.com/dp/PRODUCT_ID',
      formats: ['json'],
      parser: '@olostep/amazon-product',
    }
  }
});
Il parser estrae automaticamente dati strutturati specifici per quel tipo di sito web.

Migliori Pratiche

Quando fai scraping di più di 3-5 URL, usa batchScrape invece di più chiamate scrapeWebsite. L’elaborazione in batch è:
  • Molto più veloce (elaborazione parallela)
  • Più conveniente
  • Più facile da gestire
  • Migliore per i limiti di velocità
Per i siti pesanti in JavaScript, usa il parametro wait_before_scraping:
  • Siti semplici: 0-1000ms
  • Siti dinamici: 2000-3000ms
  • JavaScript pesante: 5000-8000ms
Prova con valori diversi per trovare il tempo di attesa ottimale.
Per siti web popolari (Amazon, LinkedIn, Google), usa parser pre-costruiti:
  • Ottieni dati strutturati automaticamente
  • Estrazione più affidabile
  • Nessun bisogno di parsing personalizzato
  • Manutenzione da parte di Olostep
Le operazioni Batch, Crawl e Map sono asincrone:
  • Memorizza l’ID restituito (batch_id, crawl_id, map_id)
  • Interroga per il completamento o usa webhook
  • Imposta flussi di lavoro separati per il recupero
Avvolgi sempre le chiamate API in blocchi try-catch:
try {
  const result = await mastra.callApi({
    integrationName: 'olostep',
    api: 'scrapeWebsite',
    payload: { data: {...} }
  });
} catch (error) {
  // Gestisci errori di autenticazione, limiti di velocità o di rete
  console.error('Scraping fallito:', error.message);
}
Fai attenzione ai limiti di velocità:
  • Distribuisci le richieste con ritardi
  • Usa l’elaborazione in batch quando possibile
  • Monitora l’uso nella dashboard di Olostep
  • Aggiorna il piano se necessario

Esempio Completo

Ecco un esempio completo di costruzione di un agente di ricerca:
import { Mastra } from '@mastra/core';
import { Agent } from '@mastra/core';
import { createOlostepIntegration } from '@olostep/mastra-tools';

// Crea e registra l'integrazione Olostep
const olostep = createOlostepIntegration();
olostep.registerApis();

// Inizializza Mastra
export const mastra = new Mastra({
  config: {
    integrations: [olostep],
    // ... altra configurazione
  },
});

// Crea agente di ricerca
const researchAgent = new Agent({
  name: 'research-assistant',
  instructions: `
    Sei un assistente di ricerca che può cercare, estrarre e strutturare dati web.
    Quando gli utenti ti chiedono di ricercare un argomento:
    1. Usa createMap di Olostep per scoprire pagine rilevanti
    2. Usa batchScrape per estrarre contenuti da più fonti
    3. Analizza e riassumi i risultati
    4. Presenta rapporti di ricerca strutturati
  `,
  model: 'openai/gpt-4',
});

// Usa l'agente
async function researchTopic(topic: string) {
  // Step 1: Scopri pagine rilevanti
  const mapResult = await mastra.callApi({
    integrationName: 'olostep',
    api: 'createMap',
    payload: {
      data: {
        apiKey: process.env.OLOSTEP_API_KEY!,
        url: `https://example.com/search?q=${topic}`,
        top_n: 20,
      }
    }
  });

  // Step 2: Fai scraping delle pagine scoperte
  const batchResult = await mastra.callApi({
    integrationName: 'olostep',
    api: 'batchScrape',
    payload: {
      data: {
        apiKey: process.env.OLOSTEP_API_KEY!,
        batch_array: mapResult.urls.slice(0, 10).map(url => ({ url })),
        formats: ['markdown'],
      }
    }
  });

  // Step 3: Analizza con l'agente
  const summary = await researchAgent.generate({
    messages: [{
      role: 'user',
      content: `Basandoti su questi dati di ricerca, fornisci un riassunto completo di ${topic}`
    }]
  });

  return summary;
}

Risoluzione dei Problemi

Errore: “Chiave API non valida”Soluzioni:
  • Controlla la chiave API dalla dashboard
  • Assicurati che la chiave API sia impostata nella variabile d’ambiente
  • Verifica che la chiave API sia attiva
  • Controlla spazi extra nella chiave API
Errore: “API non trovata” o “Integrazione non registrata”Soluzioni:
  • Assicurati che registerApis() sia chiamato dopo la creazione dell’integrazione
  • Verifica che l’integrazione sia aggiunta alla configurazione di Mastra
  • Controlla che il nome dell’integrazione sia ‘olostep’
  • Riavvia il server Mastra dopo le modifiche
Errore: I campi di contenuto sono vuotiSoluzioni:
  • Aumenta il tempo wait_before_scraping
  • Controlla se il sito richiede il login
  • Prova un formato diverso (HTML vs Markdown)
  • Verifica che l’URL sia accessibile
  • Controlla se il sito blocca l’accesso automatizzato
Errore: “Limite di velocità superato”Soluzioni:
  • Distribuisci le richieste con ritardi
  • Usa l’elaborazione in batch invece di scraping individuali
  • Aggiorna il tuo piano Olostep
  • Controlla il limite di velocità nella dashboard
Errore: Modulo non trovato o errori di tipoSoluzioni:
  • Assicurati che @mastra/core sia installato
  • Controlla la compatibilità della versione TypeScript
  • Verifica che tutte le dipendenze siano installate
  • Ricostruisci: npm run build

Prezzi

Olostep addebita in base all’uso dell’API, indipendentemente da Mastra:
  • Scrapes: Paghi per ogni scraping
  • Batches: Paghi per URL nel batch
  • Crawls: Paghi per pagina fatta crawling
  • Maps: Paghi per operazione di mappa
Controlla i prezzi attuali su olostep.com/pricing.

Supporto

Hai bisogno di aiuto con l’integrazione Mastra?

Documentazione

Sfoglia la documentazione completa dell’API

Email di Supporto

Documenti Mastra

Scopri il framework Mastra

Risorse Correlate

Scrapes API

Scopri l’endpoint Scrapes

Batches API

Scopri l’endpoint Batches

Crawls API

Scopri l’endpoint Crawls

Maps API

Scopri l’endpoint Maps

Integrazione Zapier

Automatizza con i flussi di lavoro Zapier

Integrazione LangChain

Crea agenti AI con LangChain

Sito Web Mastra

Piattaforma Mastra

Inizia Subito

Pronto a costruire agenti AI con capacità di web scraping?

Installa il Pacchetto

Installa @olostep/mastra-tools da npm
Crea agenti AI intelligenti che possono cercare, estrarre e strutturare dati web con Olostep e Mastra!