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

# Intégration Olostep + Vercel AI SDK

> Donnez aux agents AI SDK la recherche web en direct, le scraping, le crawling et des réponses citées avec les outils prêts à l’emploi d’Olostep

L'intégration Olostep AI SDK offre aux agents construits avec le [Vercel AI SDK](https://ai-sdk.dev) des outils prêts à l'emploi pour les données web en direct. Olostep est une API de recherche, de scraping et de crawling web : une API pour rechercher, extraire et structurer les données web. Passez les outils à `generateText` ou `streamText` et le modèle décide quand rechercher, scraper ou crawler.

[Installer depuis npm →](https://www.npmjs.com/package/@olostep/ai-sdk)

## Fonctionnalités

Le package fournit 6 outils :

> **Scraper**
>
> Scrapez n'importe quelle URL et retournez un markdown propre, avec rendu JavaScript

> **Rechercher**
>
> Recherchez sur le web en direct et retournez les titres, URLs et descriptions

> **Répondre**
>
> Répondez à une question à partir du web en direct, avec les URLs sources

> **Carte**
>
> Listez les URLs sur un site web, éventuellement classées par une requête

> **Crawl**
>
> Crawlez un site à partir d'une URL de départ et retournez le markdown de chaque page

> **Lot**
>
> Scrapez une liste d'URLs en un seul lot et retournez le markdown de chacune

## Installation

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

Fonctionne avec AI SDK 5, 6 et 7, Zod 3.25+ ou 4, et Node.js 18+.

## Configuration

Définissez votre clé API Olostep comme une variable d'environnement :

```bash theme={null}
export OLOSTEP_API_KEY=your-api-key-here
```

Ou dans votre fichier `.env` :

```
OLOSTEP_API_KEY=your-api-key-here
```

Obtenez votre clé API depuis le [Tableau de bord Olostep](https://www.olostep.com/dashboard).

## Démarrage rapide

Passez tous les outils Olostep au modèle avec `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: 'Lisez les notes de version de Next.js 15 et listez les changements majeurs, avec les sources.',
});

console.log(text);
```

`stopWhen` permet au modèle d'appeler des outils sur plusieurs étapes, par exemple rechercher d'abord puis scraper le meilleur résultat. La chaîne de modèles utilise le [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Vous pouvez également passer n'importe quel modèle de fournisseur AI SDK, tel que `openai('gpt-5-mini')` de `@ai-sdk/openai`.

### Choisir des outils individuels

Ne donnez au modèle que les outils dont il a besoin :

```typescript theme={null}
import { olostepScrape, olostepSearch } from '@olostep/ai-sdk';

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

## Outils disponibles

Les noms d'outils ci-dessous sont les clés utilisées par `olostepTools()`.

### scrape

`olostepScrape()`. Scrapez une seule URL et retournez son contenu en markdown.

**Entrée :**

**url** `string` *required*

L'URL de la page à scraper

**waitBeforeScraping** `number`

Millisecondes à attendre pour que les pages lourdes en JavaScript se rendent (0 à 10000)

**Retourne :** `{ url, markdown }`

### search

`olostepSearch()`. Recherchez sur le web en direct.

**Entrée :**

**query** `string` *required*

La requête de recherche

**limit** `number` (default: 10)

Nombre maximum de résultats (1 à 20)

**Retourne :** `{ query, results: [{ title, url, description }] }`

### answer

`olostepAnswer()`. Recherchez et lisez le web en direct pour répondre à une question, avec les sources.

**Entrée :**

**task** `string` *required*

La question ou la tâche de recherche

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

### map

`olostepMap()`. Découvrez les URLs sur un site web.

**Entrée :**

**url** `string` *required*

Le site web à cartographier

**searchQuery** `string`

Classez les URLs par pertinence par rapport à cette requête

**topN** `number`

Nombre maximum d'URLs à retourner (1 à 500)

**Retourne :** `{ url, urls }`

### crawl

`olostepCrawl()`. Crawlez un site web à partir d'une URL de départ et retournez le markdown de chaque page. L'outil attend que le crawl soit terminé avant de retourner.

**Entrée :**

**url** `string` *required*

L'URL de départ pour le crawl

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

Nombre maximum de pages à crawler (1 à 25)

**includeUrls** `array`

Ne crawlez que les URLs correspondant à ces motifs globaux, par exemple `["/docs/**"]`

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

### batch

`olostepBatch()`. Scrapez une liste d'URLs en un seul lot et retournez le markdown de chaque page. L'outil attend que le lot soit terminé avant de retourner.

**Entrée :**

**urls** `array` *required*

Les URLs à scraper (1 à 20)

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

> [!NOTE]
>
> Les outils de crawl et de lot sont limités à 25 pages et 20 URLs par appel pour garder les résultats des outils suffisamment petits pour le modèle. Pour des tâches plus importantes, appelez directement les APIs [Crawls](https://docs.olostep.com/features/crawls.md) et [Batches](https://docs.olostep.com/features/batches.md) avec le [SDK Node.js](https://docs.olostep.com/sdks/node-js.md).

## Options

Chaque outil, ainsi que `olostepTools()`, accepte les mêmes options :

```typescript theme={null}
olostepTools({
  apiKey: 'olostep_...',   // par défaut à process.env.OLOSTEP_API_KEY
  maxCharacters: 20_000,   // contenu de page maximum retourné au modèle, par page
  timeoutSeconds: 300,     // durée d'attente des outils de crawl et de lot pour terminer le travail
});
```

**apiKey** `string`

Clé API Olostep. Par défaut à la variable d'environnement `OLOSTEP_API_KEY`.

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

Nombre maximum de caractères du contenu de page retourné au modèle par page. Les pages plus longues sont tronquées.

**timeoutSeconds** `number` (default: 300)

Durée d'attente des outils de crawl et de lot pour terminer le travail, en secondes.

## Exemple de streaming

Utilisez les mêmes outils avec `streamText`, par exemple dans un gestionnaire de route 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: 'Vous êtes un assistant de recherche. Utilisez les outils web et citez vos sources.',
    messages: await convertToModelMessages(messages),
    tools: olostepTools(),
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}
```

## Cas d'utilisation populaires

> **Assistant de recherche**
>
> 1. Le modèle utilise `search` ou `answer` pour trouver des sources
> 2. Il utilise `scrape` pour lire les pages les plus pertinentes
> 3. Il retourne un résumé avec les URLs sources

> **Agent de codage conscient des documents**
>
> 1. Le modèle utilise `map` avec une `searchQuery` pour trouver les bonnes pages de documentation
> 2. Il utilise `batch` ou `crawl` pour les lire
> 3. Il écrit du code en fonction de l'API actuelle au lieu de deviner

> **Surveillance des concurrents et des prix**
>
> 1. Un travail planifié appelle `generateText` avec `scrape` et `batch`
> 2. Le modèle extrait les prix ou les changements de chaque page
> 3. Votre code les compare avec la dernière exécution et envoie des alertes

## Bonnes pratiques

> **Ne passez que les outils dont vous avez besoin**
>
> La description de chaque outil est envoyée au modèle. Moins d'outils signifie moins de jetons et moins de mauvais choix d'outils. Pour un chat qui ne lit que des pages, `scrape` et `search` sont souvent suffisants.

> **Définissez une limite d'étapes**
>
> Définissez toujours `stopWhen` (par exemple `stepCountIs(5)`) pour que le modèle puisse enchaîner les appels d'outils mais ne puisse pas boucler indéfiniment.

> **Réduisez maxCharacters pour les longues pages**
>
> Le contenu des pages est la plus grande partie de la facture de jetons. Si vous crawlez ou traitez par lots de nombreuses pages, réduisez `maxCharacters` pour que tous les résultats tiennent dans la fenêtre de contexte du modèle.

> **Augmentez timeoutSeconds pour les grands crawls**
>
> Les outils de crawl et de lot attendent que le travail soit terminé. Si vous rencontrez des délais d'attente, augmentez `timeoutSeconds`, ou réduisez `maxPages`.

## Dépannage

> **Échec de l'authentification**
>
> **Erreur** : "Clé API invalide"
>
> **Solutions** :
>
> * Vérifiez votre clé API dans le [tableau de bord](https://www.olostep.com/dashboard)
> * Assurez-vous que `OLOSTEP_API_KEY` est défini là où votre code s'exécute (par exemple dans les variables d'environnement de votre projet Vercel)
> * Ou passez directement la clé avec `olostepTools({ apiKey })`

> **Le modèle n'appelle pas les outils**
>
> **Solutions** :
>
> * Définissez `stopWhen`, sinon la génération s'arrête après la première étape
> * Utilisez un modèle qui prend en charge l'appel d'outils
> * Mentionnez le web dans votre invite ou message système, par exemple "utilisez les outils web et citez vos sources"

> **Crawl ou lot expire**
>
> **Solutions** :
>
> * Augmentez `timeoutSeconds`
> * Réduisez `maxPages` ou passez moins d'URLs
> * Sur les fonctions sans serveur, assurez-vous que la limite de temps de la fonction elle-même est plus longue que `timeoutSeconds`

> **Longueur du contexte dépassée**
>
> **Solutions** :
>
> * Réduisez `maxCharacters`
> * Utilisez `map` avec `searchQuery` pour choisir moins de pages, mais plus pertinentes, avant de les lire

## Tarification

Olostep facture en fonction de l'utilisation de l'API, indépendamment de l'AI SDK :

* **Scrapes** : Payez par scrape
* **Recherches et Réponses** : Payez par requête
* **Lots** : Payez par URL dans le lot
* **Crawls** : Payez par page crawlée
* **Cartes** : Payez par opération de cartographie

Consultez la tarification actuelle sur [olostep.com/pricing](https://www.olostep.com/pricing).

## Support

> **[GitHub](https://github.com/olostep-api/olostep-ai-sdk)**
>
> Code source et problèmes

> **[Email de support](mailto:info@olostep.com)**
>
> Email : [info@olostep.com](mailto:info@olostep.com)

> **[Docs AI SDK](https://ai-sdk.dev/docs)**
>
> En savoir plus sur le Vercel AI SDK

> **[Documentation](https://docs.olostep.com)**
>
> Parcourir la documentation complète de l'API

## Ressources associées

> **[API Scrapes](https://docs.olostep.com/features/scrapes.md)**
>
> En savoir plus sur le point d'accès Scrapes

> **[API Crawls](https://docs.olostep.com/features/crawls.md)**
>
> En savoir plus sur le point d'accès Crawls

> **[Intégration Mastra](https://docs.olostep.com/integrations/mastra.md)**
>
> Construire des agents avec Mastra

> **[Intégration LangChain](https://docs.olostep.com/integrations/langchain.md)**
>
> Construire des agents IA avec LangChain


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