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

npm

npm install @mastra/parallel parallel-web zod

pnpm

pnpm add @mastra/parallel parallel-web zod

Yarn

yarn add @mastra/parallel parallel-web zod

Bun

bun add @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

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

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()

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

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

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()

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

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

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

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(),
})

Related

• Parallel Search documentation
• Parallel Extract documentation
• createTool() reference