feat(ai-parallel): add Parallel Search integration

.changeset/parallel-search.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-parallel': minor
+---
+
+Add a first-class Parallel Search client and server tool for source-grounded TanStack AI agents.

docs/adapters/parallel.md

@@ -0,0 +1,99 @@
+---
+title: Parallel Search
+id: parallel-adapter
+order: 11
+description: "Add live web sources and citations to TanStack AI agents with Parallel Search."
+keywords:
+  - tanstack ai
+  - parallel
+  - parallel search
+  - web search
+  - citations
+---
+
+An AI agent needs current web sources to answer questions beyond its training data. Parallel Search gives any function-calling TanStack AI model ranked sources and relevant excerpts.
+
+## Set up the workspace
+
+`@tanstack/ai-parallel` is available from the TanStack AI workspace.
+
+1. Install dependencies from the repository root:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Set your Parallel API key:
+
+   ```bash
+   export PARALLEL_API_KEY=your-api-key
+   ```
+
+## Add web search to an agent
+
+Add `parallelSearchTool()` to the `tools` array for a function-calling adapter:
+
+```ts
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { parallelSearchTool } from '@tanstack/ai-parallel'
+
+const stream = chat({
+  adapter: openaiText('gpt-5.6'),
+  tools: [
+    parallelSearchTool({
+      mode: 'fast',
+      defaultMaxResults: 5,
+    }),
+  ],
+  messages: [
+    {
+      role: 'user',
+      content: 'Find recent research on reliable AI agents and cite your sources.',
+    },
+  ],
+})
+```
+
+The tool runs on the server and returns each source URL, relevant excerpts, title, and publication date. Set `sessionId` explicitly when searches should share a Parallel session.
+
+## Control search behavior
+
+Configure source restrictions when you create the tool:
+
+```ts
+import { parallelSearchTool } from '@tanstack/ai-parallel'
+
+const search = parallelSearchTool({
+  mode: 'basic',
+  defaultMaxResults: 3,
+  sourcePolicy: {
+    include_domains: ['arxiv.org'],
+    after_date: '2026-08-01',
+  },
+})
+```
+
+The model can provide a query, an optional search objective, and an optional result limit. Application-owned source rules apply to every request.
+
+## Use the search client directly
+
+Call Parallel Search outside an agent loop with `ParallelSearchClient`:
+
+```ts
+import { ParallelSearchClient } from '@tanstack/ai-parallel'
+
+const client = new ParallelSearchClient()
+const response = await client.search({
+  search_queries: ['reliable AI agent research'],
+  objective: 'Find recent peer-reviewed research.',
+  mode: 'basic',
+  advanced_settings: { max_results: 3 },
+})
+
+for (const result of response.results) {
+  console.log(result.url, result.excerpts)
+}
+```
+
+The client calls `POST https://api.parallel.ai/v1/search` with your `PARALLEL_API_KEY`. See the [Parallel Search API reference](https://docs.parallel.ai/api-reference/search/search) for request details.

docs/config.json

@@ -977,6 +977,11 @@
           "to": "adapters/perplexity",
           "addedAt": "2026-08-13"
         },
+        {
+          "label": "Parallel Search",
+          "to": "adapters/parallel",
+          "addedAt": "2026-08-23"
+        },
         {
           "label": "Vercel AI Gateway",
           "to": "adapters/vercel-gateway",

packages/ai-parallel/README.md

@@ -0,0 +1,76 @@
+# @tanstack/ai-parallel
+
+Give a TanStack AI agent current web sources and relevant excerpts through the [Parallel Search API](https://docs.parallel.ai/api-reference/search/search).
+
+This package is available from the TanStack AI workspace.
+
+## Set up
+
+1. Install dependencies from the repository root:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Set your Parallel API key:
+
+   ```bash
+   export PARALLEL_API_KEY=your-api-key
+   ```
+
+3. Add the search tool to a function-calling model:
+
+   ```ts
+   import { chat } from '@tanstack/ai'
+   import { openaiText } from '@tanstack/ai-openai'
+   import { parallelSearchTool } from '@tanstack/ai-parallel'
+
+   const stream = chat({
+     adapter: openaiText('gpt-5.6'),
+     tools: [
+       parallelSearchTool({
+         mode: 'fast',
+         defaultMaxResults: 5,
+       }),
+     ],
+     messages: [
+       {
+         role: 'user',
+         content:
+           'Find recent research on reliable AI agents and cite your sources.',
+       },
+     ],
+   })
+   ```
+
+The tool returns source URLs, relevant excerpts, titles, and publication dates. Set `sessionId` explicitly when searches should share a Parallel session.
+
+## Restrict sources
+
+Set application-owned source rules when you create the tool:
+
+```ts
+const search = parallelSearchTool({
+  mode: 'basic',
+  sourcePolicy: {
+    include_domains: ['arxiv.org'],
+    after_date: '2026-08-01',
+  },
+})
+```
+
+## Call the Search API directly
+
+```ts
+import { ParallelSearchClient } from '@tanstack/ai-parallel'
+
+const client = new ParallelSearchClient()
+const { results } = await client.search({
+  search_queries: ['reliable AI agent research'],
+  objective: 'Find recent peer-reviewed research.',
+  mode: 'basic',
+  advanced_settings: { max_results: 3 },
+})
+```
+
+The client sends requests to `POST https://api.parallel.ai/v1/search`. Pass `apiKey`, `baseURL`, or `fetch` to configure the client.

packages/ai-parallel/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tanstack/ai-parallel",
+  "version": "0.1.0",
+  "description": "Parallel Search API client and server tool for TanStack AI",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-parallel"
+  },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "parallel",
+    "search",
+    "web-search"
+  ],
+  "dependencies": {
+    "parallel-web": "^1.3.0"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "vite": "^8.2.1",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "zod": "^4.0.0"
+  }
+}