AI Gateway Provider

The AI Gateway provider connects you to models from multiple AI providers through a single interface. Instead of integrating with each provider separately, you can access OpenAI, Anthropic, Google, Meta, xAI, and other providers and their models.

Features

• Access models from multiple providers without having to install additional provider modules/dependencies
• Use the same code structure across different AI providers
• Switch between models and providers easily
• Automatic authentication when deployed on Vercel
• View pricing information across providers
• Observability for AI model usage through the Vercel dashboard

Setup

The Vercel AI Gateway provider is part of the AI SDK.

Basic Usage

For most use cases, you can use the AI Gateway directly with a model string:

1
// use plain model string with global provider
2
import { generateText } from 'ai';
3

4
const { text } = await generateText({
5
  model: 'openai/gpt-5.4',
6
  prompt: 'Hello world',
7
});

1
// use provider instance (requires version 5.0.36 or later)
2
import { generateText, gateway } from 'ai';
3

4
const { text } = await generateText({
5
  model: gateway('openai/gpt-5.4'),
6
  prompt: 'Hello world',
7
});

The AI SDK automatically uses the AI Gateway when you pass a model string in the creator/model-name format.

Provider Instance

You can also import the default provider instance gateway from ai:

1
import { gateway } from 'ai';

You may want to create a custom provider instance when you need to:

• Set custom configuration options (API key, Vercel access token, base URL, headers)
• Use the provider in a provider registry
• Wrap the provider with middleware
• Use different settings for different parts of your application

To create a custom provider instance, import createGateway from ai:

1
import { createGateway } from 'ai';
2

3
const gateway = createGateway({
4
  apiKey: process.env.AI_GATEWAY_API_KEY ?? '',
5
});

You can use the following optional settings to customize the AI Gateway provider instance:

• baseURL string

  Use a different URL prefix for API calls. The default prefix is https://ai-gateway.vercel.sh/v4/ai.

• apiKey string

  API key or Vercel access token that is being sent using the Authorization header. It defaults to the AI_GATEWAY_API_KEY environment variable. Supports AI Gateway API keys, Vercel personal access tokens, and Vercel app access tokens.

• teamIdOrSlug string

  Vercel team ID or slug used to scope model requests when authenticating with multi-team Vercel access tokens.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

• metadataCacheRefreshMillis number

  How frequently to refresh the metadata cache in milliseconds. Defaults to 5 minutes (300,000ms).

Authentication

The Gateway provider supports the following authentication methods:

API Key Authentication

Set your API key via environment variable:

1
AI_GATEWAY_API_KEY=your_api_key_here

Or pass it directly to the provider:

1
import { createGateway } from 'ai';
2

3
const gateway = createGateway({
4
  apiKey: 'your_api_key_here',
5
});

Vercel Access Token Authentication for Model Requests

For dynamic runtime authentication of model requests, pass a Vercel personal access token or Vercel app access token to a custom Gateway provider instance:

1
import { createGateway } from 'ai';
2

3
const gateway = createGateway({
4
  apiKey: 'your_vercel_access_token_here',
5
  teamIdOrSlug: 'your-team', // required for multi-team tokens
6
});

apiKey takes precedence over AI_GATEWAY_API_KEY and OIDC.

OIDC Authentication (Vercel Deployments)

When deployed to Vercel, the AI Gateway provider supports authenticating model requests using OIDC (OpenID Connect) tokens without API Keys.

How OIDC Authentication Works

1. In Production/Preview Deployments:

   • OIDC authentication is automatically handled
   • No manual configuration needed
   • Tokens are automatically obtained and refreshed

2. In Local Development:

   • First, install and authenticate with the Vercel CLI
   • Run vercel env pull to download your project's OIDC token locally
   • For automatic token management:
     • Use vercel dev to start your development server - this will handle token refreshing automatically
   • For manual token management:
     • If not using vercel dev, note that OIDC tokens expire after 12 hours
     • You'll need to run vercel env pull again to refresh the token before it expires

Read more about using OIDC tokens in the Vercel AI Gateway docs.

Bring Your Own Key (BYOK)

You can connect your own provider credentials to use with Vercel AI Gateway. This lets you use your existing provider accounts and access private resources.

To set up BYOK, add your provider credentials in your Vercel team's AI Gateway settings. Once configured, AI Gateway automatically uses your credentials. No code changes are needed.

For providers like Azure where you can use custom deployment names, you can configure model mappings to map gateway model slugs to your deployment names. See model mappings for details.

Learn more in the BYOK documentation.

Language Models

You can create language models using a provider instance. The first argument is the model ID in the format creator/model-name:

1
import { generateText } from 'ai';
2

3
const { text } = await generateText({
4
  model: 'openai/gpt-5.4',
5
  prompt: 'Explain quantum computing in simple terms',
6
});

AI Gateway language models can also be used in the streamText function and support structured data generation with Output (see AI SDK Core).

When an upstream provider reports a well-formed error after streaming has started, AI SDK Core exposes it as a StreamProviderError. Use its type, code, statusCode, and isRetryable metadata to classify the failure without inspecting the Gateway's serialized error payload.

Batch

AI Gateway supports durable text batches through experimental_startBatch, experimental_getBatchStatus, and experimental_getBatchResults. See Batch for the provider-agnostic workflow, and the AI Gateway batch processing guide for supported models, limits, and Gateway-specific behavior.

Pass a publicly reachable HTTPS webhookUrl when starting a batch to receive a terminal notification instead of polling. AI Gateway sends batch.completed, batch.failed, or batch.cancelled. The event contains terminal status information but not batch results. Completion webhooks are an AI Gateway capability; direct Anthropic and OpenAI batch providers return an unsupported warning when this option is provided.

1
import { randomUUID } from 'node:crypto';
2
import {
3
  experimental_startBatch as startBatch,
4
  type Experimental_BatchReference as BatchReference,
5
  type GatewayProviderMetadata,
6
} from 'ai';
7

8
// The receiver uses this token to look up the expected batch and signing
9
// secret before trusting anything in the webhook body.
10
const token = randomUUID();
11
const model = 'anthropic/claude-haiku-4.5' as const;
12

13
// Reserve the token before starting so an early delivery finds a retryable
14
// pending record rather than an unknown callback.
15
await reserveBatchWebhook(token);
16

17
const batch = await startBatch({
18
  requests: [
19
    {
20
      id: 'france',
21
      type: 'text',
22
      model,
23
      prompt: 'What is the capital of France?',
24
    },
25
    {
26
      id: 'germany',
27
      type: 'text',
28
      model,
29
      prompt: 'What is the capital of Germany?',
30
    },
31
  ],
32
  providerOptions: {
33
    gateway: { idempotencyKey: token },
34
  },
35
  webhookUrl: `https://example.com/api/batch-webhook?token=${token}`,
36
});
37

38
const gatewayMetadata = batch.providerMetadata?.gateway as
39
  | GatewayProviderMetadata
40
  | undefined;
41
const signingSecret = gatewayMetadata?.asyncJob?.webhookSigningSecret;
42

43
if (typeof signingSecret !== 'string') {
44
  throw new Error('AI Gateway did not return a webhook signing secret.');
45
}
46

47
// Keep sensitive provider metadata out of the receiver queue and logs.
48
const batchReference = {
49
  version: batch.version,
50
  id: batch.id,
51
  provider: batch.provider,
52
} satisfies BatchReference;
53

54
await completeBatchWebhookReservation(token, {
55
  batch: batchReference,
56
  signingSecret,
57
});

The signing secret is returned only in the start response. Reserve the callback token before submitting the batch, then persist the secret and minimal batch reference before the process exits. The stable providerOptions.gateway.idempotencyKey makes retrying an ambiguous start safe. Reuse the reserved token when retrying; do not generate a new one. Delete the reservation after a definitive start failure. While the reservation is still pending, the receiver should return a retryable response so an early delivery is sent again after setup completes.

The receiver must verify the x-ai-gateway-signature header against a bounded raw request body before trusting the event:

1
import { createHmac, timingSafeEqual } from 'node:crypto';
2

3
const MAX_AGE_SECONDS = 5 * 60;
4
const MAX_BODY_BYTES = 64 * 1024;
5

6
export async function POST(request: Request) {
7
  const token = new URL(request.url).searchParams.get('token');
8
  if (token == null) return new Response(null, { status: 401 });
9

10
  const record = await loadBatchWebhook(token);
11
  if (record == null) return new Response(null, { status: 401 });
12
  if (record.state !== 'ready') return new Response(null, { status: 503 });
13

14
  const declaredLength = request.headers.get('content-length');
15
  if (declaredLength != null && Number(declaredLength) > MAX_BODY_BYTES) {
16
    return new Response(null, { status: 413 });
17
  }
18

19
  const rawBody = await readBodyWithLimit(request, MAX_BODY_BYTES);
20
  if (rawBody == null) return new Response(null, { status: 413 });
21

22
  const signature = request.headers.get('x-ai-gateway-signature');
23
  if (
24
    signature == null ||
25
    !verifySignature({
26
      header: signature,
27
      rawBody,
28
      secret: record.signingSecret,
29
    })
30
  ) {
31
    return new Response(null, { status: 401 });
32
  }
33

34
  let event: { data?: { jobId?: string; status?: string } };
35
  try {
36
    event = JSON.parse(rawBody);
37
  } catch {
38
    return new Response(null, { status: 400 });
39
  }
40

41
  const jobId = event.data?.jobId;
42
  const status = event.data?.status;
43
  if (
44
    jobId !== record.batch.id ||
45
    (status !== 'cancelled' && status !== 'completed' && status !== 'failed')
46
  ) {
47
    return new Response(null, { status: 401 });
48
  }
49

50
  // The header is not signed, so require it to match the signed event body.
51
  const deliveryId = `${jobId}-${status}`;
52
  if (request.headers.get('x-ai-gateway-idempotency-key') !== deliveryId) {
53
    return new Response(null, { status: 401 });
54
  }
55

56
  await enqueueBatchResultFetch({
57
    batch: record.batch,
58
    deliveryId,
59
  });
60

61
  return new Response(null, { status: 204 });
62
}
63

64
async function readBodyWithLimit(request: Request, maxBytes: number) {
65
  if (request.body == null) return '';
66

67
  const reader = request.body.getReader();
68
  const decoder = new TextDecoder();
69
  let body = '';
70
  let size = 0;
71

72
  try {
73
    while (true) {
74
      const { done, value } = await reader.read();
75
      if (done) return body + decoder.decode();
76

77
      size += value.byteLength;
78
      if (size > maxBytes) {
79
        await reader.cancel();
80
        return undefined;
81
      }
82

83
      body += decoder.decode(value, { stream: true });
84
    }
85
  } finally {
86
    reader.releaseLock();
87
  }
88
}
89

90
function verifySignature({
91
  header,
92
  rawBody,
93
  secret,
94
}: {
95
  header: string;
96
  rawBody: string;
97
  secret: string;
98
}) {
99
  const timestamp = header.match(/(?:^|,)t=(\d+)/)?.[1];
100
  const digest = header.match(/(?:^|,)v1=([0-9a-f]{64})(?:,|$)/)?.[1];
101
  if (timestamp == null || digest == null) return false;
102

103
  const expected = createHmac('sha256', secret)
104
    .update(`${timestamp}.${rawBody}`, 'utf8')
105
    .digest('hex');
106
  const provided = Buffer.from(digest, 'hex');
107
  const computed = Buffer.from(expected, 'hex');
108
  if (provided.length !== computed.length) return false;
109
  if (!timingSafeEqual(provided, computed)) return false;
110

111
  return Math.abs(Date.now() / 1000 - Number(timestamp)) <= MAX_AGE_SECONDS;
112
}

The signature header has the form t=<unix seconds>,v1=<hex digest>, where v1 is the HMAC-SHA256 digest of "<t>.<raw body>". Verify a size-limited raw request body rather than a re-serialized object, use a timing-safe comparison, reject stale timestamps, and reject events whose data.jobId does not match the persisted batch.id.

AI Gateway expects a 2xx response within 10 seconds and retries failed deliveries. It does not follow redirects, so the callback endpoint itself must return the 2xx response. Retries carry the same x-ai-gateway-idempotency-key value (<jobId>-<status>), which receivers can use for deduplication. After verification, pass the persisted batch reference to experimental_getBatchStatus and experimental_getBatchResults. Delivery is best-effort, so periodically reconcile persisted batches by status as a fallback for a notification that exhausts its retries.

Each request specifies its type and model. AI Gateway currently requires every text request in a batch to use the same model and throws before submission when the models differ.

Reranking Models

You can create reranking models using the rerankingModel method on the provider instance:

1
import { rerank } from 'ai';
2
import { gateway } from '@ai-sdk/gateway';
3

4
const { ranking } = await rerank({
5
  model: gateway.rerankingModel('cohere/rerank-v3.5'),
6
  query: 'What is the capital of France?',
7
  documents: [
8
    'Paris is the capital of France.',
9
    'Berlin is the capital of Germany.',
10
    'Madrid is the capital of Spain.',
11
  ],
12
  topN: 2,
13
});
14

15
console.log(ranking);
16
// [
17
//   { originalIndex: 0, score: 0.89, document: 'Paris is the capital of France.' },
18
//   { originalIndex: 2, score: 0.15, document: 'Madrid is the capital of Spain.' },
19
// ]

Reranking models are useful for improving search results in retrieval-augmented generation (RAG) pipelines by re-scoring candidate documents after an initial retrieval step.

Realtime Models

You can create realtime models for bidirectional audio/text WebSocket sessions using the experimental_realtime method on the provider instance. The first argument is the model ID in the format creator/model-name:

1
import { gateway } from '@ai-sdk/gateway';
2

3
const model = gateway.experimental_realtime('openai/gpt-realtime-2');

The Gateway normalizes realtime the same way it normalizes every other modality: your client speaks the normalized AI SDK realtime protocol and the Gateway translates to and from the upstream provider server-side. This means the same client code works regardless of which provider backs the model.

Realtime sessions run in the browser and require a short-lived Gateway client secret created on your server with gateway.experimental_realtime.getToken(). The method uses your Gateway credential (apiKey, AI_GATEWAY_API_KEY, or Vercel OIDC token) to mint a vcst_ client secret and returns the WebSocket URL for the model.

1
import { gateway } from 'ai';
2

3
export async function POST() {
4
  const token = await gateway.experimental_realtime.getToken({
5
    model: 'openai/gpt-realtime-2',
6
    expiresAfterSeconds: 60 * 10,
7
  });
8

9
  return Response.json(token);
10
}

Use the matching Gateway realtime model in the browser. Creating the model is safe in browser code; only getToken() is server-side.

1
'use client';
2

3
import { experimental_useRealtime } from '@ai-sdk/react';
4
import { gateway } from 'ai';
5

6
export default function RealtimePage() {
7
  const realtime = experimental_useRealtime({
8
    model: gateway.experimental_realtime('openai/gpt-realtime-2'),
9
    api: {
10
      token: '/api/realtime/setup',
11
    },
12
  });
13

14
  // ...
15
}

Do not expose your Gateway API key or OIDC token to browser clients. Only return the short-lived setup response from getToken().

Provider Options

Gateway provider options — tags, user, byok, compliance flags, and so on — are set under providerOptions.gateway in the session configuration, mirroring how they ride the request body on the non-realtime routes. Include them in the session configuration you send to the Gateway, and the Gateway applies them server-side:

1
import type { GatewayProviderOptions } from '@ai-sdk/gateway';
2

3
const gatewayOptions: GatewayProviderOptions = {
4
  tags: ['cooking-coach', 'v2'],
5
  user: 'user-123',
6
};
7

8
const sessionConfig = {
9
  instructions: 'You are a concise voice assistant.',
10
  providerOptions: { gateway: gatewayOptions },
11
};

The GatewayProviderOptions type is exported from @ai-sdk/gateway for stable client-facing fields. The type also accepts service-owned option keys so the Gateway service can add or change server-side options without requiring an SDK release for every schema change. Runtime validation is owned by the Gateway service.

Available Models

The AI Gateway supports models from OpenAI, Anthropic, Google, Meta, xAI, Mistral, DeepSeek, Amazon Bedrock, Cohere, Perplexity, Alibaba, and other providers.

For the complete list of available models, see the AI Gateway documentation.

Dynamic Model Discovery

You can discover available models programmatically:

1
import { gateway, generateText } from 'ai';
2

3
const availableModels = await gateway.getAvailableModels();
4

5
// List all available models
6
availableModels.models.forEach(model => {
7
  console.log(`${model.id}: ${model.name}`);
8
  if (model.description) {
9
    console.log(`  Description: ${model.description}`);
10
  }
11
  if (model.pricing) {
12
    console.log(`  Input: $${model.pricing.input}/token`);
13
    console.log(`  Output: $${model.pricing.output}/token`);
14
    if (model.pricing.cachedInputTokens) {
15
      console.log(
16
        `  Cached input (read): $${model.pricing.cachedInputTokens}/token`,
17
      );
18
    }
19
    if (model.pricing.cacheCreationInputTokens) {
20
      console.log(
21
        `  Cache creation (write): $${model.pricing.cacheCreationInputTokens}/token`,
22
      );
23
    }
24
  }
25
});
26

27
// Use any discovered model with plain string
28
const { text } = await generateText({
29
  model: availableModels.models[0].id, // e.g., 'openai/gpt-5.4'
30
  prompt: 'Hello world',
31
});

Credit Usage

You can check your team's current credit balance and usage:

1
import { gateway } from 'ai';
2

3
const credits = await gateway.getCredits();
4

5
console.log(`Team balance: ${credits.balance} credits`);
6
console.log(`Team total used: ${credits.total_used} credits`);

The getCredits() method returns your team's credit information based on the authenticated API key or OIDC token:

• balance number - Your team's current available credit balance
• total_used number - Total credits consumed by your team

Generation Lookup

Look up detailed information about a specific generation by its ID, including cost, token usage, latency, and provider details. Generation IDs are available in providerMetadata.gateway.generationId on both generateText and streamText responses.

When streaming, the generation ID is injected on the first content chunk, so you can capture it early in the stream without waiting for completion. This is especially useful in cases where a network interruption or mid-stream error could prevent you from receiving the final response — since the gateway records the final status server-side, you can use the generation ID to look up the results (including cost, token usage, and finish reason) later via getGenerationInfo().

1
import { gateway, generateText } from 'ai';
2

3
// Make a request
4
const result = await generateText({
5
  model: gateway('anthropic/claude-sonnet-4'),
6
  prompt: 'Explain quantum entanglement briefly',
7
});
8

9
// Get the generation ID from provider metadata
10
const generationId = result.providerMetadata?.gateway?.generationId;
11

12
// Look up detailed generation info
13
const generation = await gateway.getGenerationInfo({ id: generationId });
14

15
console.log(`Model: ${generation.model}`);
16
console.log(`Cost: $${generation.totalCost.toFixed(6)}`);
17
console.log(`Latency: ${generation.latency}ms`);
18
console.log(`Prompt tokens: ${generation.promptTokens}`);
19
console.log(`Completion tokens: ${generation.completionTokens}`);

With streamText, you can capture the generation ID from the first chunk via stream:

1
import { gateway, streamText } from 'ai';
2

3
const result = streamText({
4
  model: gateway('anthropic/claude-sonnet-4'),
5
  prompt: 'Explain quantum entanglement briefly',
6
});
7

8
let generationId: string | undefined;
9

10
for await (const part of result.stream) {
11
  if (!generationId && part.providerMetadata?.gateway?.generationId) {
12
    generationId = part.providerMetadata.gateway.generationId as string;
13
    console.log(`Generation ID (early): ${generationId}`);
14
  }
15
}
16

17
// Look up cost and usage after the stream completes
18
if (generationId) {
19
  const generation = await gateway.getGenerationInfo({ id: generationId });
20
  console.log(`Cost: $${generation.totalCost.toFixed(6)}`);
21
  console.log(`Finish reason: ${generation.finishReason}`);
22
}

You can also capture the generation ID for every completed model call with onLanguageModelCallEnd. The callback runs before client-side tools execute, so the metadata remains available even if the operation is later aborted while a tool is running:

1
import { gateway, generateText } from 'ai';
2

3
await generateText({
4
  model: gateway('anthropic/claude-sonnet-4'),
5
  prompt: 'Explain quantum entanglement briefly',
6
  onLanguageModelCallEnd({ providerMetadata }) {
7
    const generationId = providerMetadata?.gateway?.generationId as
8
      | string
9
      | undefined;
10

11
    if (generationId) {
12
      console.log(`Completed Gateway generation: ${generationId}`);
13
    }
14
  },
15
});

The getGenerationInfo() method accepts:

• id string - The generation ID to look up (format: gen_<ulid>, required)

It returns a GatewayGenerationInfo object with the following fields:

• id string - The generation ID
• totalCost number - Total cost in USD
• upstreamInferenceCost number - Upstream inference cost in USD (relevant for BYOK)
• usage number - Usage cost in USD (same as totalCost)
• createdAt string - ISO 8601 timestamp when the generation was created
• model string - Model identifier used
• isByok boolean - Whether Bring Your Own Key credentials were used
• providerName string - The provider that served this generation
• streamed boolean - Whether streaming was used
• finishReason string - Finish reason (e.g. 'stop')
• latency number - Time to first token in milliseconds
• generationTime number - Total generation time in milliseconds
• promptTokens number - Number of prompt tokens
• completionTokens number - Number of completion tokens
• reasoningTokens number - Reasoning tokens used (if applicable)
• cachedTokens number - Cached tokens used (if applicable)
• cacheCreationTokens number - Cache creation input tokens
• billableWebSearchCalls number - Number of billable web search calls

Examples

Basic Text Generation

1
import { generateText } from 'ai';
2

3
const { text } = await generateText({
4
  model: 'anthropic/claude-sonnet-4.6',
5
  prompt: 'Write a haiku about programming',
6
});
7

8
console.log(text);

Streaming

1
import { streamText } from 'ai';
2

3
const { textStream } = await streamText({
4
  model: 'openai/gpt-5.4',
5
  prompt: 'Explain the benefits of serverless architecture',
6
});
7

8
for await (const textPart of textStream) {
9
  process.stdout.write(textPart);
10
}

Tool Usage

1
import { generateText, tool } from 'ai';
2
import { z } from 'zod';
3

4
const { text } = await generateText({
5
  model: 'xai/grok-4.6',
6
  prompt: 'What is the weather like in San Francisco?',
7
  tools: {
8
    getWeather: tool({
9
      description: 'Get the current weather for a location',
10
      inputSchema: z.object({
11
        location: z.string().describe('The location to get weather for'),
12
      }),
13
      execute: async ({ location }) => {
14
        // Your weather API call here
15
        return `It's sunny in ${location}`;
16
      },
17
    }),
18
  },
19
});

Provider-Executed Tools

Some providers offer tools that are executed by the provider itself, such as OpenAI's web search tool. To use these tools through AI Gateway, import the provider to access the tool definitions:

1
import { generateText, isStepCount } from 'ai';
2
import { openai } from '@ai-sdk/openai';
3

4
const result = await generateText({
5
  model: 'openai/gpt-5.4-mini',
6
  prompt: 'What is the Vercel AI Gateway?',
7
  stopWhen: isStepCount(10),
8
  tools: {
9
    web_search: openai.tools.webSearch({}),
10
  },
11
});
12

13
console.dir(result.text);

Gateway Tools

The AI Gateway provider includes built-in tools that are executed by the gateway itself. These tools can be used with any model through the gateway.

Perplexity Search

The Perplexity Search tool enables models to search the web using Perplexity's search API. This tool is executed by the AI Gateway and returns web search results that the model can use to provide up-to-date information.

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Search for news about AI regulations in January 2025.',
6
  tools: {
7
    perplexity_search: gateway.tools.perplexitySearch(),
8
  },
9
});
10

11
console.log(result.text);
12
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
13
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

You can also configure the search with optional parameters:

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt:
6
    'Search for news about AI regulations from the first week of January 2025.',
7
  tools: {
8
    perplexity_search: gateway.tools.perplexitySearch({
9
      maxResults: 5,
10
      searchLanguageFilter: ['en'],
11
      country: 'US',
12
      searchDomainFilter: ['reuters.com', 'bbc.com', 'nytimes.com'],
13
    }),
14
  },
15
});
16

17
console.log(result.text);
18
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
19
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

The Perplexity Search tool supports the following optional configuration options:

• maxResults number

  The maximum number of search results to return (1-20, default: 10).

• maxTokensPerPage number

  The maximum number of tokens to extract per search result page (256-2048, default: 2048).

• maxTokens number

  The maximum total tokens across all search results (default: 25000, max: 1000000).

• searchLanguageFilter string[]

  Filter search results by language using ISO 639-1 language codes (e.g., ['en'] for English, ['en', 'es'] for English and Spanish).

• country string

  Filter search results by country using ISO 3166-1 alpha-2 country codes (e.g., 'US' for United States, 'GB' for United Kingdom).

• searchDomainFilter string[]

  Limit search results to specific domains (e.g., ['reuters.com', 'bbc.com']). This is useful for restricting results to trusted sources.

• searchRecencyFilter 'day' | 'week' | 'month' | 'year'

  Filter search results by relative time period. Useful for always getting recent results (e.g., 'week' for results from the last week).

The tool works with both generateText and streamText:

1
import { gateway, streamText } from 'ai';
2

3
const result = streamText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Search for the latest news about AI regulations.',
6
  tools: {
7
    perplexity_search: gateway.tools.perplexitySearch(),
8
  },
9
});
10

11
for await (const part of result.stream) {
12
  switch (part.type) {
13
    case 'text-delta':
14
      process.stdout.write(part.text);
15
      break;
16
    case 'tool-call':
17
      console.log('\nTool call:', JSON.stringify(part, null, 2));
18
      break;
19
    case 'tool-result':
20
      console.log('\nTool result:', JSON.stringify(part, null, 2));
21
      break;
22
  }
23
}

Exa Search

The Exa Search tool enables models to search the web using Exa's Search API. This tool is executed by the AI Gateway and returns token-efficient web excerpts for agent workflows.

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt:
6
    'Find the latest AI regulation updates and summarize the key changes.',
7
  tools: {
8
    exa_search: gateway.tools.exaSearch(),
9
  },
10
});
11

12
console.log(result.text);
13
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
14
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

You can also configure the search with optional parameters:

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Find recent AI regulation news from trusted sources.',
6
  tools: {
7
    exa_search: gateway.tools.exaSearch({
8
      type: 'fast',
9
      numResults: 5,
10
      category: 'news',
11
      includeDomains: ['reuters.com', 'bbc.com', 'nytimes.com'],
12
      contents: {
13
        highlights: true,
14
        maxAgeHours: 24,
15
      },
16
    }),
17
  },
18
});
19

20
console.log(result.text);
21
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
22
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.

Tako Search

The Tako Search tool enables models to search the web and Tako's curated knowledge graph in a single call using Tako's Search API. This tool is executed by the AI Gateway and returns token-efficient web excerpts, plus knowledge-graph results that carry structured data, premium source attribution, and an embed-ready visualization.

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'How has Nvidia quarterly revenue changed over the last two years?',
6
  tools: {
7
    tako_search: gateway.tools.takoSearch(),
8
  },
9
});
10

11
console.log(result.text);
12
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
13
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

Configure the search with effort, source selection, and localization defaults. These defaults override values the model includes in a tool call:

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'AMD vs. Nvidia headcount since 2013',
6
  tools: {
7
    tako_search: gateway.tools.takoSearch({
8
      effort: 'fast',
9
      sources: {
10
        data: {
11
          contentFormat: 'json_compact',
12
          includeContents: true,
13
          maxRows: 100,
14
        },
15
        web: {
16
          count: 3,
17
        },
18
      },
19
      countryCode: 'US',
20
      locale: 'en-US',
21
    }),
22
  },
23
});
24

25
console.log(result.text);

The Tako Search tool supports these optional configuration options:

• effort 'fast' | 'instant' | 'deep' - Search effort. 'fast' is the balanced default, 'instant' favors cached low-latency results, and 'deep' broadens retrieval with reranking at higher cost and latency.
• sources object - Omit to search both curated Tako data and the live web. When set, only source keys present are searched.
• sources.web object - Configure web results:
  • count number - Maximum web results, 1-20.
  • category 'finance' | 'news' | 'sports' - Restrict web results to one category.
  • includeDomains / excludeDomains string[] - Only return, or drop, results from these bare domains. Up to 20 each.
  • publishedAfter / publishedBefore string - Keep results published on or after, or on or before, this YYYY-MM-DD date.
  • snippetMaxChars number - Character cap on each result's text excerpt. Defaults to 4,000; maximum 20,000.
  • highlights boolean - Return query-relevant passages as each result's snippet instead of the opening text of the page. The snippet can hold multiple passages joined by ' ... ', and a page with no highlight returns snippet: null. Defaults to true in the AI Gateway.
  • includeContents boolean - Inline each page's extracted full text in content. articleContentMaxChars caps it, defaulting to 30,000 characters (maximum 1,000,000).
• sources.data object - Configure data results:
  • count number - Maximum data results, 1-20. Defaults to 5.
  • includeContents boolean - Inline each card's underlying rows in content.dataset as typed, unit-labeled columns. This adds a data surcharge based on the row count and dataset source. To estimate cost, first search with includeContents: false and inspect cards.content.export_pricing. Because this applies to every returned card, use count and maxRows to control cost.
  • contentFormat 'json_compact' | 'json_records' | 'csv' | 'card_json' - Serialization for inlined card data. Defaults to 'json_compact'.
  • maxRows number - Row cap per result. Omit to use the allowance in cards.content.export_pricing. A data surcharge applies per 1,000 exported rows; lower values reduce cost.
  • nodeIds string[] - Data Graph node IDs to prioritize. Up to 20.
  • strict boolean - Only return cards matching nodeIds. Requires at least one nodeIds value.
• location object - End-user { latitude, longitude } coordinates for localized results.
• countryCode string - ISO 3166-1 alpha-2 country code, such as 'US'.
• locale string - BCP-47 locale, such as 'en-US'.
• timezone string - IANA timezone, such as 'America/New_York'.
• outputSettings object - Card rendering controls. forceRefresh is available only with 'instant' effort.
• includeRelated number - Number of related search suggestions to include (1-20).

For precise entity matching, quote a phrase in the query and optionally append a label: "Tesla":PRODUCT price. Tako treats the quoted phrase as one entity before searching.

The tool works with both generateText and streamText:

1
import { gateway, streamText } from 'ai';
2

3
const result = streamText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'What is the latest US inflation rate?',
6
  tools: {
7
    tako_search: gateway.tools.takoSearch(),
8
  },
9
});
10

11
for await (const part of result.stream) {
12
  switch (part.type) {
13
    case 'text-delta':
14
      process.stdout.write(part.text);
15
      break;
16
    case 'tool-call':
17
      console.log('\nTool call:', JSON.stringify(part, null, 2));
18
      break;
19
    case 'tool-result':
20
      console.log('\nTool result:', JSON.stringify(part, null, 2));
21
      break;
22
  }
23
}

Parallel Search

The Parallel Search tool enables models to search the web using Parallel AI's Search API. This tool is optimized for LLM consumption, returning relevant excerpts from web pages that can replace multiple keyword searches with a single call.

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Research the latest developments in quantum computing.',
6
  tools: {
7
    parallel_search: gateway.tools.parallelSearch(),
8
  },
9
});
10

11
console.log(result.text);
12
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
13
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

You can also configure the search with optional parameters:

1
import { gateway, generateText } from 'ai';
2

3
const result = await generateText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Find detailed information about TypeScript 5.0 features.',
6
  tools: {
7
    parallel_search: gateway.tools.parallelSearch({
8
      mode: 'agentic',
9
      maxResults: 5,
10
      sourcePolicy: {
11
        includeDomains: ['typescriptlang.org', 'github.com'],
12
      },
13
      excerpts: {
14
        maxCharsPerResult: 8000,
15
      },
16
    }),
17
  },
18
});
19

20
console.log(result.text);
21
console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
22
console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));

The Parallel Search tool supports the following optional configuration options:

• mode 'one-shot' | 'agentic'

  Mode preset for different use cases:

  • 'one-shot' - Comprehensive results with longer excerpts for single-response answers (default)
  • 'agentic' - Concise, token-efficient results optimized for multi-step agentic workflows

• maxResults number

  Maximum number of results to return (1-20). Defaults to 10 if not specified.

• sourcePolicy object

  Source policy for controlling which domains to include/exclude:

  • includeDomains - List of domains to include in search results
  • excludeDomains - List of domains to exclude from search results
  • afterDate - Only include results published after this date (ISO 8601 format)

• excerpts object

  Excerpt configuration for controlling result length:

  • maxCharsPerResult - Maximum characters per result
  • maxCharsTotal - Maximum total characters across all results

• fetchPolicy object

  Fetch policy for controlling content freshness:

  • maxAgeSeconds - Maximum age in seconds for cached content (set to 0 for always fresh)

The tool works with both generateText and streamText:

1
import { gateway, streamText } from 'ai';
2

3
const result = streamText({
4
  model: 'openai/gpt-5.4-nano',
5
  prompt: 'Research the latest AI safety guidelines.',
6
  tools: {
7
    parallel_search: gateway.tools.parallelSearch(),
8
  },
9
});
10

11
for await (const part of result.stream) {
12
  switch (part.type) {
13
    case 'text-delta':
14
      process.stdout.write(part.text);
15
      break;
16
    case 'tool-call':
17
      console.log('\nTool call:', JSON.stringify(part, null, 2));
18
      break;
19
    case 'tool-result':
20
      console.log('\nTool result:', JSON.stringify(part, null, 2));
21
      break;
22
  }
23
}

Custom Reporting

Track usage per end-user and categorize requests with tags, then query the data through the reporting API.

Usage Tracking with User and Tags

1
import type { GatewayProviderOptions } from '@ai-sdk/gateway';
2
import { generateText } from 'ai';
3

4
const { text } = await generateText({
5
  model: 'openai/gpt-5.4',
6
  prompt: 'Summarize this document...',
7
  providerOptions: {
8
    gateway: {
9
      user: 'user-abc-123', // Track usage for this specific end-user
10
      tags: ['document-summary', 'premium-feature'], // Categorize for reporting
11
    } satisfies GatewayProviderOptions,
12
  },
13
});