Saltar al contenido

CrawlForge TeamEquipo de Ingeniería

8 min de lecturaActualizado

Cómo usar CrawlForge con el Vercel AI SDK

El Vercel AI SDK te ofrece una interfaz unificada para llamar a LLMs desde cualquier framework: Next.js, SvelteKit, Nuxt o Node puro. CrawlForge le da a tu LLM acceso a datos web en vivo mediante 31 herramientas de scraping especializadas. Juntos, te permiten construir aplicaciones de IA que pueden buscar, obtener, extraer y analizar contenido web en tiempo real.

Este tutorial te muestra cómo registrar las herramientas de CrawlForge con la API tool() del Vercel AI SDK, para que tu IA pueda hacer scraping de la web con la misma naturalidad con la que genera texto.

Tabla de contenidos

Requisitos previos

Bash
npm install ai @ai-sdk/anthropic zod dotenv
Bash
# .env.local
ANTHROPIC_API_KEY=sk-ant-xxxxx
CRAWLFORGE_API_KEY=cf_live_xxxxx

Obtén tu API key de CrawlForge en crawlforge.dev/signup: 1.000 credits gratis incluidos.

Cómo funciona: herramientas en el Vercel AI SDK

El Vercel AI SDK te permite definir herramientas que el LLM puede invocar durante una conversación. Cada herramienta tiene un nombre, una descripción, un esquema de parámetros (usando Zod) y una función execute. El LLM lee las descripciones de las herramientas, decide cuándo llamarlas e incorpora los resultados en su respuesta.

La API REST de CrawlForge encaja perfectamente con este patrón: cada una de las 31 herramientas se convierte en una función invocable con parámetros tipados.

Paso 1: crear el wrapper de herramientas de CrawlForge

Primero, construye un helper reutilizable que llame a cualquier endpoint de CrawlForge:

Typescript
// lib/crawlforge.ts
const CRAWLFORGE_BASE = 'https://crawlforge.dev/api/v1/tools';

export async function callCrawlForge<T>(
  toolName: string,
  params: Record<string, unknown>
): Promise<T> {
  const response = await fetch(`${CRAWLFORGE_BASE}/${toolName}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CRAWLFORGE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(params),
  });

  if (!response.ok) {
    throw new Error(`CrawlForge ${toolName} failed: ${response.status}`);
  }

  return response.json() as Promise<T>;
}

Paso 2: registrar herramientas con generateText

Ahora registra las herramientas de CrawlForge usando la función tool() del Vercel AI SDK:

Typescript
// app/api/chat/route.ts
import { generateText, tool } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';
import { callCrawlForge } from '@/lib/crawlforge';

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    // Fetch and extract clean content from any URL (2 credits)
    extractContent: tool({
      description: 'Extract the main content from a web page as clean text. Use this when you need to read an article, documentation page, or any web content.',
      parameters: z.object({
        url: z.string().url().describe('The URL to extract content from'),
      }),
      execute: async ({ url }) => {
        return callCrawlForge('extract_content', { url });
      },
    }),

    // Search the web (5 credits)
    searchWeb: tool({
      description: 'Search the web using Google. Returns titles, URLs, and snippets for the top results.',
      parameters: z.object({
        query: z.string().describe('The search query'),
        limit: z.number().optional().default(5).describe('Number of results'),
      }),
      execute: async ({ query, limit }) => {
        return callCrawlForge('search_web', { query, limit });
      },
    }),

    // Extract structured data with CSS selectors (2 credits)
    scrapeStructured: tool({
      description: 'Extract specific data from a web page using CSS selectors. Use when you need structured data like prices, names, or lists.',
      parameters: z.object({
        url: z.string().url().describe('The URL to scrape'),
        selectors: z.record(z.string()).describe('CSS selectors mapping field names to selectors'),
      }),
      execute: async ({ url, selectors }) => {
        return callCrawlForge('scrape_structured', { url, selectors });
      },
    }),
  },
  prompt: 'Find the current pricing for Vercel Pro plan and compare it to Netlify Pro.',
});

console.log(result.text);

Cuando el LLM se encuentra con una pregunta que requiere datos web, invoca automáticamente la herramienta de CrawlForge adecuada, recibe los resultados y los integra en su respuesta. No se necesita orquestación manual.

Paso 3: construir un chat en streaming con acceso web

Para una experiencia de chat en tiempo real, usa streamText en lugar de generateText:

Typescript
// app/api/chat/route.ts
import { streamText, tool } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';
import { callCrawlForge } from '@/lib/crawlforge';

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

  const result = streamText({
    model: anthropic('claude-sonnet-4-20250514'),
    system: `You are a research assistant with access to live web data.
When users ask about current information, use your tools to fetch it.
Always cite the URLs you retrieved data from.`,
    messages,
    tools: {
      extractContent: tool({
        description: 'Extract main content from a URL as clean text',
        parameters: z.object({
          url: z.string().url(),
        }),
        execute: async ({ url }) =>
          callCrawlForge('extract_content', { url }),
      }),
      searchWeb: tool({
        description: 'Search the web and return top results',
        parameters: z.object({
          query: z.string(),
          limit: z.number().optional().default(5),
        }),
        execute: async ({ query, limit }) =>
          callCrawlForge('search_web', { query, limit }),
      }),
    },
    maxSteps: 5, // Allow up to 5 tool calls per response
  });

  return result.toDataStreamResponse();
}

El parámetro maxSteps: 5 permite que el LLM encadene varias llamadas a herramientas; por ejemplo, primero buscar en la web y luego extraer contenido del resultado principal.

Componente de frontend

Typescript
// app/page.tsx
'use client';
import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

  return (
    <div className="max-w-2xl mx-auto p-4">
      {messages.map((m) => (
        <div key={m.id} className="mb-4">
          <strong>{m.role === 'user' ? 'You' : 'AI'}:</strong>
          <p>{m.content}</p>
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask anything about the web..."
          className="w-full p-2 border rounded"
          disabled={isLoading}
        />
      </form>
    </div>
  );
}

Avanzado: agente de investigación con múltiples herramientas

Combina varias herramientas de CrawlForge para flujos de trabajo de investigación más profundos:

Typescript
import { generateText, tool } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';
import { callCrawlForge } from '@/lib/crawlforge';

const research = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    searchWeb: tool({
      description: 'Search Google for information',
      parameters: z.object({ query: z.string(), limit: z.number().default(5) }),
      execute: async ({ query, limit }) =>
        callCrawlForge('search_web', { query, limit }),
    }),
    extractContent: tool({
      description: 'Read the full content of a web page',
      parameters: z.object({ url: z.string().url() }),
      execute: async ({ url }) =>
        callCrawlForge('extract_content', { url }),
    }),
    analyzeContent: tool({
      description: 'Analyze text for topics, sentiment, and key entities',
      parameters: z.object({ text: z.string() }),
      execute: async ({ text }) =>
        callCrawlForge('analyze_content', { text }),
    }),
  },
  maxSteps: 10,
  prompt: `Research the current state of MCP server adoption in 2026.
    Search for recent articles, read the top 3, and analyze the key trends.
    Provide a summary with citations.`,
});

console.log(research.text);
// Returns a cited research summary using live web data

Este agente hará lo siguiente:

  1. Buscar en Google artículos relevantes (5 credits)
  2. Extraer contenido de los resultados principales (2 credits cada uno)
  3. Analizar el contenido en busca de temas (3 credits cada uno)

Costo total para una investigación de 3 fuentes: ~20 credits.

Desglose de costos en credits

HerramientaCreditsMejor para
fetch_url1Obtención de HTML en bruto
extract_text1Extracción de texto limpio
extract_links1Descubrimiento de enlaces
extract_metadata1Metadatos de página (título, etiquetas OG)
extract_content2Extracción de contenido legible
scrape_structured2Extracción de datos basada en selectores CSS
summarize_content2Resumen de texto
analyze_content3Análisis de temas y sentimiento
search_web5Resultados de búsqueda de Google
deep_research10Investigación de múltiples fuentes con citas

Consulta el desglose completo de precios para las 31 herramientas.

Mejores prácticas

Minimiza el uso de credits. Usa extract_content (2 credits) en lugar de deep_research (10 credits) cuando solo necesitas una página. Las descripciones de las herramientas guían al LLM hacia la opción más barata que satisface la consulta.

Configura maxSteps con cuidado. Un valor de maxSteps más alto permite más llamadas a herramientas por respuesta, pero consume más credits. Empieza con 3-5 y auméntalo solo si el LLM necesita más de forma constante.

Cachea las páginas a las que accedes con frecuencia. Si tu app obtiene repetidamente la misma URL, cachea la respuesta de CrawlForge en Redis o una base de datos en lugar de volver a obtenerla cada vez.

Usa descripciones de Zod. Las cadenas .describe() en tus parámetros de Zod ayudan al LLM a entender qué valores pasar. Sé específico: "La URL completa incluyendo https://" es mejor que "URL".

Próximos pasos

Ahora tienes una aplicación con el Vercel AI SDK con acceso web en vivo. Amplía desde aquí:


Construye apps de IA que ven la web. Empieza gratis con 1.000 credits, sin tarjeta de crédito.

Pruébalo tú mismo — sin necesidad de registrarte

Explora las 31 herramientas de scraping y extracción de CrawlForge en el playground y luego empieza gratis con 1,000 credits.

1,000 credits gratis • Por única vez • No se requiere tarjeta de crédito

Etiquetas

  • vercel-ai-sdk
  • nextjs
  • integration
  • web-scraping
  • ai-engineering
  • tutorial
  • typescript

Sobre el autor

CrawlForge Team

Equipo de Ingeniería

Construimos el MCP server de web scraping más completo. Creamos herramientas que ayudan a los desarrolladores a extraer, analizar y transformar datos web para aplicaciones de IA.

Newsletter

Mantente al día con los últimos artículos

Recibe tutoriales, novedades del producto y consejos de web scraping en tu bandeja de entrada.

Sin spam. Cancela tu suscripción cuando quieras.

FAQ

Preguntas frecuentes

01¿Cómo uso CrawlForge con el Vercel AI SDK?

Registra las 31 herramientas de scraping de CrawlForge con la API tool() del Vercel AI SDK para que cualquier LLM que llames mediante generateText o streamText pueda obtener, extraer e investigar la web cuando lo necesite. La configuración toma menos de 10 minutos y funciona con Next.js, SvelteKit, Nuxt o Node puro.

02¿Qué es una herramienta en el Vercel AI SDK?

El Vercel AI SDK te permite definir herramientas que el LLM puede invocar durante una conversación. Cada herramienta tiene un nombre, una descripción, un esquema de parámetros usando Zod y una función execute. El LLM lee las descripciones de las herramientas, decide cuándo llamarlas e incorpora los resultados en su respuesta.

03¿Cómo minimizo el uso de credits de CrawlForge en una app con el AI SDK?

Usa extract_content (2 credits) en lugar de deep_research (10 credits) cuando solo necesitas una página. Configura maxSteps con cuidado: empieza con 3-5 y auméntalo solo si es necesario. Cachea las páginas a las que accedes con frecuencia en Redis o una base de datos en lugar de volver a obtenerlas cada vez.

04¿Por qué importan las descripciones de los parámetros de Zod para las herramientas del AI SDK?

Las cadenas .describe() en tus parámetros de Zod ayudan al LLM a entender qué valores pasar. Sé específico: "La URL completa incluyendo https://" es mejor que "URL". Las descripciones claras guían al LLM hacia la herramienta más barata que satisface la consulta.

Sigue leyendo

Artículos relacionados

Tutoriales

8m

Cómo usar CrawlForge con agentes de LangGraph

Construye agentes de web scraping con estado usando LangGraph y CrawlForge. Guía en TypeScript que cubre nodos del grafo, gestión de estado y flujos de scraping condicionales.

Tutoriales

7m

Cómo usar CrawlForge con agentes de IA de Mastra

Crea agentes de IA con capacidades de web scraping usando Mastra y CrawlForge. Guía de configuración en TypeScript con integración de herramientas, workflows y ejemplos de agentes.