@ai-sdk/gateway 3.0.136 → 3.0.138

package/docs/00-ai-gateway.mdx

@@ -566,6 +566,93 @@ for await (const part of result.fullStream) {
 }
 ```
 
+#### Exa Search
+
+The Exa Search tool enables models to search the web using [Exa's Search API](https://exa.ai/docs/reference/search-api-guide-for-coding-agents). This tool is executed by the AI Gateway and returns token-efficient web excerpts for agent workflows.
+
+```ts
+import { gateway, generateText } from 'ai';
+
+const result = await generateText({
+  model: 'openai/gpt-5.4-nano',
+  prompt:
+    'Find the latest AI regulation updates and summarize the key changes.',
+  tools: {
+    exa_search: gateway.tools.exaSearch(),
+  },
+});
+
+console.log(result.text);
+console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
+console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));
+```
+
+You can also configure the search with optional parameters:
+
+```ts
+import { gateway, generateText } from 'ai';
+
+const result = await generateText({
+  model: 'openai/gpt-5.4-nano',
+  prompt: 'Find recent AI regulation news from trusted sources.',
+  tools: {
+    exa_search: gateway.tools.exaSearch({
+      type: 'fast',
+      numResults: 5,
+      category: 'news',
+      includeDomains: ['reuters.com', 'bbc.com', 'nytimes.com'],
+      contents: {
+        highlights: true,
+        maxAgeHours: 24,
+      },
+    }),
+  },
+});
+
+console.log(result.text);
+console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
+console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));
+```
+
+The Exa Search tool supports the following optional configuration options:
+
+- **type** _'auto' | 'fast' | 'instant'_
+
+  Search mode. `'auto'` is the default balance of speed and quality.
+
+- **numResults** _number_
+
+  Maximum number of results to return (1-100, default: 10).
+
+- **category** _'company' | 'people' | 'research paper' | 'news' | 'personal site' | 'financial report'_
+
+  Focus results on a specific content type.
+
+- **includeDomains** / **excludeDomains** _string[]_
+
+  Restrict or exclude search results by domain.
+
+- **startPublishedDate** / **endPublishedDate** _string_
+
+  Filter results by ISO 8601 publication date.
+
+- **contents** _object_
+
+  Control result extraction and freshness:
+  - `text` - Return full page text, optionally capped with `maxCharacters`
+  - `highlights` - Return token-efficient excerpts
+  - `maxAgeHours` - Control cached content freshness
+  - `livecrawlTimeout` - Livecrawl timeout in milliseconds
+  - `subpages` / `subpageTarget` - Crawl related subpages
+  - `extras.links` / `extras.imageLinks` - Extract links from pages
+
+The tool works with both `generateText` and `streamText`.
+
+This initial Gateway integration supports Exa's plain Search modes and
+token-efficient content controls. Deep synthesis modes and generated summaries
+are intentionally not exposed yet because they have separate pricing from
+standard Search.
+
 #### Parallel Search
 
 The Parallel Search tool enables models to search the web using [Parallel AI's Search API](https://docs.parallel.ai/api-reference/search-beta/search). This tool is optimized for LLM consumption, returning relevant excerpts from web pages that can replace multiple keyword searches with a single call.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "3.0.136",
+  "version": "3.0.138",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "@vercel/oidc": "3.2.0",
-    "@ai-sdk/provider": "3.0.11",
-    "@ai-sdk/provider-utils": "4.0.31"
+    "@ai-sdk/provider": "3.0.12",
+    "@ai-sdk/provider-utils": "4.0.32"
   },
   "devDependencies": {
     "@types/node": "18.15.11",

package/src/gateway-tools.ts

@@ -1,3 +1,4 @@
+import { exaSearch } from './tool/exa-search';
 import { parallelSearch } from './tool/parallel-search';
 import { perplexitySearch } from './tool/perplexity-search';
 
@@ -5,6 +6,15 @@ import { perplexitySearch } from './tool/perplexity-search';
  * Gateway-specific provider-defined tools.
  */
 export const gatewayTools = {
+  /**
+   * Search the web using Exa for current information and token-efficient
+   * excerpts optimized for agent workflows.
+   *
+   * Supports search type, category, domain, date, location, and content
+   * extraction controls.
+   */
+  exaSearch,
+
   /**
    * Search the web using Parallel AI's Search API for LLM-optimized excerpts.
    *

package/src/gateway-video-model.ts

@@ -46,6 +46,7 @@ export class GatewayVideoModel implements Experimental_VideoModelV3 {
     duration,
     fps,
     seed,
+    generateAudio,
     image,
     providerOptions,
     headers,
@@ -79,6 +80,7 @@ export class GatewayVideoModel implements Experimental_VideoModelV3 {
           ...(duration && { duration }),
           ...(fps && { fps }),
           ...(seed && { seed }),
+          ...(generateAudio !== undefined && { generateAudio }),
           ...(providerOptions && { providerOptions }),
           ...(image && { image: maybeEncodeVideoFile(image) }),
         },

package/src/tool/exa-search.ts

@@ -0,0 +1,352 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod';
+
+export type ExaSearchType = 'auto' | 'fast' | 'instant';
+
+export type ExaSearchCategory =
+  | 'company'
+  | 'people'
+  | 'research paper'
+  | 'news'
+  | 'personal site'
+  | 'financial report';
+
+export type ExaTextSection =
+  | 'header'
+  | 'navigation'
+  | 'banner'
+  | 'body'
+  | 'sidebar'
+  | 'footer'
+  | 'metadata';
+
+export interface ExaSearchTextConfig {
+  maxCharacters?: number;
+  includeHtmlTags?: boolean;
+  verbosity?: 'compact' | 'standard' | 'full';
+  includeSections?: ExaTextSection[];
+  excludeSections?: ExaTextSection[];
+}
+
+export interface ExaSearchHighlightsConfig {
+  query?: string;
+  maxCharacters?: number;
+}
+
+export interface ExaSearchExtrasConfig {
+  links?: number;
+  imageLinks?: number;
+}
+
+export interface ExaSearchContentsConfig {
+  text?: boolean | ExaSearchTextConfig;
+  highlights?: boolean | ExaSearchHighlightsConfig;
+  maxAgeHours?: number;
+  livecrawlTimeout?: number;
+  subpages?: number;
+  subpageTarget?: string | string[];
+  extras?: ExaSearchExtrasConfig;
+}
+
+export interface ExaSearchConfig {
+  /**
+   * Default search method. Exa defaults to auto when omitted.
+   */
+  type?: ExaSearchType;
+
+  /**
+   * Default maximum number of results to return (1-100, default: 10).
+   */
+  numResults?: number;
+
+  /**
+   * Default category filter for result types.
+   */
+  category?: ExaSearchCategory;
+
+  /**
+   * Default two-letter ISO country code for location-aware search.
+   */
+  userLocation?: string;
+
+  /**
+   * Default domains to include or exclude.
+   */
+  includeDomains?: string[];
+  excludeDomains?: string[];
+
+  /**
+   * Default published date filters in ISO 8601 format.
+   */
+  startPublishedDate?: string;
+  endPublishedDate?: string;
+
+  /**
+   * Default content extraction controls.
+   */
+  contents?: ExaSearchContentsConfig;
+}
+
+export interface ExaSearchResult {
+  title: string;
+  url: string;
+  id: string;
+  publishedDate?: string | null;
+  author?: string | null;
+  image?: string | null;
+  favicon?: string | null;
+  text?: string;
+  highlights?: string[];
+  highlightScores?: number[];
+  summary?: string;
+  subpages?: ExaSearchResult[];
+  extras?: {
+    links?: string[];
+    imageLinks?: string[];
+  };
+}
+
+export interface ExaSearchResponse {
+  requestId: string;
+  searchType?: string;
+  resolvedSearchType?: string;
+  results: ExaSearchResult[];
+  costDollars?: {
+    total?: number;
+    search?: Record<string, number>;
+  };
+}
+
+export interface ExaSearchError {
+  error:
+    | 'api_error'
+    | 'rate_limit'
+    | 'timeout'
+    | 'invalid_input'
+    | 'configuration_error'
+    | 'execution_error'
+    | 'unknown';
+  statusCode?: number;
+  message: string;
+}
+
+export interface ExaSearchInput {
+  query: string;
+  type?: ExaSearchType;
+  num_results?: number;
+  category?: ExaSearchCategory;
+  user_location?: string;
+  include_domains?: string[];
+  exclude_domains?: string[];
+  start_published_date?: string;
+  end_published_date?: string;
+  contents?: {
+    text?:
+      | boolean
+      | {
+          max_characters?: number;
+          include_html_tags?: boolean;
+          verbosity?: 'compact' | 'standard' | 'full';
+          include_sections?: ExaTextSection[];
+          exclude_sections?: ExaTextSection[];
+        };
+    highlights?:
+      | boolean
+      | {
+          query?: string;
+          max_characters?: number;
+        };
+    max_age_hours?: number;
+    livecrawl_timeout?: number;
+    subpages?: number;
+    subpage_target?: string | string[];
+    extras?: {
+      links?: number;
+      image_links?: number;
+    };
+  };
+}
+
+export type ExaSearchOutput = ExaSearchResponse | ExaSearchError;
+
+const exaSearchInputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      query: z
+        .string()
+        .describe('Natural-language web search query. This is required.'),
+      type: z
+        .enum(['auto', 'fast', 'instant'])
+        .optional()
+        .describe(
+          'Search method. Use auto for the default balance of speed and quality.',
+        ),
+      num_results: z
+        .number()
+        .optional()
+        .describe('Maximum number of results to return (1-100, default: 10).'),
+      category: z
+        .enum([
+          'company',
+          'people',
+          'research paper',
+          'news',
+          'personal site',
+          'financial report',
+        ])
+        .optional()
+        .describe('Optional content category to focus results.'),
+      user_location: z
+        .string()
+        .optional()
+        .describe("Two-letter ISO country code such as 'US'."),
+      include_domains: z
+        .array(z.string())
+        .optional()
+        .describe('Only return results from these domains.'),
+      exclude_domains: z
+        .array(z.string())
+        .optional()
+        .describe('Exclude results from these domains.'),
+      start_published_date: z
+        .string()
+        .optional()
+        .describe('Only return links published after this ISO 8601 date.'),
+      end_published_date: z
+        .string()
+        .optional()
+        .describe('Only return links published before this ISO 8601 date.'),
+      contents: z
+        .object({
+          text: z
+            .union([
+              z.boolean(),
+              z.object({
+                max_characters: z.number().optional(),
+                include_html_tags: z.boolean().optional(),
+                verbosity: z.enum(['compact', 'standard', 'full']).optional(),
+                include_sections: z
+                  .array(
+                    z.enum([
+                      'header',
+                      'navigation',
+                      'banner',
+                      'body',
+                      'sidebar',
+                      'footer',
+                      'metadata',
+                    ]),
+                  )
+                  .optional(),
+                exclude_sections: z
+                  .array(
+                    z.enum([
+                      'header',
+                      'navigation',
+                      'banner',
+                      'body',
+                      'sidebar',
+                      'footer',
+                      'metadata',
+                    ]),
+                  )
+                  .optional(),
+              }),
+            ])
+            .optional(),
+          highlights: z
+            .union([
+              z.boolean(),
+              z.object({
+                query: z.string().optional(),
+                max_characters: z.number().optional(),
+              }),
+            ])
+            .optional(),
+          max_age_hours: z.number().optional(),
+          livecrawl_timeout: z.number().optional(),
+          subpages: z.number().optional(),
+          subpage_target: z.union([z.string(), z.array(z.string())]).optional(),
+          extras: z
+            .object({
+              links: z.number().optional(),
+              image_links: z.number().optional(),
+            })
+            .optional(),
+        })
+        .optional()
+        .describe('Controls extracted page content and freshness.'),
+    }),
+  ),
+);
+
+const exaSearchOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.union([
+      z.object({
+        requestId: z.string(),
+        searchType: z.string().optional(),
+        resolvedSearchType: z.string().optional(),
+        results: z.array(
+          z.object({
+            title: z.string(),
+            url: z.string(),
+            id: z.string(),
+            publishedDate: z.string().nullable().optional(),
+            author: z.string().nullable().optional(),
+            image: z.string().nullable().optional(),
+            favicon: z.string().nullable().optional(),
+            text: z.string().optional(),
+            highlights: z.array(z.string()).optional(),
+            highlightScores: z.array(z.number()).optional(),
+            summary: z.string().optional(),
+            subpages: z.array(z.any()).optional(),
+            extras: z
+              .object({
+                links: z.array(z.string()).optional(),
+                imageLinks: z.array(z.string()).optional(),
+              })
+              .optional(),
+          }),
+        ),
+        costDollars: z
+          .object({
+            total: z.number().optional(),
+            search: z.record(z.number()).optional(),
+          })
+          .optional(),
+      }),
+      z.object({
+        error: z.enum([
+          'api_error',
+          'rate_limit',
+          'timeout',
+          'invalid_input',
+          'configuration_error',
+          'execution_error',
+          'unknown',
+        ]),
+        statusCode: z.number().optional(),
+        message: z.string(),
+      }),
+    ]),
+  ),
+);
+
+export const exaSearchToolFactory = createProviderToolFactoryWithOutputSchema<
+  ExaSearchInput,
+  ExaSearchOutput,
+  ExaSearchConfig
+>({
+  id: 'gateway.exa_search',
+  inputSchema: exaSearchInputSchema,
+  outputSchema: exaSearchOutputSchema,
+});
+
+export const exaSearch = (
+  config: ExaSearchConfig = {},
+): ReturnType<typeof exaSearchToolFactory> => exaSearchToolFactory(config);

package/src/tool/parallel-search.ts

@@ -199,16 +199,20 @@ const parallelSearchInputSchema = lazySchema(() =>
           include_domains: z
             .array(z.string())
             .optional()
-            .describe('List of domains to include in search results.'),
+            .describe(
+              'Limit results to these domains. Use plain domain names only — e.g. example.com or sub.example.gov, or a bare extension like .edu. Do not include a scheme, path, or port (e.g. not https://example.com/page).',
+            ),
           exclude_domains: z
             .array(z.string())
             .optional()
-            .describe('List of domains to exclude from search results.'),
+            .describe(
+              'Exclude results from these domains. Use plain domain names only — e.g. example.com or sub.example.gov, or a bare extension like .edu. Do not include a scheme, path, or port (e.g. not https://example.com/page).',
+            ),
           after_date: z
             .string()
             .optional()
             .describe(
-              'Only include results published after this date (ISO 8601 format).',
+              'Only include results published after this date. Use an ISO 8601 calendar date formatted YYYY-MM-DD (e.g. 2025-01-01); do not include a time.',
             ),
         })
         .optional()