Integrazione Olostep + Vercel AI SDK

L’integrazione Olostep AI SDK offre agli agenti costruiti con il Vercel AI SDK strumenti pronti all’uso per i dati web live. Olostep è un’API di ricerca, scraping e crawling web: un’API per cercare, estrarre e strutturare dati web. Passa gli strumenti a generateText o streamText e il modello decide quando cercare, fare scraping o crawling. Installa da npm →

Caratteristiche

Il pacchetto fornisce 6 strumenti:

Scrape

Esegui scraping di qualsiasi URL e restituisci markdown pulito, con rendering JavaScript

Search

Cerca nel web live e restituisci titoli, URL e descrizioni

Answer

Rispondi a una domanda dal web live, con URL di origine

Map

Elenca gli URL su un sito web, eventualmente classificati per una query

Crawl

Esegui crawling di un sito da un URL iniziale e restituisci il markdown di ogni pagina

Batch

Esegui scraping di un elenco di URL in un batch e restituisci il markdown di ciascuno

Installazione

npm install @olostep/ai-sdk ai zod

yarn add @olostep/ai-sdk ai zod

pnpm add @olostep/ai-sdk ai zod

Funziona con AI SDK 5, 6 e 7, Zod 3.25+ o 4, e Node.js 18+.

Configurazione

Imposta la tua chiave API Olostep come variabile di 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 Olostep.

Avvio Rapido

Passa tutti gli strumenti Olostep al modello con olostepTools():

import { generateText, stepCountIs } from 'ai';
import { olostepTools } from '@olostep/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  tools: olostepTools(),
  stopWhen: stepCountIs(5),
  prompt: 'Leggi le note di rilascio di Next.js 15 e elenca i cambiamenti significativi, con fonti.',
});

console.log(text);

stopWhen consente al modello di chiamare strumenti su più passaggi, ad esempio cercare prima e poi fare scraping del miglior risultato. La stringa del modello utilizza il Vercel AI Gateway. Puoi anche passare qualsiasi modello del provider AI SDK, come openai('gpt-5-mini') da @ai-sdk/openai.

Seleziona Strumenti Individuali

Dai al modello solo gli strumenti di cui ha bisogno:

import { olostepScrape, olostepSearch } from '@olostep/ai-sdk';

const tools = {
  scrape: olostepScrape(),
  search: olostepSearch(),
};

Strumenti Disponibili

I nomi degli strumenti di seguito sono le chiavi utilizzate da olostepTools().

scrape

olostepScrape(). Esegui scraping di un singolo URL e restituisci il suo contenuto come markdown. Input:

string

obbligatorio

L’URL della pagina da eseguire scraping

number

Millisecondi da attendere per il rendering delle pagine pesanti di JavaScript (0 a 10000)

Restituisce: { url, markdown }

search

olostepSearch(). Cerca nel web live. Input:

string

obbligatorio

La query di ricerca

number

predefinito:"10"

Numero massimo di risultati (1 a 20)

Restituisce: { query, results: [{ title, url, description }] }

answer

olostepAnswer(). Cerca e leggi il web live per rispondere a una domanda, con fonti. Input:

string

obbligatorio

La domanda o il compito di ricerca

Restituisce: { answer, sources }

map

olostepMap(). Scopri gli URL su un sito web. Input:

string

obbligatorio

Il sito web da mappare

string

Classifica gli URL per rilevanza a questa query

number

Numero massimo di URL da restituire (1 a 500)

Restituisce: { url, urls }

crawl

olostepCrawl(). Esegui crawling di un sito web da un URL iniziale e restituisci il markdown di ogni pagina. Lo strumento attende che il crawling sia completato prima di restituire. Input:

string

obbligatorio

L’URL da cui iniziare il crawling

number

predefinito:"5"

Pagine massime da eseguire crawling (1 a 25)

array

Esegui crawling solo degli URL che corrispondono a questi pattern glob, ad esempio ["/docs/**"]

Restituisce: { url, pages: [{ url, markdown }] }

batch

olostepBatch(). Esegui scraping di un elenco di URL in un batch e restituisci il markdown di ogni pagina. Lo strumento attende che il batch sia completato prima di restituire. Input:

array

obbligatorio

Gli URL da eseguire scraping (1 a 20)

Restituisce: { pages: [{ url, markdown }] }

Gli strumenti di crawling e batch sono limitati a 25 pagine e 20 URL per chiamata per mantenere i risultati degli strumenti abbastanza piccoli per il modello. Per lavori più grandi, chiama direttamente le API Crawls e Batches con l’SDK Node.js.

Opzioni

Ogni strumento, e olostepTools(), accetta le stesse opzioni:

olostepTools({
  apiKey: 'olostep_...',   // predefinito a process.env.OLOSTEP_API_KEY
  maxCharacters: 20_000,   // massimo contenuto della pagina restituito al modello, per pagina
  timeoutSeconds: 300,     // quanto tempo gli strumenti di crawling e batch attendono che il lavoro sia completato
});

string

Chiave API Olostep. Predefinito alla variabile di ambiente OLOSTEP_API_KEY.

number

predefinito:"20000"

Numero massimo di caratteri del contenuto della pagina restituito al modello per pagina. Le pagine più lunghe vengono troncate.

number

predefinito:"300"

Quanto tempo gli strumenti di crawling e batch attendono che il lavoro sia completato, in secondi.

Esempio di Streaming

Usa gli stessi strumenti con streamText, ad esempio in un gestore di rotte Next.js:

app/api/chat/route.ts

import { convertToModelMessages, streamText, stepCountIs, type UIMessage } from 'ai';
import { olostepTools } from '@olostep/ai-sdk';

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: 'openai/gpt-5-mini',
    system: 'Sei un assistente di ricerca. Usa gli strumenti web e cita le tue fonti.',
    messages: await convertToModelMessages(messages),
    tools: olostepTools(),
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}

Casi d’Uso Popolari

Assistente di Ricerca

Il modello utilizza search o answer per trovare le fonti
Utilizza scrape per leggere le pagine più rilevanti
Restituisce un riassunto con URL di origine

Agente di Codifica Consapevole dei Documenti

Il modello utilizza map con un searchQuery per trovare le pagine di documentazione giuste
Utilizza batch o crawl per leggerle
Scrive codice contro l’API corrente invece di indovinare

Monitoraggio dei Competitor e dei Prezzi

Un lavoro programmato chiama generateText con scrape e batch
Il modello estrae prezzi o cambiamenti da ogni pagina
Il tuo codice li confronta con l’ultima esecuzione e invia avvisi

Migliori Pratiche

Passa Solo gli Strumenti di Cui Hai Bisogno

La descrizione di ogni strumento viene inviata al modello. Meno strumenti significano meno token e meno scelte sbagliate di strumenti. Per una chat che legge solo pagine, scrape e search sono spesso sufficienti.

Imposta un Limite di Passaggi

Imposta sempre stopWhen (ad esempio stepCountIs(5)) in modo che il modello possa concatenare le chiamate agli strumenti ma non possa entrare in un loop infinito.

Riduci maxCharacters per Pagine Lunghe

Il contenuto delle pagine è la parte più grande del costo dei token. Se esegui crawling o batch di molte pagine, riduci maxCharacters in modo che tutti i risultati si adattino alla finestra di contesto del modello.

Aumenta timeoutSeconds per Grandi Crawl

Gli strumenti di crawling e batch attendono che il lavoro sia completato. Se si verificano timeout, aumenta timeoutSeconds, o riduci maxPages.

Risoluzione dei Problemi

Autenticazione Fallita

Errore: “Chiave API non valida”Soluzioni:

Controlla la tua chiave API nel dashboard
Assicurati che OLOSTEP_API_KEY sia impostato dove il tuo codice viene eseguito (ad esempio nelle variabili di ambiente del tuo progetto Vercel)
Oppure passa la chiave direttamente con olostepTools({ apiKey })

Il Modello Non Chiama gli Strumenti

Soluzioni:

Imposta stopWhen, altrimenti la generazione si interrompe dopo il primo passaggio
Usa un modello che supporta le chiamate agli strumenti
Menziona il web nel tuo prompt o messaggio di sistema, ad esempio “usa gli strumenti web e cita le tue fonti”

Crawl o Batch Scade

Soluzioni:

Aumenta timeoutSeconds
Riduci maxPages o passa meno URL
Su funzioni serverless, assicurati che il limite di tempo della funzione sia più lungo di timeoutSeconds

Lunghezza del Contesto Superata

Soluzioni:

Riduci maxCharacters
Usa map con searchQuery per scegliere meno pagine, ma più rilevanti, prima di leggerle

Prezzi

Olostep addebita in base all’uso dell’API, indipendentemente dall’AI SDK:

Scrapes: Pagamento per scraping
Searches e Answers: Pagamento per richiesta
Batches: Pagamento per URL nel batch
Crawls: Pagamento per pagina eseguita in crawling
Maps: Pagamento per operazione di mappatura

Controlla i prezzi attuali su olostep.com/pricing.

Supporto

GitHub

Codice sorgente e problemi

Email di Supporto

Email: info@olostep.com

Documentazione AI SDK

Scopri di più sul Vercel AI SDK

Documentazione

Sfoglia la documentazione completa dell’API

Risorse Correlate

API Scrapes

Scopri di più sull’endpoint Scrapes

API Crawls

Scopri di più sull’endpoint Crawls

Integrazione Mastra

Costruisci agenti con Mastra

Integrazione LangChain

Costruisci agenti AI con LangChain

​Caratteristiche

Scrape

Search

Answer

Map

Crawl

Batch

​Installazione

​Configurazione

​Avvio Rapido

​Seleziona Strumenti Individuali

​Strumenti Disponibili

​scrape

​search

​answer

​map

​crawl

​batch

​Opzioni

​Esempio di Streaming

​Casi d’Uso Popolari

​Migliori Pratiche

​Risoluzione dei Problemi

​Prezzi

​Supporto

GitHub

Email di Supporto

Documentazione AI SDK

Documentazione

​Risorse Correlate

API Scrapes

API Crawls

Integrazione Mastra

Integrazione LangChain

Caratteristiche

Installazione

Configurazione

Avvio Rapido

Seleziona Strumenti Individuali

Strumenti Disponibili

scrape

search

answer

map

crawl

batch

Opzioni

Esempio di Streaming

Casi d’Uso Popolari

Migliori Pratiche

Risoluzione dei Problemi

Prezzi

Supporto

Risorse Correlate