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

# Integración de Olostep + Vercel AI SDK

> Proporciona a los agentes del AI SDK búsqueda web en vivo, scraping, crawling y respuestas citadas con herramientas listas de Olostep

La integración del Olostep AI SDK proporciona a los agentes construidos con el [Vercel AI SDK](https://ai-sdk.dev) herramientas listas para datos web en vivo. Olostep es una API de búsqueda, scraping y crawling web: una API para buscar, extraer y estructurar datos web. Pasa las herramientas a `generateText` o `streamText` y el modelo decide cuándo buscar, hacer scraping o crawling.

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

## Características

El paquete proporciona 6 herramientas:

> **Scrape**
>
> Haz scraping de cualquier URL y devuelve markdown limpio, con renderizado de JavaScript

> **Search**
>
> Busca en la web en vivo y devuelve títulos, URLs y descripciones

> **Answer**
>
> Responde a una pregunta desde la web en vivo, con URLs de origen

> **Map**
>
> Lista las URLs en un sitio web, opcionalmente clasificadas por una consulta

> **Crawl**
>
> Haz crawling de un sitio desde una URL inicial y devuelve el markdown de cada página

> **Batch**
>
> Haz scraping de una lista de URLs en un solo lote y devuelve el markdown de cada una

## Instalación

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

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

## Configuración

Establece tu clave de API de Olostep como una variable de entorno:

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

O en tu archivo `.env`:

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

Obtén tu clave de API desde el [Dashboard de Olostep](https://www.olostep.com/dashboard).

## Inicio Rápido

Pasa todas las herramientas de Olostep al modelo 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: 'Lee las notas de lanzamiento de Next.js 15 y enumera los cambios importantes, con fuentes.',
});

console.log(text);
```

`stopWhen` permite que el modelo llame a herramientas en varios pasos, por ejemplo, buscar primero y luego hacer scraping del mejor resultado. La cadena del modelo utiliza el [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). También puedes pasar cualquier modelo de proveedor del AI SDK, como `openai('gpt-5-mini')` de `@ai-sdk/openai`.

### Seleccionar Herramientas Individuales

Solo proporciona al modelo las herramientas que necesita:

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

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

## Herramientas Disponibles

Los nombres de las herramientas a continuación son las claves utilizadas por `olostepTools()`.

### scrape

`olostepScrape()`. Haz scraping de una sola URL y devuelve su contenido como markdown.

**Entrada:**

**url** `string` *required*

La URL de la página para hacer scraping

**waitBeforeScraping** `number`

Milisegundos para esperar a que las páginas pesadas en JavaScript se rendericen (0 a 10000)

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

### search

`olostepSearch()`. Busca en la web en vivo.

**Entrada:**

**query** `string` *required*

La consulta de búsqueda

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

Número máximo de resultados (1 a 20)

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

### answer

`olostepAnswer()`. Busca y lee la web en vivo para responder una pregunta, con fuentes.

**Entrada:**

**task** `string` *required*

La pregunta o tarea de investigación

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

### map

`olostepMap()`. Descubre las URLs en un sitio web.

**Entrada:**

**url** `string` *required*

El sitio web a mapear

**searchQuery** `string`

Clasifica las URLs por relevancia a esta consulta

**topN** `number`

Número máximo de URLs a devolver (1 a 500)

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

### crawl

`olostepCrawl()`. Haz crawling de un sitio web desde una URL inicial y devuelve el markdown de cada página. La herramienta espera a que termine el crawling antes de devolver resultados.

**Entrada:**

**url** `string` *required*

La URL desde donde comenzar el crawling

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

Máximo de páginas para hacer crawling (1 a 25)

**includeUrls** `array`

Solo hacer crawling de URLs que coincidan con estos patrones glob, por ejemplo, `["/docs/**"]`

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

### batch

`olostepBatch()`. Haz scraping de una lista de URLs en un solo lote y devuelve el markdown de cada página. La herramienta espera a que termine el lote antes de devolver resultados.

**Entrada:**

**urls** `array` *required*

Las URLs para hacer scraping (1 a 20)

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

> [!NOTE]
>
> Las herramientas de crawling y batch están limitadas a 25 páginas y 20 URLs por llamada para mantener los resultados de las herramientas lo suficientemente pequeños para el modelo. Para trabajos más grandes, llama a las APIs de [Crawls](https://docs.olostep.com/features/crawls.md) y [Batches](https://docs.olostep.com/features/batches.md) directamente con el [Node.js SDK](https://docs.olostep.com/sdks/node-js.md).

## Opciones

Cada herramienta, y `olostepTools()`, acepta las mismas opciones:

```typescript theme={null}
olostepTools({
  apiKey: 'olostep_...',   // por defecto es process.env.OLOSTEP_API_KEY
  maxCharacters: 20_000,   // contenido máximo de página devuelto al modelo, por página
  timeoutSeconds: 300,     // cuánto tiempo esperan las herramientas de crawling y batch para que el trabajo termine
});
```

**apiKey** `string`

Clave de API de Olostep. Por defecto es la variable de entorno `OLOSTEP_API_KEY`.

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

Máximo de caracteres de contenido de página devuelto al modelo por página. Las páginas más largas se truncan.

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

Cuánto tiempo esperan las herramientas de crawling y batch para que el trabajo termine, en segundos.

## Ejemplo de Streaming

Usa las mismas herramientas con `streamText`, por ejemplo, en un manejador de rutas de 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: 'Eres un asistente de investigación. Usa las herramientas web y cita tus fuentes.',
    messages: await convertToModelMessages(messages),
    tools: olostepTools(),
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}
```

## Casos de Uso Populares

> **Asistente de Investigación**
>
> 1. El modelo usa `search` o `answer` para encontrar fuentes
> 2. Usa `scrape` para leer las páginas más relevantes
> 3. Devuelve un resumen con URLs de origen

> **Agente de Codificación Consciente de Documentos**
>
> 1. El modelo usa `map` con un `searchQuery` para encontrar las páginas de documentos correctas
> 2. Usa `batch` o `crawl` para leerlas
> 3. Escribe código contra la API actual en lugar de adivinar

> **Monitoreo de Competidores y Precios**
>
> 1. Un trabajo programado llama a `generateText` con `scrape` y `batch`
> 2. El modelo extrae precios o cambios de cada página
> 3. Tu código los compara con la última ejecución y envía alertas

## Mejores Prácticas

> **Solo Pasa las Herramientas que Necesitas**
>
> La descripción de cada herramienta se envía al modelo. Menos herramientas significa menos tokens y menos elecciones incorrectas de herramientas. Para un chat que solo lee páginas, `scrape` y `search` suelen ser suficientes.

> **Establece un Límite de Pasos**
>
> Siempre establece `stopWhen` (por ejemplo, `stepCountIs(5)`) para que el modelo pueda encadenar llamadas de herramientas pero no pueda buclear indefinidamente.

> **Reduce maxCharacters para Páginas Largas**
>
> El contenido de la página es la mayor parte de la factura de tokens. Si haces crawling o batch de muchas páginas, reduce `maxCharacters` para que todos los resultados quepan en la ventana de contexto del modelo.

> **Aumenta timeoutSeconds para Crawls Grandes**
>
> Las herramientas de crawling y batch esperan a que el trabajo termine. Si encuentras tiempos de espera, aumenta `timeoutSeconds`, o reduce `maxPages`.

## Solución de Problemas

> **Autenticación Fallida**
>
> **Error**: "Clave de API inválida"
>
> **Soluciones**:
>
> * Verifica tu clave de API en el [dashboard](https://www.olostep.com/dashboard)
> * Asegúrate de que `OLOSTEP_API_KEY` esté configurado donde se ejecuta tu código (por ejemplo, en las variables de entorno de tu proyecto de Vercel)
> * O pasa la clave directamente con `olostepTools({ apiKey })`

> **El Modelo No Llama a las Herramientas**
>
> **Soluciones**:
>
> * Establece `stopWhen`, de lo contrario la generación se detiene después del primer paso
> * Usa un modelo que soporte llamadas a herramientas
> * Menciona la web en tu prompt o mensaje del sistema, por ejemplo, "usa las herramientas web y cita tus fuentes"

> **Crawl o Batch Expira**
>
> **Soluciones**:
>
> * Aumenta `timeoutSeconds`
> * Reduce `maxPages` o pasa menos URLs
> * En funciones sin servidor, asegúrate de que el límite de tiempo de la función sea mayor que `timeoutSeconds`

> **Longitud del Contexto Excedida**
>
> **Soluciones**:
>
> * Reduce `maxCharacters`
> * Usa `map` con `searchQuery` para elegir menos páginas, más relevantes, antes de leerlas

## Precios

Olostep cobra en función del uso de la API, independiente del AI SDK:

* **Scrapes**: Pago por cada scraping
* **Búsquedas y Respuestas**: Pago por solicitud
* **Batches**: Pago por URL en el lote
* **Crawls**: Pago por página rastreada
* **Maps**: Pago por operación de mapeo

Consulta los precios actuales en [olostep.com/pricing](https://www.olostep.com/pricing).

## Soporte

> **[GitHub](https://github.com/olostep-api/olostep-ai-sdk)**
>
> Código fuente y problemas

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

> **[Documentación del AI SDK](https://ai-sdk.dev/docs)**
>
> Aprende sobre el Vercel AI SDK

> **[Documentación](https://docs.olostep.com)**
>
> Navega por la documentación completa de la API

## Recursos Relacionados

> **[API de Scrapes](https://docs.olostep.com/features/scrapes.md)**
>
> Aprende sobre el endpoint de Scrapes

> **[API de Crawls](https://docs.olostep.com/features/crawls.md)**
>
> Aprende sobre el endpoint de Crawls

> **[Integración con Mastra](https://docs.olostep.com/integrations/mastra.md)**
>
> Construye agentes con Mastra

> **[Integración con LangChain](https://docs.olostep.com/integrations/langchain.md)**
>
> Construye agentes de IA con LangChain


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