> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrazione Olostep + Vercel AI SDK

> Fornisci agli agenti dell’AI SDK ricerca web live, scraping, crawling e risposte citate con strumenti Olostep pronti all’uso

L'integrazione Olostep AI SDK offre agli agenti costruiti con il [Vercel AI SDK](https://ai-sdk.dev) 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 →](https://www.npmjs.com/package/@olostep/ai-sdk)

## 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

```bash npm theme={null}
npm install @olostep/ai-sdk ai zod
```

```bash yarn theme={null}
yarn add @olostep/ai-sdk ai zod
```

```bash pnpm theme={null}
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:

```bash theme={null}
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](https://www.olostep.com/dashboard).

## Avvio Rapido

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

```typescript theme={null}
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](https://vercel.com/docs/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:

```typescript theme={null}
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:**

**url** `string` *required*

L'URL della pagina da eseguire scraping

**waitBeforeScraping** `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:**

**query** `string` *required*

La query di ricerca

**limit** `number` (default: 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:**

**task** `string` *required*

La domanda o il compito di ricerca

**Restituisce:** `{ answer, sources }`

### map

`olostepMap()`. Scopri gli URL su un sito web.

**Input:**

**url** `string` *required*

Il sito web da mappare

**searchQuery** `string`

Classifica gli URL per rilevanza a questa query

**topN** `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:**

**url** `string` *required*

L'URL da cui iniziare il crawling

**maxPages** `number` (default: 5)

Pagine massime da eseguire crawling (1 a 25)

**includeUrls** `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:**

**urls** `array` *required*

Gli URL da eseguire scraping (1 a 20)

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

> [!NOTE]
>
> 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](https://docs.olostep.com/features/crawls.md) e [Batches](https://docs.olostep.com/features/batches.md) con l'[SDK Node.js](https://docs.olostep.com/sdks/node-js.md).

## Opzioni

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

```typescript theme={null}
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
});
```

**apiKey** `string`

Chiave API Olostep. Predefinito alla variabile di ambiente `OLOSTEP_API_KEY`.

**maxCharacters** `number` (default: 20000)

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

**timeoutSeconds** `number` (default: 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:

```typescript app/api/chat/route.ts theme={null}
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**
>
> 1. Il modello utilizza `search` o `answer` per trovare le fonti
> 2. Utilizza `scrape` per leggere le pagine più rilevanti
> 3. Restituisce un riassunto con URL di origine

> **Agente di Codifica Consapevole dei Documenti**
>
> 1. Il modello utilizza `map` con un `searchQuery` per trovare le pagine di documentazione giuste
> 2. Utilizza `batch` o `crawl` per leggerle
> 3. Scrive codice contro l'API corrente invece di indovinare

> **Monitoraggio dei Competitor e dei Prezzi**
>
> 1. Un lavoro programmato chiama `generateText` con `scrape` e `batch`
> 2. Il modello estrae prezzi o cambiamenti da ogni pagina
> 3. 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](https://www.olostep.com/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](https://www.olostep.com/pricing).

## Supporto

> **[GitHub](https://github.com/olostep-api/olostep-ai-sdk)**
>
> Codice sorgente e problemi

> **[Email di Supporto](mailto:info@olostep.com)**
>
> Email: [info@olostep.com](mailto:info@olostep.com)

> **[Documentazione AI SDK](https://ai-sdk.dev/docs)**
>
> Scopri di più sul Vercel AI SDK

> **[Documentazione](https://docs.olostep.com)**
>
> Sfoglia la documentazione completa dell'API

## Risorse Correlate

> **[API Scrapes](https://docs.olostep.com/features/scrapes.md)**
>
> Scopri di più sull'endpoint Scrapes

> **[API Crawls](https://docs.olostep.com/features/crawls.md)**
>
> Scopri di più sull'endpoint Crawls

> **[Integrazione Mastra](https://docs.olostep.com/integrations/mastra.md)**
>
> Costruisci agenti con Mastra

> **[Integrazione LangChain](https://docs.olostep.com/integrations/langchain.md)**
>
> Costruisci agenti AI con LangChain


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.