From 91b7183a276c6ef584b587e1d7201083daf8bd19 Mon Sep 17 00:00:00 2001
From: Genmin <joey@joeyroth.com>
Date: Thu, 30 Apr 2026 16:34:03 -0700
Subject: [PATCH] fix: add gateway caching provider option

---
 .changeset/few-lemons-drum.md                 |  5 +++++
 .../01-ai-sdk-providers/00-ai-gateway.mdx     |  6 ++++++
 .../src/gateway-language-model.test.ts        | 20 +++++++++++++++++++
 .../src/gateway-provider-options.test-d.ts    | 12 +++++++++++
 .../gateway/src/gateway-provider-options.ts   |  4 ++++
 5 files changed, 47 insertions(+)
 create mode 100644 .changeset/few-lemons-drum.md
 create mode 100644 packages/gateway/src/gateway-provider-options.test-d.ts

diff --git a/.changeset/few-lemons-drum.md b/.changeset/few-lemons-drum.md
new file mode 100644
index 000000000000..fd408b9572f2
--- /dev/null
+++ b/.changeset/few-lemons-drum.md
@@ -0,0 +1,5 @@
+---
+"@ai-sdk/gateway": patch
+---
+
+Add the `caching: 'auto'` gateway provider option to the exported type schema.
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..a99474e89f76 100644
--- a/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
+++ b/content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
@@ -800,6 +800,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 for supported models.
+
+  Example: `caching: 'auto'` lets AI Gateway apply automatic prompt caching when the routed model supports it.
+
 - **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.
diff --git a/packages/gateway/src/gateway-language-model.test.ts b/packages/gateway/src/gateway-language-model.test.ts
index 9f009bb2dd29..b641517ef7d5 100644
--- a/packages/gateway/src/gateway-language-model.test.ts
+++ b/packages/gateway/src/gateway-language-model.test.ts
@@ -1544,6 +1544,26 @@ describe('GatewayLanguageModel', () => {
       });
     });
 
+    it('should pass automatic caching option', async () => {
+      prepareJsonResponse({
+        content: { type: 'text', text: 'Test response' },
+      });
+
+      await createTestModel().doGenerate({
+        prompt: TEST_PROMPT,
+        providerOptions: {
+          gateway: {
+            caching: 'auto',
+          },
+        },
+      });
+
+      const requestBody = await server.calls[0].requestBodyJson;
+      expect(requestBody.providerOptions).toEqual({
+        gateway: { caching: 'auto' },
+      });
+    });
+
     it('should pass providerTimeouts for doGenerate', async () => {
       prepareJsonResponse({
         content: { type: 'text', text: 'Test response' },
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..962faa3daf30
--- /dev/null
+++ b/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>();
+  });
+});
diff --git a/packages/gateway/src/gateway-provider-options.ts b/packages/gateway/src/gateway-provider-options.ts
index 25ef891a80a4..382a6328f0ff 100644
--- a/packages/gateway/src/gateway-provider-options.ts
+++ b/packages/gateway/src/gateway-provider-options.ts
@@ -49,6 +49,10 @@ 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(),
+      /**
+       * Enable automatic prompt caching for supported models.
+       */
+      caching: z.literal('auto').optional(),
       /**
        * Request-scoped BYOK credentials to use instead of cached credentials.
        *