feat (providers/openai): add support for reasoning summaries (#5906) (#5909)

lgrammel · shaper · web-flow · commit 849314111c4a · 2025-04-23T10:01:11.000+02:00
Co-authored-by: Walter Korman &lt;shaper@vercel.com&gt;
diff --git a/.changeset/mean-monkeys-sip.md b/.changeset/mean-monkeys-sip.md
@@ -0,0 +1,5 @@
+---
+'@ai-sdk/openai': patch
+---
+
+feat (providers/openai): add support for reasoning summaries
diff --git a/content/providers/01-ai-sdk-providers/02-openai.mdx b/content/providers/01-ai-sdk-providers/02-openai.mdx
@@ -563,6 +563,9 @@ The following provider options are available:
 - **reasoningEffort** _'low' | 'medium' | 'high'_
   Reasoning effort for reasoning models. Defaults to `medium`. If you use `providerOptions` to set the `reasoningEffort` option, this model setting will be ignored.
 
+- **reasoningSummary** _'auto' | 'detailed'_
+  Controls whether the model returns its reasoning process. Set to `'auto'` for a condensed summary, `'detailed'` for more comprehensive reasoning. Defaults to `undefined` (no reasoning summaries). When enabled, reasoning summaries appear in the stream as events with type `'reasoning'` and in non-streaming responses within the `reasoning` field.
+
 - **strictSchemas** _boolean_
   Whether to use strict JSON schemas in tools and when generating JSON outputs. Defaults to `true`.
 
@@ -616,6 +619,53 @@ const result = await generateText({
 const sources = result.sources;
 ```
 
+#### Reasoning Summaries
+
+For reasoning models like `o3-mini`, `o3`, and `o4-mini`, you can enable reasoning summaries to see the model's thought process:
+
+```ts highlight="8-9,16"
+import { openai } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: openai.responses('o3-mini'),
+  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
+  providerOptions: {
+    openai: {
+      reasoningSummary: 'detailed', // 'auto' for condensed or 'detailed' for comprehensive
+    },
+  },
+});
+
+for await (const part of result.fullStream) {
+  if (part.type === 'reasoning') {
+    console.log(`Reasoning: ${part.textDelta}`);
+  } else if (part.type === 'text-delta') {
+    process.stdout.write(part.textDelta);
+  }
+}
+```
+
+For non-streaming calls with `generateText`, the reasoning summaries are available in the `reasoning` field of the response:
+
+```ts highlight="8-9,13"
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai.responses('o3-mini'),
+  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
+  providerOptions: {
+    openai: {
+      reasoningSummary: 'detailed',
+    },
+  },
+});
+console.log('Reasoning:', result.reasoning);
+```
+
+Learn more about reasoning summaries in the [OpenAI documentation](https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries).
+
 #### PDF support
 
 The OpenAI Responses API supports reading PDF files.
diff --git a/examples/ai-core/src/generate-text/openai-responses-reasoning-summary.ts b/examples/ai-core/src/generate-text/openai-responses-reasoning-summary.ts
@@ -0,0 +1,34 @@
+import { openai, OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import 'dotenv/config';
+
+async function main() {
+  const result = await generateText({
+    // supported: o4-mini, o3, o3-mini and o1
+    model: openai.responses('o3-mini'),
+    prompt:
+      'Tell me about the debate over Taqueria La Cumbre and El Farolito and who created the San Francisco Mission-style burrito.',
+    providerOptions: {
+      openai: {
+        // https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
+        reasoningSummary: 'auto', // 'detailed'
+      } satisfies OpenAIResponsesProviderOptions,
+    },
+  });
+
+  process.stdout.write('\x1b[34m');
+  console.log(result.reasoning);
+  process.stdout.write('\x1b[0m');
+  console.log(result.text);
+  console.log();
+  console.log('Finish reason:', result.finishReason);
+  console.log('Usage:', {
+    ...result.usage,
+    reasoningTokens: result.providerMetadata?.openai?.reasoningTokens,
+  });
+  console.log();
+  console.log('Request:', JSON.stringify(result.request, null, 2));
+  console.log('Response:', JSON.stringify(result.response, null, 2));
+}
+
+main().catch(console.error);
diff --git a/examples/ai-core/src/stream-text/openai-responses-reasoning-summary.ts b/examples/ai-core/src/stream-text/openai-responses-reasoning-summary.ts
@@ -0,0 +1,35 @@
+import 'dotenv/config';
+import { openai } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+async function main() {
+  const result = streamText({
+    // supported: o4-mini, o3, o3-mini and o1
+    model: openai.responses('o3-mini'),
+    system: 'You are a helpful assistant.',
+    prompt:
+      'Tell me about the debate over Taqueria La Cumbre and El Farolito and who created the San Francisco Mission-style burrito.',
+    providerOptions: {
+      openai: {
+        // https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
+        // reasoningSummary: 'auto', // 'detailed'
+        reasoningSummary: 'detailed',
+      },
+    },
+  });
+
+  for await (const part of result.fullStream) {
+    if (part.type === 'reasoning' && part.reasoningType === 'text') {
+      process.stdout.write('\x1b[34m' + part.text + '\x1b[0m');
+    } else if (part.type === 'text') {
+      process.stdout.write(part.text);
+    }
+  }
+
+  console.log();
+  console.log('Finish reason:', await result.finishReason);
+  console.log('Usage:', await result.usage);
+  console.log('Provider metadata:', await result.providerMetadata);
+}
+
+main().catch(console.error);
diff --git a/packages/openai/src/responses/openai-responses-language-model.test.ts b/packages/openai/src/responses/openai-responses-language-model.test.ts
@@ -50,6 +50,83 @@ describe('OpenAIResponsesLanguageModel', () => {
     'https://api.openai.com/v1/responses': {},
   });
 
+  const prepareReasoningResponse = () => {
+    server.urls['https://api.openai.com/v1/responses'].response = {
+      type: 'json-value',
+      body: {
+        id: 'resp_67c97c0203188190a025beb4a75242bc',
+        object: 'response',
+        created_at: 1741257730,
+        status: 'completed',
+        error: null,
+        incomplete_details: null,
+        input: [],
+        instructions: null,
+        max_output_tokens: null,
+        model: 'o3-mini-2025-01-31',
+        output: [
+          {
+            id: 'rs_6808709f6fcc8191ad2e2fdd784017b3',
+            type: 'reasoning',
+            summary: [
+              {
+                type: 'summary_text',
+                text: '**Exploring burrito origins**\n\nThe user is curious about the debate regarding Taqueria La Cumbre and El Farolito.',
+              },
+              {
+                type: 'summary_text',
+                text: "**Investigating burrito origins**\n\nThere's a fascinating debate about who created the Mission burrito.",
+              },
+            ],
+          },
+          {
+            id: 'msg_67c97c02656c81908e080dfdf4a03cd1',
+            type: 'message',
+            status: 'completed',
+            role: 'assistant',
+            content: [
+              {
+                type: 'output_text',
+                text: 'answer text',
+                annotations: [],
+              },
+            ],
+          },
+        ],
+        parallel_tool_calls: true,
+        previous_response_id: null,
+        reasoning: {
+          effort: 'low',
+          summary: 'auto',
+        },
+        store: true,
+        temperature: 1,
+        text: {
+          format: {
+            type: 'text',
+          },
+        },
+        tool_choice: 'auto',
+        tools: [],
+        top_p: 1,
+        truncation: 'disabled',
+        usage: {
+          input_tokens: 34,
+          input_tokens_details: {
+            cached_tokens: 0,
+          },
+          output_tokens: 538,
+          output_tokens_details: {
+            reasoning_tokens: 320,
+          },
+          total_tokens: 572,
+        },
+        user: null,
+        metadata: {},
+      },
+    };
+  };
+
   describe('doGenerate', () => {
     describe('basic text response', () => {
       beforeEach(() => {
@@ -695,6 +772,55 @@ describe('OpenAIResponsesLanguageModel', () => {
           { type: 'unsupported-setting', setting: 'stopSequences' },
         ]);
       });
+
+      it('should extract reasoning summary', async () => {
+        prepareReasoningResponse();
+
+        const result = await createModel('o3-mini').doGenerate({
+          prompt: TEST_PROMPT,
+          inputFormat: 'prompt',
+          providerOptions: {
+            openai: {
+              reasoningEffort: 'low',
+              reasoningSummary: 'auto',
+            },
+          },
+        });
+
+        expect(result.content).toMatchInlineSnapshot(`
+          [
+            {
+              "reasoningType": "text",
+              "text": "**Exploring burrito origins**
+
+          The user is curious about the debate regarding Taqueria La Cumbre and El Farolito.,**Investigating burrito origins**
+
+          There's a fascinating debate about who created the Mission burrito.",
+              "type": "reasoning",
+            },
+            {
+              "text": "answer text",
+              "type": "text",
+            },
+          ]
+        `);
+
+        expect(result.providerMetadata).toStrictEqual({
+          openai: {
+            responseId: 'resp_67c97c0203188190a025beb4a75242bc',
+            cachedPromptTokens: 0,
+            reasoningTokens: 320,
+          },
+        });
+
+        expect(await server.calls[0].requestBody).toMatchObject({
+          model: 'o3-mini',
+          reasoning: {
+            effort: 'low',
+            summary: 'auto',
+          },
+        });
+      });
     });
 
     describe('tool calls', () => {
@@ -1377,5 +1503,98 @@ describe('OpenAIResponsesLanguageModel', () => {
         ]
       `);
     });
+
+    it('should stream reasoning summary', async () => {
+      prepareReasoningResponse();
+
+      server.urls['https://api.openai.com/v1/responses'].response = {
+        type: 'stream-chunks',
+        chunks: [
+          `data:{"type":"response.created","response":{"id":"resp_67c9a81b6a048190a9ee441c5755a4e8","object":"response","created_at":1741269019,"status":"in_progress","error":null,"incomplete_details":null,"input":[],"instructions":null,"max_output_tokens":null,"model":"o3-mini-2025-01-31","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":"low","summary":"auto"},"store":true,"temperature":null,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":null,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}\n\n`,
+          `data:{"type":"response.reasoning_summary_text.delta","item_id":"rs_68082c0556348191af675cee0453109b","output_index":0,"summary_index":0,"delta":"**Exploring burrito origins**\\n\\nThe user is"}\n\n`,
+          `data:{"type":"response.reasoning_summary_text.delta","item_id":"rs_68082c0556348191af675cee0453109b","output_index":0,"summary_index":0,"delta":" curious about the debate regarding Taqueria La Cumbre and El Farolito."}\n\n`,
+          `data:{"type":"response.reasoning_summary_text.done","item_id":"rs_68082c0556348191af675cee0453109b","output_index":0,"summary_index":0,"text":"**Exploring burrito origins**\\n\\nThe user is curious about the debate regarding Taqueria La Cumbre and El Farolito."}\n\n`,
+          `data:{"type":"response.reasoning_summary_text.delta","item_id":"rs_68082c0556348191af675cee0453109b","output_index":0,"summary_index":1,"delta":"**Investigating burrito origins**\\n\\nThere's a fascinating debate about who created the Mission burrito."}\n\n`,
+          `data:{"type":"response.reasoning_summary_part.done","item_id":"rs_68082c0556348191af675cee0453109b","output_index":0,"summary_index":1,"part":{"type":"summary_text","text":"**Investigating burrito origins**\\n\\nThere's a fascinating debate about who created the Mission burrito."}}\n\n`,
+          `data:{"type":"response.output_item.added","output_index":1,"item":{"id":"msg_67c9a81dea8c8190b79651a2b3adf91e","type":"message","status":"in_progress","role":"assistant","content":[]}}\n\n`,
+          `data:{"type":"response.content_part.added","item_id":"msg_67c9a81dea8c8190b79651a2b3adf91e","output_index":1,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}\n\n`,
+          `data:{"type":"response.output_text.delta","item_id":"msg_67c9a81dea8c8190b79651a2b3adf91e","output_index":1,"content_index":0,"delta":"Taqueria La Cumbre"}\n\n`,
+          `data:{"type":"response.completed","response":{"id":"resp_67c9a81b6a048190a9ee441c5755a4e8","object":"response","created_at":1741269019,"status":"completed","error":null,"incomplete_details":null,"input":[],"instructions":null,"max_output_tokens":null,"model":"o3-mini-2025-01-31","output":[{"id":"rs_68082c0556348191af675cee0453109b","type":"reasoning","summary":[{"type":"summary_text","text":"**Exploring burrito origins**\\n\\nThe user is curious about the debate regarding Taqueria La Cumbre and El Farolito."},{"type":"summary_text","text":"**Investigating burrito origins**\\n\\nThere's a fascinating debate about who created the Mission burrito."}]},{"id":"msg_67c9a81dea8c8190b79651a2b3adf91e","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Taqueria La Cumbre","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":"low","summary":"auto"},"store":true,"temperature":null,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":null,"truncation":"disabled","usage":{"input_tokens":543,"input_tokens_details":{"cached_tokens":234},"output_tokens":478,"output_tokens_details":{"reasoning_tokens":350},"total_tokens":1021},"user":null,"metadata":{}}}\n\n`,
+        ],
+      };
+
+      const { stream } = await createModel('o3-mini').doStream({
+        inputFormat: 'prompt',
+        prompt: TEST_PROMPT,
+        providerOptions: {
+          openai: {
+            reasoningEffort: 'low',
+            reasoningSummary: 'auto',
+          },
+        },
+      });
+
+      expect(await convertReadableStreamToArray(stream)).toMatchInlineSnapshot(`
+        [
+          {
+            "type": "stream-start",
+            "warnings": [],
+          },
+          {
+            "id": "resp_67c9a81b6a048190a9ee441c5755a4e8",
+            "modelId": "o3-mini-2025-01-31",
+            "timestamp": 2025-03-06T13:50:19.000Z,
+            "type": "response-metadata",
+          },
+          {
+            "reasoningType": "text",
+            "text": "**Exploring burrito origins**
+
+        The user is",
+            "type": "reasoning",
+          },
+          {
+            "reasoningType": "text",
+            "text": " curious about the debate regarding Taqueria La Cumbre and El Farolito.",
+            "type": "reasoning",
+          },
+          {
+            "reasoningType": "text",
+            "text": "**Investigating burrito origins**
+
+        There's a fascinating debate about who created the Mission burrito.",
+            "type": "reasoning",
+          },
+          {
+            "text": "Taqueria La Cumbre",
+            "type": "text",
+          },
+          {
+            "finishReason": "stop",
+            "providerMetadata": {
+              "openai": {
+                "cachedPromptTokens": 234,
+                "reasoningTokens": 350,
+                "responseId": "resp_67c9a81b6a048190a9ee441c5755a4e8",
+              },
+            },
+            "type": "finish",
+            "usage": {
+              "inputTokens": 543,
+              "outputTokens": 478,
+            },
+          },
+        ]
+      `);
+
+      expect(await server.calls[0].requestBody).toMatchObject({
+        model: 'o3-mini',
+        reasoning: {
+          effort: 'low',
+          summary: 'auto',
+        },
+        stream: true,
+      });
+    });
   });
 });
diff --git a/packages/openai/src/responses/openai-responses-language-model.ts b/packages/openai/src/responses/openai-responses-language-model.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@ai-sdk/openai': patch
 +---
++
 +feat (providers/openai): add support for reasoning summaries