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

# Olostep + Vercel AI SDK Integration

> Gib AI SDK-Agenten Live-Websuche, Scraping, Crawling und zitierte Antworten mit fertigen Olostep-Tools

Die Olostep AI SDK-Integration bietet Agenten, die mit dem [Vercel AI SDK](https://ai-sdk.dev) erstellt wurden, fertige Tools für Live-Webdaten. Olostep ist eine Websuche-, Scraping- und Crawling-API: eine API, um Webdaten zu suchen, zu extrahieren und zu strukturieren. Übergebe die Tools an `generateText` oder `streamText` und das Modell entscheidet, wann gesucht, gescrapt oder gecrawlt wird.

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

## Funktionen

Das Paket bietet 6 Tools:

> **Scrape**
>
> Scrape jede URL und gib sauberes Markdown zurück, mit JavaScript-Rendering

> **Search**
>
> Durchsuche das Live-Web und gib Titel, URLs und Beschreibungen zurück

> **Answer**
>
> Beantworte eine Frage aus dem Live-Web, mit Quell-URLs

> **Map**
>
> Liste die URLs auf einer Website auf, optional nach einer Abfrage sortiert

> **Crawl**
>
> Crawle eine Seite von einer Start-URL und gib das Markdown jeder Seite zurück

> **Batch**
>
> Scrape eine Liste von URLs in einem Batch und gib das Markdown jeder Seite zurück

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

Funktioniert mit AI SDK 5, 6 und 7, Zod 3.25+ oder 4 und Node.js 18+.

## Einrichtung

Setze deinen Olostep API-Schlüssel als Umgebungsvariable:

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

Oder in deiner `.env` Datei:

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

Hole dir deinen API-Schlüssel vom [Olostep Dashboard](https://www.olostep.com/dashboard).

## Schnellstart

Übergebe alle Olostep-Tools an das Modell mit `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: 'Lies die Next.js 15 Release Notes und liste die Breaking Changes mit Quellen auf.',
});

console.log(text);
```

`stopWhen` ermöglicht es dem Modell, Tools über mehrere Schritte aufzurufen, z.B. zuerst zu suchen und dann das beste Ergebnis zu scrapen. Der Modellstring verwendet das [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). Du kannst auch jedes AI SDK-Anbietermodell übergeben, wie z.B. `openai('gpt-5-mini')` von `@ai-sdk/openai`.

### Einzelne Tools auswählen

Gib dem Modell nur die Tools, die es benötigt:

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

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

## Verfügbare Tools

Die unten aufgeführten Toolnamen sind die Schlüssel, die von `olostepTools()` verwendet werden.

### scrape

`olostepScrape()`. Scrape eine einzelne URL und gib deren Inhalt als Markdown zurück.

**Eingabe:**

**url** `string` *required*

Die URL der Seite, die gescrapt werden soll

**waitBeforeScraping** `number`

Millisekunden, die gewartet werden sollen, bis JavaScript-lastige Seiten gerendert sind (0 bis 10000)

**Rückgabe:** `{ url, markdown }`

### search

`olostepSearch()`. Durchsuche das Live-Web.

**Eingabe:**

**query** `string` *required*

Die Suchanfrage

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

Maximale Anzahl der Ergebnisse (1 bis 20)

**Rückgabe:** `{ query, results: [{ title, url, description }] }`

### answer

`olostepAnswer()`. Suche und lese das Live-Web, um eine Frage zu beantworten, mit Quellen.

**Eingabe:**

**task** `string` *required*

Die Frage oder Rechercheaufgabe

**Rückgabe:** `{ answer, sources }`

### map

`olostepMap()`. Entdecke die URLs auf einer Website.

**Eingabe:**

**url** `string` *required*

Die Website, die abgebildet werden soll

**searchQuery** `string`

Sortiere URLs nach Relevanz zu dieser Abfrage

**topN** `number`

Maximale Anzahl der zurückzugebenden URLs (1 bis 500)

**Rückgabe:** `{ url, urls }`

### crawl

`olostepCrawl()`. Crawle eine Website von einer Start-URL und gib das Markdown jeder Seite zurück. Das Tool wartet, bis der Crawl abgeschlossen ist, bevor es zurückgibt.

**Eingabe:**

**url** `string` *required*

Die URL, von der aus gecrawlt werden soll

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

Maximale Anzahl der zu crawlenden Seiten (1 bis 25)

**includeUrls** `array`

Crawle nur URLs, die diesen Glob-Mustern entsprechen, z.B. `["/docs/**"]`

**Rückgabe:** `{ url, pages: [{ url, markdown }] }`

### batch

`olostepBatch()`. Scrape eine Liste von URLs in einem Batch und gib das Markdown jeder Seite zurück. Das Tool wartet, bis der Batch abgeschlossen ist, bevor es zurückgibt.

**Eingabe:**

**urls** `array` *required*

Die zu scrapenden URLs (1 bis 20)

**Rückgabe:** `{ pages: [{ url, markdown }] }`

> [!NOTE]
>
> Die Crawl- und Batch-Tools sind auf 25 Seiten und 20 URLs pro Aufruf begrenzt, um die Tool-Ergebnisse klein genug für das Modell zu halten. Für größere Aufgaben rufe die [Crawls](https://docs.olostep.com/features/crawls.md) und [Batches](https://docs.olostep.com/features/batches.md) APIs direkt mit dem [Node.js SDK](https://docs.olostep.com/sdks/node-js.md) auf.

## Optionen

Jedes Tool und `olostepTools()` akzeptiert die gleichen Optionen:

```typescript theme={null}
olostepTools({
  apiKey: 'olostep_...',   // Standardmäßig process.env.OLOSTEP_API_KEY
  maxCharacters: 20_000,   // Maximale Seiteninhalte, die pro Seite an das Modell zurückgegeben werden
  timeoutSeconds: 300,     // Wie lange die Crawl- und Batch-Tools auf den Abschluss des Jobs warten
});
```

**apiKey** `string`

Olostep API-Schlüssel. Standardmäßig die `OLOSTEP_API_KEY` Umgebungsvariable.

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

Maximale Anzahl von Zeichen des Seiteninhalts, die pro Seite an das Modell zurückgegeben werden. Längere Seiten werden abgeschnitten.

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

Wie lange die Crawl- und Batch-Tools auf den Abschluss des Jobs warten, in Sekunden.

## Streaming-Beispiel

Verwende die gleichen Tools mit `streamText`, zum Beispiel in einem Next.js-Routenhandler:

```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: 'Du bist ein Forschungsassistent. Verwende die Webtools und zitiere deine Quellen.',
    messages: await convertToModelMessages(messages),
    tools: olostepTools(),
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}
```

## Beliebte Anwendungsfälle

> **Forschungsassistent**
>
> 1. Das Modell verwendet `search` oder `answer`, um Quellen zu finden
> 2. Es verwendet `scrape`, um die relevantesten Seiten zu lesen
> 3. Es gibt eine Zusammenfassung mit Quell-URLs zurück

> **Dokumentenbewusster Coding-Agent**
>
> 1. Das Modell verwendet `map` mit einer `searchQuery`, um die richtigen Dokumentationsseiten zu finden
> 2. Es verwendet `batch` oder `crawl`, um sie zu lesen
> 3. Es schreibt Code gegen die aktuelle API anstatt zu raten

> **Wettbewerbs- und Preisüberwachung**
>
> 1. Ein geplanter Job ruft `generateText` mit `scrape` und `batch` auf
> 2. Das Modell extrahiert Preise oder Änderungen von jeder Seite
> 3. Dein Code vergleicht sie mit dem letzten Lauf und sendet Benachrichtigungen

## Beste Praktiken

> **Nur die benötigten Tools übergeben**
>
> Die Beschreibung jedes Tools wird an das Modell gesendet. Weniger Tools bedeuten weniger Tokens und weniger falsche Toolauswahlen. Für einen Chat, der nur Seiten liest, sind `scrape` und `search` oft ausreichend.

> **Setze ein Schrittlimit**
>
> Setze immer `stopWhen` (zum Beispiel `stepCountIs(5)`), damit das Modell Toolaufrufe verketten kann, aber nicht endlos in einer Schleife läuft.

> **Reduziere maxCharacters für lange Seiten**
>
> Seiteninhalt ist der größte Teil der Tokenrechnung. Wenn du viele Seiten crawlst oder batchst, reduziere `maxCharacters`, damit alle Ergebnisse in das Kontextfenster des Modells passen.

> **Erhöhe timeoutSeconds für große Crawls**
>
> Crawl- und Batch-Tools warten auf den Abschluss des Jobs. Wenn du Zeitüberschreitungen hast, erhöhe `timeoutSeconds` oder reduziere `maxPages`.

## Fehlerbehebung

> **Authentifizierung fehlgeschlagen**
>
> **Fehler**: "Ungültiger API-Schlüssel"
>
> **Lösungen**:
>
> * Überprüfe deinen API-Schlüssel im [Dashboard](https://www.olostep.com/dashboard)
> * Stelle sicher, dass `OLOSTEP_API_KEY` dort gesetzt ist, wo dein Code läuft (zum Beispiel in den Umgebungsvariablen deines Vercel-Projekts)
> * Oder übergebe den Schlüssel direkt mit `olostepTools({ apiKey })`

> **Das Modell ruft die Tools nicht auf**
>
> **Lösungen**:
>
> * Setze `stopWhen`, andernfalls stoppt die Generierung nach dem ersten Schritt
> * Verwende ein Modell, das Toolaufrufe unterstützt
> * Erwähne das Web in deinem Prompt oder Systemnachricht, zum Beispiel "verwende die Webtools und zitiere deine Quellen"

> **Crawl oder Batch läuft ab**
>
> **Lösungen**:
>
> * Erhöhe `timeoutSeconds`
> * Reduziere `maxPages` oder übergebe weniger URLs
> * Stelle bei serverlosen Funktionen sicher, dass das Zeitlimit der Funktion länger ist als `timeoutSeconds`

> **Kontextlänge überschritten**
>
> **Lösungen**:
>
> * Reduziere `maxCharacters`
> * Verwende `map` mit `searchQuery`, um weniger, relevantere Seiten auszuwählen, bevor du sie liest

## Preisgestaltung

Olostep berechnet basierend auf der API-Nutzung, unabhängig vom AI SDK:

* **Scrapes**: Bezahlung pro Scrape
* **Suchen und Antworten**: Bezahlung pro Anfrage
* **Batches**: Bezahlung pro URL im Batch
* **Crawls**: Bezahlung pro gecrawlte Seite
* **Maps**: Bezahlung pro Mapping-Operation

Überprüfe die aktuellen Preise auf [olostep.com/pricing](https://www.olostep.com/pricing).

## Support

> **[GitHub](https://github.com/olostep-api/olostep-ai-sdk)**
>
> Quellcode und Probleme

> **[Support E-Mail](mailto:info@olostep.com)**
>
> E-Mail: [info@olostep.com](mailto:info@olostep.com)

> **[AI SDK-Dokumentation](https://ai-sdk.dev/docs)**
>
> Erfahre mehr über das Vercel AI SDK

> **[Dokumentation](https://docs.olostep.com)**
>
> Durchsuche die vollständige API-Dokumentation

## Verwandte Ressourcen

> **[Scrapes API](https://docs.olostep.com/features/scrapes.md)**
>
> Erfahre mehr über den Scrapes-Endpunkt

> **[Crawls API](https://docs.olostep.com/features/crawls.md)**
>
> Erfahre mehr über den Crawls-Endpunkt

> **[Mastra-Integration](https://docs.olostep.com/integrations/mastra.md)**
>
> Baue Agenten mit Mastra

> **[LangChain-Integration](https://docs.olostep.com/integrations/langchain.md)**
>
> Baue AI-Agenten mit LangChain


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