Backport: feat (provider/gateway): add provider routing sort options (#14508)

This is an automated backport of #14311 to the release-v6.0 branch. FYI
@shaper

---------

Co-authored-by: Walter Korman <shaper@vercel.com>

Author: vercel-ai-sdk[bot]

.changeset/bright-crabs-float.md

@@ -0,0 +1,5 @@
+---
+"@ai-sdk/gateway": patch
+---
+
+feat (provider/gateway): add sort options

content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

@@ -776,6 +776,20 @@ The following gateway provider options are available:
 
   Example: `only: ['anthropic', 'vertex']` will only allow routing to Anthropic or Vertex AI.
 
+- **sort** _'cost' | 'ttft' | 'tps'_
+
+  Sorts available providers by a performance or cost metric before routing. The gateway will try the best-scoring provider first and fall back through the rest in sorted order. If unspecified, providers are ordered using the gateway's default system ranking.
+
+  - `'cost'` — lowest cost first
+  - `'ttft'` — lowest time-to-first-token first
+  - `'tps'` — highest tokens-per-second first
+
+  When combined with `order`, the user-specified providers are promoted to the front while remaining providers follow the sorted order.
+
+  Example: `sort: 'ttft'` will route to the provider with the fastest time-to-first-token.
+
+  When `sort` is active, the response's `providerMetadata.gateway.routing.sort` object contains the sort option used, the resulting execution order, per-provider metric values, and any providers that were deprioritized.
+
 - **models** _string[]_
 
   Specifies fallback models to use when the primary model fails or is unavailable. The gateway will try the primary model first (specified in the `model` parameter), then try each model in this array in order until one succeeds.

examples/ai-functions/src/generate-text/gateway/provider-options-sort.ts

@@ -0,0 +1,20 @@
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { generateText } from 'ai';
+import { run } from '../../lib/run';
+
+run(async () => {
+  const { providerMetadata, text, usage } = await generateText({
+    model: 'openai/gpt-oss-120b',
+    prompt: 'Invent a new holiday and describe its traditions.',
+    providerOptions: {
+      gateway: {
+        sort: 'ttft',
+      } satisfies GatewayProviderOptions,
+    },
+  });
+
+  console.log(text);
+  console.log();
+  console.log('Usage:', usage);
+  console.log(JSON.stringify(providerMetadata, null, 2));
+});

examples/ai-functions/src/stream-text/gateway/provider-options-sort.ts

@@ -0,0 +1,27 @@
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { streamText } from 'ai';
+import { run } from '../../lib/run';
+
+run(async () => {
+  const result = streamText({
+    model: 'openai/gpt-oss-120b',
+    prompt: 'Invent a new holiday and describe its traditions.',
+    providerOptions: {
+      gateway: {
+        sort: 'ttft',
+      } satisfies GatewayProviderOptions,
+    },
+  });
+
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+
+  console.log();
+  console.log('Token usage:', await result.usage);
+  console.log('Finish reason:', await result.finishReason);
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(await result.providerMetadata, null, 2),
+  );
+});

packages/gateway/src/gateway-provider-options.ts

@@ -17,6 +17,14 @@ const gatewayProviderOptions = lazySchema(() =>
        * Example: `['bedrock', 'anthropic']` will try Amazon Bedrock first, then Anthropic as fallback.
        */
       order: z.array(z.string()).optional(),
+      /**
+       * Sort providers by a performance or cost metric before routing.
+       *
+       * - `'cost'`: lowest cost first
+       * - `'ttft'`: lowest time-to-first-token first
+       * - `'tps'`: highest tokens-per-second first
+       */
+      sort: z.enum(['cost', 'ttft', 'tps']).optional(),
       /**
        * The unique identifier for the end user on behalf of whom the request was made.
        *