Skip to main content

Parallel

The @mastra/parallel package exposes Parallel Search and Extract as Mastra-compatible tools. Each factory returns a tool created with createTool() and a typed Zod input and output schema.

Installation
Direct link to Installation

npm install @mastra/parallel parallel-web zod

Set PARALLEL_API_KEY in your environment. You can also pass an API key directly to any factory.

Quick start
Direct link to Quick start

Use createParallelTools() to create both tools with shared client configuration:

src/mastra/tools/index.ts
import { createParallelTools } from '@mastra/parallel'

export const parallelTools = createParallelTools()
// Or pass an explicit API key:
// export const parallelTools = createParallelTools({ apiKey: 'parallel-api-key' })

The returned object contains parallelSearch and parallelExtract.

Create either tool separately when an agent doesn't need both:

src/mastra/tools/index.ts
import { createParallelExtractTool, createParallelSearchTool } from '@mastra/parallel'

export const searchTool = createParallelSearchTool()
export const extractTool = createParallelExtractTool({ apiKey: 'parallel-api-key' })

The client isn't initialized until the tool executes. A missing API key therefore fails at execution time with a configuration error.

Configuration
Direct link to Configuration

All factories accept ParallelClientOptions, an alias of ClientOptions from the official parallel-web client:

apiKey?:

string
Parallel API key. Falls back to the PARALLEL_API_KEY environment variable.

baseURL?:

string
Override the Parallel API base URL. The client also reads PARALLEL_BASE_URL.

timeout?:

number
Timeout in milliseconds for one request attempt.

fetch?:

Fetch
Custom fetch implementation.

fetchOptions?:

RequestInit
Additional options passed to each fetch call.

maxRetries?:

number
= 2
Maximum retries for temporary failures.

defaultHeaders?:

HeadersLike
Headers included with every request.

defaultQuery?:

Record<string, string | undefined>
Query parameters included with every request.

logLevel?:

LogLevel
Client log level. Falls back to PARALLEL_LOG, then warn.

logger?:

Logger
Client logger implementation.

The package also exports getParallelClient() for applications that need the configured official client directly.

createParallelSearchTool()
Direct link to createparallelsearchtool

Creates the parallel-search tool. Search returns ranked URLs and excerpts focused on the supplied queries and objective.

import { createParallelSearchTool } from '@mastra/parallel'

const searchTool = createParallelSearchTool()

Search input
Direct link to Search input

searchQueries:

string[]
One or more concise keyword queries. Parallel recommends 2-3 queries of 3-6 words each.

objective?:

string
Self-contained description of the goal driving the search.

mode?:

'turbo' | 'fast' | 'basic' | 'advanced'
= 'advanced'
Search mode.

clientModel?:

string
Model that will consume the results. Parallel uses it to tailor response defaults.

maxResults?:

number
Maximum number of results to return.

excerptMaxCharsPerResult?:

number
Maximum excerpt characters for each result.

maxCharsTotal?:

number
Maximum excerpt characters across all results.

location?:

string
ISO 3166-1 alpha-2 country code for geo-targeted results.

includeDomains?:

string[]
Only return results from these domains. Include and exclude lists can contain at most 200 domains combined.

excludeDomains?:

string[]
Exclude results from these domains. Include and exclude lists can contain at most 200 domains combined.

afterDate?:

string
Only return content published on or after this YYYY-MM-DD date.

fetchPolicy?:

FetchPolicy
Controls live fetching and cached-content fallback.
FetchPolicy

maxAgeSeconds?:

number
Maximum cached-content age before a live fetch. The minimum is 600 seconds.

timeoutSeconds?:

number
Timeout for a live fetch.

disableCacheFallback?:

boolean
Return an error instead of older cached content when a live fetch fails.

sessionId?:

string
Session identifier shared across related Search and Extract calls.

Search output
Direct link to Search output

Search returns searchId, sessionId, and results. Optional usage and warnings arrays preserve metadata from Parallel.

searchId:

string
Parallel Search request ID.

sessionId:

string
Session ID returned by Parallel.

results:

SearchResult[]
Results ordered by decreasing relevance.
SearchResult

url:

string
Result URL.

title?:

string
Page title.

publishDate?:

string
Page publication date.

excerpts:

string[]
Relevant Markdown excerpts.

usage?:

UsageItem[]
SKU names and counts for the request.

warnings?:

Warning[]
Validation or request warnings from Parallel.

createParallelExtractTool()
Direct link to createparallelextracttool

Creates the parallel-extract tool. Extract returns relevant excerpts or full content for up to 20 public URLs and reports per-URL failures separately.

import { createParallelExtractTool } from '@mastra/parallel'

const extractTool = createParallelExtractTool()

Extract input
Direct link to Extract input

urls:

string[]
One to 20 URLs to extract.

objective?:

string
Information to focus on while extracting.

searchQueries?:

string[]
Keyword queries used with the objective to focus excerpts.

clientModel?:

string
Model that will consume the results. Parallel uses it to tailor response defaults.

excerptMaxCharsPerResult?:

number
Maximum excerpt characters for each URL.

fullContent?:

boolean | number
Return full page content. Pass a number to cap characters for each URL.

maxCharsTotal?:

number
Maximum excerpt characters across all results.

fetchPolicy?:

FetchPolicy
Controls live fetching and cached-content fallback.
FetchPolicy

maxAgeSeconds?:

number
Maximum cached-content age before a live fetch. The minimum is 600 seconds.

timeoutSeconds?:

number
Timeout for a live fetch.

disableCacheFallback?:

boolean
Return an error instead of older cached content when a live fetch fails.

sessionId?:

string
Session identifier shared across related Search and Extract calls.

Extract output
Direct link to Extract output

extractId:

string
Parallel Extract request ID.

sessionId:

string
Session ID returned by Parallel.

results:

ExtractResult[]
Successful URL results.
ExtractResult

url:

string
Extracted URL.

title?:

string
Page title.

publishDate?:

string
Page publication date.

excerpts:

string[]
Relevant Markdown excerpts.

fullContent?:

string
Full Markdown content when requested.

errors:

ExtractError[]
Requested URLs that weren't returned as results.
ExtractError

url:

string
URL that failed.

errorType:

string
Parallel error type.

httpStatusCode?:

number
HTTP status code when available.

content?:

string
Response content when available.

usage?:

UsageItem[]
SKU names and counts for the request.

warnings?:

Warning[]
Validation or request warnings from Parallel.

Use the tools with an agent
Direct link to Use the tools with an agent

src/mastra/agents/research-agent.ts
import { Agent } from '@mastra/core/agent'
import { createParallelTools } from '@mastra/parallel'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'Search the web for current sources, then extract relevant content from the best pages.',
  tools: createParallelTools(),
})
On this page