Backport: feat (provider/anthropic): support passing metadata.user_id (#13783)

vercel-ai-sdk[bot] · shaper · web-flow · commit 05b8ca2b03a9 · 2026-03-23T21:23:59.000-07:00
This is an automated backport of #13782 to the release-v6.0 branch. FYI @shaper Co-authored-by: Walter Korman <shaper@vercel.com>
diff --git a/.changeset/dull-hairs-impress.md b/.changeset/dull-hairs-impress.md
@@ -0,0 +1,5 @@
+---
+"@ai-sdk/anthropic": patch
+---
+
+feat (provider/anthropic): support passing metadata.user_id
diff --git a/content/providers/01-ai-sdk-providers/05-anthropic.mdx b/content/providers/01-ai-sdk-providers/05-anthropic.mdx
@@ -146,6 +146,12 @@ The following optional provider options are available for Anthropic models:
   - `"jsonTool"`: Use a special `"json"` tool to specify the structured output format.
   - `"auto"`: Use `"outputFormat"` when supported, otherwise fall back to `"jsonTool"` (default).
 
+- `metadata` _object_
+
+  Optional. Metadata to include with the request. See the [Anthropic API documentation](https://platform.claude.com/docs/en/api/messages/create) for details.
+
+  - `userId` _string_ - An external identifier for the end-user. Should be a UUID, hash, or other opaque identifier. Must not contain PII.
+
 ### Structured Outputs and Tool Input Streaming
 
 Tool call streaming is enabled by default. You can opt out by setting the
diff --git a/content/providers/01-ai-sdk-providers/08-amazon-bedrock.mdx b/content/providers/01-ai-sdk-providers/08-amazon-bedrock.mdx
@@ -1380,6 +1380,16 @@ const { text } = await generateText({
 });
 ```
 
+### Provider Options
+
+The following optional provider options are available for Bedrock Anthropic models:
+
+- `metadata` _object_
+
+  Optional. Metadata to include with the request. See the [Anthropic API documentation](https://platform.claude.com/docs/en/api/messages/create) for details.
+
+  - `userId` _string_ - An external identifier for the end-user.
+
 ### Cache Control
 
 In the messages and message parts, you can use the `providerOptions` property to set cache control breakpoints.
diff --git a/content/providers/01-ai-sdk-providers/16-google-vertex.mdx b/content/providers/01-ai-sdk-providers/16-google-vertex.mdx
@@ -1429,6 +1429,12 @@ The following optional provider options are available for Anthropic models:
 
   Optional. See [Reasoning section](#reasoning) for more details.
 
+- `metadata` _object_
+
+  Optional. Metadata to include with the request. See the [Anthropic API documentation](https://platform.claude.com/docs/en/api/messages/create) for details.
+
+  - `userId` _string_ - An external identifier for the end-user.
+
 ### Reasoning
 
 Anthropic has reasoning support for the `claude-3-7-sonnet@20250219` model.
diff --git a/examples/ai-functions/src/generate-text/anthropic/metadata.ts b/examples/ai-functions/src/generate-text/anthropic/metadata.ts
@@ -0,0 +1,21 @@
+import {
+  anthropic,
+  type AnthropicLanguageModelOptions,
+} from '@ai-sdk/anthropic';
+import { generateText } from 'ai';
+import { run } from '../../lib/run';
+import { print } from '../../lib/print';
+
+run(async () => {
+  const result = await generateText({
+    model: anthropic('claude-sonnet-4-5'),
+    prompt: 'Invent a new holiday and describe its traditions.',
+    providerOptions: {
+      anthropic: {
+        metadata: { userId: 'user-123' },
+      } satisfies AnthropicLanguageModelOptions,
+    },
+  });
+
+  print('Content:', result.text);
+});
diff --git a/packages/anthropic/src/anthropic-messages-language-model.test.ts b/packages/anthropic/src/anthropic-messages-language-model.test.ts
@@ -4442,6 +4442,42 @@ describe('AnthropicMessagesLanguageModel', () => {
       expect(result.warnings).toStrictEqual([]);
     });
 
+    it('should pass metadata with user_id to request body', async () => {
+      prepareJsonFixtureResponse('anthropic-text');
+
+      const result = await model.doGenerate({
+        prompt: TEST_PROMPT,
+        providerOptions: {
+          anthropic: {
+            metadata: { userId: 'test-user-id' },
+          } satisfies AnthropicLanguageModelOptions,
+        },
+      });
+
+      expect(await server.calls[0].requestBodyJson).toMatchInlineSnapshot(`
+        {
+          "max_tokens": 4096,
+          "messages": [
+            {
+              "content": [
+                {
+                  "text": "Hello",
+                  "type": "text",
+                },
+              ],
+              "role": "user",
+            },
+          ],
+          "metadata": {
+            "user_id": "test-user-id",
+          },
+          "model": "claude-3-haiku-20240307",
+        }
+      `);
+
+      expect(result.warnings).toStrictEqual([]);
+    });
+
     describe('context management', () => {
       it('should send context_management in request body', async () => {
         prepareJsonFixtureResponse('anthropic-text');
diff --git a/packages/anthropic/src/anthropic-messages-language-model.ts b/packages/anthropic/src/anthropic-messages-language-model.ts
@@ -388,6 +388,9 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       ...(anthropicOptions?.cacheControl && {
         cache_control: anthropicOptions.cacheControl,
       }),
+      ...(anthropicOptions?.metadata?.userId != null && {
+        metadata: { user_id: anthropicOptions.metadata.userId },
+      }),
 
       // mcp servers:
       ...(anthropicOptions?.mcpServers &&
diff --git a/packages/anthropic/src/anthropic-messages-options.ts b/packages/anthropic/src/anthropic-messages-options.ts
@@ -112,6 +112,23 @@ export const anthropicLanguageModelOptions = z.object({
     })
     .optional(),
 
+  /**
+   * Metadata to include with the request.
+   *
+   * See https://platform.claude.com/docs/en/api/messages/create for details.
+   */
+  metadata: z
+    .object({
+      /**
+       * An external identifier for the user associated with the request.
+       *
+       * Should be a UUID, hash value, or other opaque identifier.
+       * Must not contain PII (name, email, phone number, etc.).
+       */
+      userId: z.string().optional(),
+    })
+    .optional(),
+
   /**
    * MCP servers to be utilized in this request.
    */

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@ai-sdk/anthropic": patch
 +---
++
 +feat (provider/anthropic): support passing metadata.user_id