@parallel-web/ai-sdk-tools

AI SDK tools for Parallel Web, built for Vercel's AI SDK v6.

Installation

npm install ai @parallel-web/ai-sdk-tools
# or
pnpm add ai @parallel-web/ai-sdk-tools
# or
yarn add ai @parallel-web/ai-sdk-tools

Note: This package requires AI SDK v6. If you're still on AI SDK v5, install the last v5-compatible release instead: npm install @parallel-web/[email protected].

Usage

Add PARALLEL_API_KEY obtained from Parallel Platform to your environment variables.

Search Tool

searchTool uses Parallel's v1 Search API to perform web searches and return LLM-optimized results.

Input schema:

• search_queries (required): List of concise keyword search queries (3-6 words each, at least one, max 5). Provide 2-3 for best results.
• objective (optional): Natural-language description of the underlying question or goal driving the search. Recommended alongside search_queries for best results.
• mode (optional): 'advanced' (default) for higher quality with advanced retrieval and compression, or 'basic' for the lowest latency

Extract Tool

extractTool uses Parallel's v1 Extract API to fetch and extract relevant content from specific URLs.

Input schema:

• urls (required): List of URLs to extract content from (max 20)
• objective (optional): Natural-language description of what information you're looking for

Basic Example

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { searchTool, extractTool } from '@parallel-web/ai-sdk-tools';

const result = streamText({
  model: openai('gpt-4o'),
  messages: [
    { role: 'user', content: 'What are the latest developments in AI?' },
  ],
  tools: {
    'web-search': searchTool,
    'web-extract': extractTool,
  },
  toolChoice: 'auto',
});

// Stream the response
return result.toUIMessageStreamResponse();

Factory Functions

For more control over the tool configuration, use the factory functions to create tools with custom defaults.

Note: Both factory functions accept an optional apiKey parameter. If not provided, they fall back to the PARALLEL_API_KEY environment variable.

createSearchTool

Create a search tool with custom defaults for mode, max_chars_total, client_model, and advanced settings (max_results, excerpts, location, source_policy, fetch_policy). Advanced settings are nested under advanced_settings in the v1 API; pass them as flat options here and they're assembled for you.

Best practice: Use advanced settings only when strictly required — restrictive parameters such as source_policy, location, and max_results can unnecessarily limit results and reduce quality.

import { createSearchTool } from '@parallel-web/ai-sdk-tools';

const myCustomSearchTool = createSearchTool({
  mode: 'basic',               // 'basic' offers the lowest latency; 'advanced' (default) is higher quality
  max_results: 5,              // Limit to 5 results (nested under advanced_settings)
  client_model: 'gpt-4o',      // Optional: tailor result formatting to the consuming model
  apiKey: 'your-api-key',      // Optional: pass an API key, falls back to PARALLEL_API_KEY env variable
});

createExtractTool

Create an extract tool with custom defaults for excerpts, full_content, fetch_policy, max_chars_total, and client_model. In the v1 API excerpts are always returned; their size is controlled via excerpts.

import { createExtractTool } from '@parallel-web/ai-sdk-tools';

const myExtractTool = createExtractTool({
  full_content: true,          // Include full page content (nested under advanced_settings)
  excerpts: {
    max_chars_per_result: 10000,
  },
  apiKey: 'your-api-key',      // Optional: pass an API key, falls back to PARALLEL_API_KEY env variable
});

Direct API Usage

You can also use the parallel-web SDK directly for maximum flexibility:

import { tool } from 'ai';
import { z } from 'zod';
import { Parallel } from 'parallel-web';

const parallel = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY,
});

const webSearch = tool({
  description: 'Search the web for information.',
  inputSchema: z.object({
    search_queries: z.array(z.string()).min(1).describe('Keyword search queries'),
    objective: z.string().nullable().optional().describe("The user's question"),
  }),
  execute: async ({ search_queries, objective }) => {
    const result = await parallel.search({
      search_queries,
      objective,
      mode: 'advanced',
      advanced_settings: { max_results: 5 },
    });
    return result;
  },
});

API Reference

• Search API Reference
• Extract API Reference
• Search API Best Practices
• Extract API Best Practices

Response Format

Both tools return the raw API response from Parallel:

Search Response

{
  search_id: string;
  session_id: string;
  results: Array<{
    url: string;
    title?: string;
    publish_date?: string;
    excerpts: string[];
  }>;
  usage?: Array<{ name: string; count: number }>;
  warnings?: Array<{ code: string; message: string }>;
}

Extract Response

{
  extract_id: string;
  session_id: string;
  results: Array<{
    url: string;
    title?: string;
    excerpts: string[];
    full_content?: string;
    publish_date?: string;
  }>;
  errors: Array<{
    url: string;
    error_type: string;
    http_status_code?: number;
    content?: string;
  }>;
  usage?: Array<{ name: string; count: number }>;
  warnings?: Array<{ code: string; message: string }>;
}

Migration to v1.0.0 (AI SDK v6 + v1 Search/Extract API)

Version 1.0.0 targets AI SDK v6 and Parallel's v1 Search and Extract APIs (parallel-web@^0.5.0). If you need AI SDK v5, install @parallel-web/[email protected].

searchTool changes

• search_queries is now required (at least one query); objective is optional but recommended alongside it.
• mode values changed from 'agentic'/'one-shot' to 'basic'/'advanced', defaulting to 'advanced'. Map 'agentic'/'one-shot' → 'basic'.
• createSearchTool advanced options (max_results, excerpts, source_policy, fetch_policy, plus the new location) are now sent under advanced_settings; new top-level options max_chars_total and client_model are also available. You still pass them as flat options.

extractTool changes

• Up to 20 URLs per request (was 10).
• Excerpts are always returned; the excerpts option no longer accepts a boolean — pass excerpt settings (e.g. { max_chars_per_result }) to control size.
• createExtractTool options full_content and fetch_policy are now sent under advanced_settings; new top-level options max_chars_total and client_model are also available.

Migration from v0.1.x

Version 0.2.0 introduces an updated API that conforms with Parallel's Search and Extract MCP tools:

searchTool changes

• Input schema changed: Removed search_type and include_domains. Added mode parameter.
• Return value changed: Now returns raw API response ({ search_id, results, ... }) instead of { searchParams, answer }.

Before (v0.1.x):

const result = await searchTool.execute({
  objective: 'Find TypeScript info',
  search_type: 'list',
  search_queries: ['TypeScript'],
  include_domains: ['typescriptlang.org'],
});
console.log(result.answer.results);

After (v0.2.0):

const result = await searchTool.execute({
  objective: 'Find TypeScript info',
  search_queries: ['TypeScript'],
  mode: 'agentic', // optional, defaults to 'agentic'
});
console.log(result.results);

extractTool changes

• Input schema changed: urls is now first, objective is optional.
• Return value changed: Now returns raw API response ({ extract_id, results, errors, ... }) instead of { searchParams, answer }.

Before (v0.1.x):

const result = await extractTool.execute({
  objective: 'Extract content',
  urls: ['https://example.com'],
  search_queries: ['keyword'],
});
console.log(result.answer.results);

After (v0.2.0):

const result = await extractTool.execute({
  urls: ['https://example.com'],
  objective: 'Extract content', // optional
});
console.log(result.results);