feat,docs(openai,azure):provide Responses API providerMetadata types at the provider-specific metadata / reasoning part metadata (#12010)

## Background

The Responses API attaches provider-specific metadata to messages and
reasoning parts, but until now there were no exported, typed helpers for
accessing this metadata in a type-safe way from client code.

As a result, users had to rely on untyped or loosely typed access to
`providerMetadata`, especially when working with response IDs, logprobs,
service tier information, or reasoning-related metadata.

## Summary

This PR adds and documents typed providerMetadata helpers for the
Responses API at the message and reasoning level.

- Export new providerMetadata types for both OpenAI and Azure:
  - `OpenaiResponsesProviderMetadata`
  - `OpenaiResponsesReasoningProviderMetadata`
  - `AzureResponsesProviderMetadata`
  - `AzureResponsesReasoningProviderMetadata`
- Ensure providerMetadata construction is type-checked internally using
`satisfies`.
- Update OpenAI and Azure provider documentation with:
  - Typed examples for accessing message-level providerMetadata.
  - New sections describing typed providerMetadata in reasoning parts.
- Update examples to demonstrate practical usage of the new types
(e.g. `responseId`, `logprobs`, `serviceTier`,
`reasoningEncryptedContent`).

No behavior changes are introduced; this change improves type safety,
documentation, and developer ergonomics.

## Manual Verification

### examples in `examples/ai-functions`
Edited for add types and run tests.
- pnpm tsx src/generate-text/azure-reasoning-encrypted-content.ts
- pnpm tsx src/generate-text/azure-reasoning.ts
- pnpm tsx src/generate-text/openai-logprobs.ts
- pnpm tsx src/generate-text/openai-reasoning-encrypted-content.ts
- pnpm tsx src/generate-text/openai-reasoning.ts
- pnpm tsx src/generate-text/openai-responses-previous-response-id.ts
- pnpm tsx src/stream-text/azure-fullstream-logprobs.ts
- pnpm tsx src/stream-text/azure-reasoning-encrypted-content.ts
- pnpm tsx src/stream-text/azure-reasoning.ts
- pnpm tsx src/stream-text/openai-fullstream-logprobs.ts
- pnpm tsx src/stream-text/openai-reasoning-encrypted-content.ts
- pnpm tsx src/stream-text/openai-reasoning.ts
- pnpm tsx src/stream-text/openai-responses-service-tier.ts

### examples in `examples/next-openai`
Edited for add types and run tests.
- http://localhost:3000/chat-openai-previous-response-id

## Related Issues

#10266

---------

Co-authored-by: tsuzaki430 <tsuzaki430@users.noreply.github.com>

Author: tsuzaki430

.changeset/afraid-readers-begin.md

@@ -0,0 +1,12 @@
+---
+'@ai-sdk/openai': patch
+'@ai-sdk/azure': patch
+---
+
+Provide Responses API providerMetadata types at the message / reasoning level.
+
+- Export the following types for use in client code:
+  - `OpenaiResponsesProviderMetadata`
+  - `OpenaiResponsesReasoningProviderMetadata`
+  - `AzureResponsesProviderMetadata`
+  - `AzureResponsesReasoningProviderMetadata`

content/providers/01-ai-sdk-providers/03-openai.mdx

@@ -255,24 +255,34 @@ The following provider options are available:
 
 The OpenAI responses provider also returns provider-specific metadata:
 
+For Responses models, you can type this metadata using `OpenaiResponsesProviderMetadata`:
+
 ```ts
-const { providerMetadata } = await generateText({
-  model: openai.responses('gpt-5'),
+import { openai, type OpenaiResponsesProviderMetadata } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai('gpt-5'),
 });
 
-const openaiMetadata = providerMetadata?.openai;
-```
+const providerMetadata = result.providerMetadata as
+  | OpenaiResponsesProviderMetadata
+  | undefined;
 
-The following OpenAI-specific metadata is returned:
+const { responseId, logprobs, serviceTier } = providerMetadata?.openai ?? {};
 
-- **responseId** _string_
-  The ID of the response. Can be used to continue a conversation.
+// responseId can be used to continue a conversation (previousResponseId).
+console.log(responseId);
+```
 
-- **cachedPromptTokens** _number_
-  The number of prompt tokens that were a cache hit.
+The following OpenAI-specific metadata may be returned:
 
-- **reasoningTokens** _number_
-  The number of reasoning tokens that the model generated.
+- **responseId** _string | null | undefined_
+  The ID of the response. Can be used to continue a conversation.
+- **logprobs** _(optional)_
+  Log probabilities of output tokens (when enabled).
+- **serviceTier** _(optional)_
+  Service tier information returned by the API.
 
 #### Reasoning Output
 
@@ -929,6 +939,52 @@ for (const part of result.content) {
   API.
 </Note>
 
+#### Typed providerMetadata in Reasoning Parts
+
+When using the OpenAI Responses API, reasoning output parts can include provider metadata.
+To handle this metadata in a type-safe way, use `OpenaiResponsesReasoningProviderMetadata`.
+
+For reasoning parts, when `part.type === 'reasoning'`, the `providerMetadata` is provided in the form of `OpenaiResponsesReasoningProviderMetadata`.
+
+This metadata includes the following fields:
+
+- `itemId`  
+  The ID of the reasoning item in the Responses API.
+- `reasoningEncryptedContent` (optional)  
+  Encrypted reasoning content (only returned when requested via `include: ['reasoning.encrypted_content']`).
+
+```ts
+import {
+  openai,
+  type OpenaiResponsesReasoningProviderMetadata,
+  type OpenAIResponsesProviderOptions,
+} from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai('gpt-5'),
+  prompt: 'How many "r"s are in the word "strawberry"?',
+  providerOptions: {
+    openai: {
+      store: false,
+      include: ['reasoning.encrypted_content'],
+    } satisfies OpenAIResponsesProviderOptions,
+  },
+});
+
+for (const part of result.content) {
+  if (part.type === 'reasoning') {
+    const providerMetadata = part.providerMetadata as
+      | OpenaiResponsesReasoningProviderMetadata
+      | undefined;
+
+    const { itemId, reasoningEncryptedContent } =
+      providerMetadata?.openai ?? {};
+    console.log(itemId, reasoningEncryptedContent);
+  }
+}
+```
+
 #### Typed providerMetadata in Source Document Parts
 
 For source document parts, when `part.type === 'source'` and `sourceType === 'document'`, the `providerMetadata` is provided as `OpenaiResponsesSourceDocumentProviderMetadata`.

content/providers/01-ai-sdk-providers/04-azure.mdx

@@ -322,24 +322,34 @@ The following provider options are available:
 
 The Azure OpenAI provider also returns provider-specific metadata:
 
+For Responses models (`azure(deploymentName)`), you can type this metadata using `AzureResponsesProviderMetadata`:
+
 ```ts
-const { providerMetadata } = await generateText({
+import { azure, type AzureResponsesProviderMetadata } from '@ai-sdk/azure';
+import { generateText } from 'ai';
+
+const result = await generateText({
   model: azure('your-deployment-name'),
 });
 
-const openaiMetadata = providerMetadata?.openai;
-```
+const providerMetadata = result.providerMetadata as
+  | AzureResponsesProviderMetadata
+  | undefined;
 
-The following OpenAI-specific metadata is returned:
+const { responseId, logprobs, serviceTier } = providerMetadata?.azure ?? {};
 
-- **responseId** _string_
-  The ID of the response. Can be used to continue a conversation.
+// responseId can be used to continue a conversation (previousResponseId).
+console.log(responseId);
+```
 
-- **cachedPromptTokens** _number_
-  The number of prompt tokens that were a cache hit.
+The following Azure-specific metadata may be returned:
 
-- **reasoningTokens** _number_
-  The number of reasoning tokens that the model generated.
+- **responseId** _string | null | undefined_
+  The ID of the response. Can be used to continue a conversation.
+- **logprobs** _(optional)_
+  Log probabilities of output tokens (when enabled).
+- **serviceTier** _(optional)_
+  Service tier information returned by the API.
 
 <Note>
   The providerMetadata is only returned with the default responses API, and is
@@ -652,6 +662,51 @@ for (const part of result.content) {
   API.
 </Note>
 
+#### Typed providerMetadata in Reasoning Parts
+
+When using the Azure OpenAI Responses API, reasoning output parts can include provider metadata.
+To handle this metadata in a type-safe way, use `AzureResponsesReasoningProviderMetadata`.
+
+For reasoning parts, when `part.type === 'reasoning'`, the `providerMetadata` is provided in the form of `AzureResponsesReasoningProviderMetadata`.
+
+This metadata includes the following fields:
+
+- `itemId`  
+  The ID of the reasoning item in the Responses API.
+- `reasoningEncryptedContent` (optional)  
+  Encrypted reasoning content (only returned when requested via `include: ['reasoning.encrypted_content']`).
+
+```ts
+import {
+  azure,
+  type AzureResponsesReasoningProviderMetadata,
+  type OpenAIResponsesProviderOptions,
+} from '@ai-sdk/azure';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: azure('your-deployment-name'),
+  prompt: 'How many "r"s are in the word "strawberry"?',
+  providerOptions: {
+    azure: {
+      store: false,
+      include: ['reasoning.encrypted_content'],
+    } satisfies OpenAIResponsesProviderOptions,
+  },
+});
+
+for (const part of result.content) {
+  if (part.type === 'reasoning') {
+    const providerMetadata = part.providerMetadata as
+      | AzureResponsesReasoningProviderMetadata
+      | undefined;
+
+    const { itemId, reasoningEncryptedContent } = providerMetadata?.azure ?? {};
+    console.log(itemId, reasoningEncryptedContent);
+  }
+}
+```
+
 #### Typed providerMetadata in Source Document Parts
 
 For source document parts, when `part.type === 'source'` and `sourceType === 'document'`, the `providerMetadata` is provided as `AzureResponsesSourceDocumentProviderMetadata`.

examples/ai-functions/src/generate-text/azure-reasoning-encrypted-content.ts

@@ -1,58 +1,50 @@
-import { generateText, stepCountIs, tool } from 'ai';
-import { z } from 'zod';
+import { generateText } from 'ai';
 import { run } from '../lib/run';
-import { azure } from '@ai-sdk/azure';
+import {
+  azure,
+  AzureResponsesReasoningProviderMetadata,
+  OpenAIResponsesProviderOptions,
+} from '@ai-sdk/azure';
 
 run(async () => {
   const result = await generateText({
-    model: azure.responses('gpt-5.1-codex-max'),
-    tools: {
-      calculator: tool({
-        description:
-          'A minimal calculator for basic arithmetic. Call it once per step.',
-        inputSchema: z.object({
-          a: z.number().describe('First operand.'),
-          b: z.number().describe('Second operand.'),
-          op: z
-            .enum(['add', 'subtract', 'multiply', 'divide'])
-            .default('add')
-            .describe('Arithmetic operation to perform.'),
-        }),
-        execute: async ({ a, b, op }) => {
-          switch (op) {
-            case 'add':
-              return { result: a + b };
-            case 'subtract':
-              return { result: a - b };
-            case 'multiply':
-              return { result: a * b };
-            case 'divide':
-              if (b === 0) {
-                return 'Cannot divide by zero.';
-              }
-              return { result: a / b };
-          }
-        },
-      }),
-    },
-    stopWhen: stepCountIs(20),
+    model: azure('gpt-5'),
+    prompt: 'How many "r"s are in the word "strawberry"?',
     providerOptions: {
       azure: {
-        reasoningEffort: 'high',
-        maxCompletionTokens: 32_000,
+        reasoningEffort: 'low',
+        reasoningSummary: 'detailed',
         store: false,
-        include: ['reasoning.encrypted_content'],
-        reasoningSummary: 'auto',
-      },
+        include: ['reasoning.encrypted_content'], // Use encrypted reasoning items
+      } satisfies OpenAIResponsesProviderOptions,
     },
-    messages: [
-      {
-        role: 'user',
-        content:
-          'Use the calculator tool to add 12 and 7, then multiply that sum by 3 then multiply by 10. Call the tool separately for each arithmetic step and only 1 tool call per step and report the final result.',
-      },
-    ],
   });
 
-  console.dir(result.response, { depth: Infinity });
+  for (const part of result.content) {
+    switch (part.type) {
+      case 'reasoning': {
+        console.log('--- reasoning ---');
+        console.log(part.text);
+        const providerMetadata = part.providerMetadata as
+          | AzureResponsesReasoningProviderMetadata
+          | undefined;
+        if (!providerMetadata) break;
+        const {
+          azure: { itemId, reasoningEncryptedContent },
+        } = providerMetadata;
+        console.log(`itemId: ${itemId}`);
+
+        // In the Responses API, explicitly setting store to false opts out of both conversation history and reasoning token storage.
+        // As a result, reasoningEncryptedContent is used to restore the reasoning tokens for the conversation history.
+        console.log(`reasoningEncryptedContent: ${reasoningEncryptedContent}`);
+        break;
+      }
+      case 'text': {
+        console.log('--- text ---');
+        console.log(part.text);
+        break;
+      }
+    }
+    console.log();
+  }
 });

examples/ai-functions/src/generate-text/azure-reasoning.ts

@@ -0,0 +1,48 @@
+import {
+  azure,
+  AzureResponsesReasoningProviderMetadata,
+  OpenAIResponsesProviderOptions,
+} from '@ai-sdk/azure';
+import { generateText } from 'ai';
+import { run } from '../lib/run';
+
+run(async () => {
+  const result = await generateText({
+    model: azure('gpt-5'),
+    prompt: 'How many "r"s are in the word "strawberry"?',
+    providerOptions: {
+      azure: {
+        reasoningEffort: 'low',
+        reasoningSummary: 'detailed',
+      } satisfies OpenAIResponsesProviderOptions,
+    },
+  });
+
+  for (const part of result.content) {
+    switch (part.type) {
+      case 'reasoning': {
+        console.log('--- reasoning ---');
+        console.log(part.text);
+        const providerMetadata = part.providerMetadata as
+          | AzureResponsesReasoningProviderMetadata
+          | undefined;
+        if (!providerMetadata) break;
+        const {
+          azure: { itemId, reasoningEncryptedContent },
+        } = providerMetadata;
+        console.log(`itemId: ${itemId}`);
+
+        // In the Responses API, store is set to true by default, so conversation history is cached.
+        // The reasoning tokens from that interaction are also cached, and as a result, reasoningEncryptedContent returns null.
+        console.log(`reasoningEncryptedContent: ${reasoningEncryptedContent}`);
+        break;
+      }
+      case 'text': {
+        console.log('--- text ---');
+        console.log(part.text);
+        break;
+      }
+    }
+    console.log();
+  }
+});

examples/ai-functions/src/generate-text/openai-logprobs.ts

@@ -1,10 +1,10 @@
-import { openai } from '@ai-sdk/openai';
+import { openai, OpenaiResponsesProviderMetadata } from '@ai-sdk/openai';
 import { generateText } from 'ai';
 import { run } from '../lib/run';
 
 run(async () => {
   const result = await generateText({
-    model: openai('gpt-3.5-turbo'),
+    model: openai('gpt-4.1-mini'),
     prompt: 'Invent a new holiday and describe its traditions.',
     providerOptions: {
       openai: {
@@ -13,5 +13,27 @@ run(async () => {
     },
   });
 
-  console.log(result.providerMetadata?.openai.logprobs);
+  const providerMetadata = result.providerMetadata as
+    | OpenaiResponsesProviderMetadata
+    | undefined;
+  if (!providerMetadata) return;
+  const {
+    openai: { responseId, logprobs, serviceTier },
+  } = providerMetadata;
+  responseId && console.log(`responseId: ${responseId}`);
+  serviceTier && console.log(`serviceTier: ${serviceTier}`);
+  if (!logprobs) return;
+  let printed = 0;
+  for (const logprob of logprobs) {
+    if (logprob != null) {
+      for (const token_info of logprob) {
+        console.log(
+          `token: ${token_info.token} , logprob: ${token_info.logprob} , top_logprobs: ${JSON.stringify(token_info.top_logprobs)}`,
+        );
+      }
+      console.log();
+      printed++;
+    }
+    if (printed >= 5) break; // Output only the first 5 entries to prevent excessive logging
+  }
 });