From 72f889c7a2f71d5ea1df6b2fd2029ff25b7ce1e3 Mon Sep 17 00:00:00 2001
From: Zelys <zelys@dfkhelper.com>
Date: Fri, 17 Apr 2026 13:29:50 -0500
Subject: [PATCH 1/2] fix(provider/gateway): add missing caching property to
 GatewayProviderOptions

The GatewayProviderOptions type was missing the caching field despite it being
documented at https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching.
This caused a TypeScript error when users tried to set caching: 'auto' with
satisfies GatewayProviderOptions.

Fixes #14595
---
 .changeset/fix-gateway-caching-type.md        |  5 ++++
 .../01-ai-sdk-providers/00-ai-gateway.mdx     |  8 ++++++
 .../src/stream-text/gateway/auto-caching.ts   | 26 +++++++++++++++++++
 .../gateway/src/gateway-provider-options.ts   | 13 ++++++++++
 4 files changed, 52 insertions(+)
 create mode 100644 .changeset/fix-gateway-caching-type.md
 create mode 100644 examples/ai-functions/src/stream-text/gateway/auto-caching.ts

diff --git a/.changeset/fix-gateway-caching-type.md b/.changeset/fix-gateway-caching-type.md
new file mode 100644
index 000000000000..b06f10138f30
--- /dev/null
+++ b/.changeset/fix-gateway-caching-type.md
@@ -0,0 +1,5 @@
+---
+"@ai-sdk/gateway": patch
+---
+
+fix(provider/gateway): add missing `caching` property to GatewayProviderOptions type
diff --git a/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx b/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
index 47cdac992978..0130e4c8ddd8 100644
--- a/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
+++ b/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
@@ -851,6 +851,14 @@ The following gateway provider options are available:
 
   For full details, see [Provider Timeouts](https://vercel.com/docs/ai-gateway/models-and-providers/provider-timeouts).
 
+- **caching** _'auto'_
+
+  Automatic prompt caching strategy. When set to `'auto'`, AI Gateway handles caching automatically based on the provider. For providers that require explicit cache markers (Anthropic, MiniMax), AI Gateway adds a `cache_control` breakpoint at the end of static content. For providers with implicit caching (OpenAI, Google, DeepSeek), no modification is needed.
+
+  When not set, requests pass through without modification.
+
+  For full details, see [Automatic Caching](https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching).
+
 You can combine these options to have fine-grained control over routing and tracking:
 
 ```ts
diff --git a/examples/ai-functions/src/stream-text/gateway/auto-caching.ts b/examples/ai-functions/src/stream-text/gateway/auto-caching.ts
new file mode 100644
index 000000000000..71baefb8223d
--- /dev/null
+++ b/examples/ai-functions/src/stream-text/gateway/auto-caching.ts
@@ -0,0 +1,26 @@
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { streamText } from 'ai';
+import { run } from '../../lib/run';
+
+run(async () => {
+  const result = streamText({
+    model: 'anthropic/claude-sonnet-4.6',
+    system:
+      'You are a helpful assistant with access to a large knowledge base. ' +
+      'Answer questions concisely and accurately.',
+    prompt: 'What is the capital of France?',
+    providerOptions: {
+      gateway: {
+        caching: 'auto',
+      } 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);
+});
diff --git a/packages/gateway/src/gateway-provider-options.ts b/packages/gateway/src/gateway-provider-options.ts
index 5a808d505b7a..a577da54102f 100644
--- a/packages/gateway/src/gateway-provider-options.ts
+++ b/packages/gateway/src/gateway-provider-options.ts
@@ -100,6 +100,19 @@ const gatewayProviderOptions = lazySchema(() =>
           byok: z.record(z.string(), z.number().int().min(1000)).optional(),
         })
         .optional(),
+      /**
+       * Automatic prompt caching strategy.
+       *
+       * - `'auto'`: Let AI Gateway handle caching automatically. For providers that
+       *   require explicit cache markers (Anthropic, MiniMax), AI Gateway adds a
+       *   `cache_control` breakpoint at the end of static content. For providers
+       *   with implicit caching (OpenAI, Google, DeepSeek), no modification is needed.
+       *
+       * When not set, requests pass through without modification.
+       *
+       * See https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching
+       */
+      caching: z.literal('auto').optional(),
     }),
   ),
 );

From 50c100a0ddf5236758bd95510754b0102f576eed Mon Sep 17 00:00:00 2001
From: Zelys <zelys@dfkhelper.com>
Date: Fri, 17 Apr 2026 13:42:03 -0500
Subject: [PATCH 2/2] test(provider/gateway): add type tests for
 GatewayProviderOptions caching field

---
 .../src/gateway-provider-options.test-d.ts    | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 packages/gateway/src/gateway-provider-options.test-d.ts

diff --git a/packages/gateway/src/gateway-provider-options.test-d.ts b/packages/gateway/src/gateway-provider-options.test-d.ts
new file mode 100644
index 000000000000..0fbebe515f28
--- /dev/null
+++ b/packages/gateway/src/gateway-provider-options.test-d.ts
@@ -0,0 +1,27 @@
+import { describe, it } from 'vitest';
+import type { GatewayProviderOptions } from './index';
+
+describe('GatewayProviderOptions', () => {
+  it('should accept caching: auto', () => {
+    const options = {
+      caching: 'auto',
+    } satisfies GatewayProviderOptions;
+
+    options;
+  });
+
+  it('should make caching optional', () => {
+    const options = {} satisfies GatewayProviderOptions;
+
+    options;
+  });
+
+  it('should reject unknown caching values', () => {
+    const options = {
+      // @ts-expect-error 'manual' is not a valid caching value
+      caching: 'manual',
+    } satisfies GatewayProviderOptions;
+
+    options;
+  });
+});