fix(gateway): add caching provider option

.changeset/gateway-caching-provider-option.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/gateway': patch
+---
+
+Add `caching: 'auto'` to `GatewayProviderOptions`.

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

@@ -794,6 +794,12 @@ The following gateway provider options are available:
 
   Example: `models: ['openai/gpt-5.4-nano', 'gemini-3-flash-preview']` will try the fallback models in order if the primary model fails.
 
+- **caching** _'auto'_
+
+  Enables automatic prompt caching. When set to `'auto'`, AI Gateway automatically applies the appropriate caching strategy based on the routed provider.
+
+  Example: `caching: 'auto'` will let AI Gateway add cache markers for providers that require explicit prompt caching.
+
 - **user** _string_
 
   Optional identifier for the end user on whose behalf the request is being made. This is used for spend tracking and attribution purposes, allowing you to track usage per end-user in your application.

packages/gateway/src/gateway-language-model.test.ts

@@ -6,6 +6,7 @@ import { createTestServer } from '@ai-sdk/test-server/with-vitest';
 import { convertReadableStreamToArray } from '@ai-sdk/provider-utils/test';
 import { GatewayLanguageModel } from './gateway-language-model';
 import type { GatewayConfig } from './gateway-config';
+import type { GatewayProviderOptions } from './gateway-provider-options';
 import {
   GatewayAuthenticationError,
   GatewayRateLimitError,
@@ -1523,18 +1524,24 @@ describe('GatewayLanguageModel', () => {
         content: { type: 'text', text: 'Test response' },
       });
 
+      const gatewayOptions = {
+        order: ['anthropic', 'bedrock', 'openai'],
+        caching: 'auto',
+      } satisfies GatewayProviderOptions;
+
       await createTestModel().doGenerate({
         prompt: TEST_PROMPT,
         providerOptions: {
-          gateway: {
-            order: ['anthropic', 'bedrock', 'openai'],
-          },
+          gateway: gatewayOptions,
         },
       });
 
       const requestBody = await server.calls[0].requestBodyJson;
       expect(requestBody.providerOptions).toEqual({
-        gateway: { order: ['anthropic', 'bedrock', 'openai'] },
+        gateway: {
+          order: ['anthropic', 'bedrock', 'openai'],
+          caching: 'auto',
+        },
       });
     });
 

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

@@ -0,0 +1,12 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { GatewayProviderOptions } from './gateway-provider-options';
+
+describe('GatewayProviderOptions type', () => {
+  it('should allow automatic caching', () => {
+    const options = {
+      caching: 'auto',
+    } satisfies GatewayProviderOptions;
+
+    expectTypeOf(options).toMatchTypeOf<GatewayProviderOptions>();
+  });
+});

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

@@ -49,6 +49,11 @@ const gatewayProviderOptions = lazySchema(() =>
        * Example: `['openai/gpt-5-nano', 'zai/glm-4.6']` will try `openai/gpt-5-nano` first, then `zai/glm-4.6` as fallback.
        */
       models: z.array(z.string()).optional(),
+      /**
+       * Whether AI Gateway should automatically apply the appropriate prompt
+       * caching strategy based on the routed provider.
+       */
+      caching: z.enum(['auto']).optional(),
       /**
        * Request-scoped BYOK credentials to use instead of cached credentials.
        *