feat(chatcompletions): add handling of reasoning for third party providers

Author: dkundel-openai

packages/agents-core/src/types/protocol.ts

@@ -65,6 +65,16 @@ export const InputText = SharedBase.extend({
 
 export type InputText = z.infer<typeof InputText>;
 
+export const ReasoningText = SharedBase.extend({
+  type: z.literal('reasoning_text'),
+  /**
+   * A text input for example a message from a user
+   */
+  text: z.string(),
+});
+
+export type ReasoningText = z.infer<typeof ReasoningText>;
+
 export const InputImage = SharedBase.extend({
   type: z.literal('input_image'),
 
@@ -452,6 +462,11 @@ export const ReasoningItem = SharedBase.extend({
    * The user facing representation of the reasoning. Additional information might be in the `providerData` field.
    */
   content: z.array(InputText),
+
+  /**
+   * The raw reasoning text from the model.
+   */
+  rawContent: z.array(ReasoningText).optional(),
 });
 
 export type ReasoningItem = z.infer<typeof ReasoningItem>;

packages/agents-openai/src/openaiChatCompletionsConverter.ts

@@ -182,10 +182,11 @@ export function itemsToMessages(
         });
       }
     } else if (item.type === 'reasoning') {
-      throw new UserError(
-        'Reasoning is not supported for chat completions. Got item: ' +
-          JSON.stringify(item),
-      );
+      const asst = ensureAssistantMessage();
+      // @ts-expect-error - reasoning is not supported in the official Chat Completion API spec
+      // this is handling third party providers that support reasoning
+      asst.reasoning = item.rawContent?.[0]?.text;
+      continue;
     } else if (item.type === 'hosted_tool_call') {
       if (item.name === 'file_search_call') {
         const asst = ensureAssistantMessage();

packages/agents-openai/src/openaiChatCompletionsModel.ts

@@ -35,6 +35,23 @@ import { protocol } from '@openai/agents-core';
 
 export const FAKE_ID = 'FAKE_ID';
 
+// Some Chat Completions API compatible providers return a reasoning property on the message
+// If that's the case we handle them separately
+type OpenAIMessageWithReasoning =
+  OpenAI.Chat.Completions.ChatCompletionMessage & {
+    reasoning: string;
+  };
+
+function hasReasoningContent(
+  message: OpenAI.Chat.Completions.ChatCompletionMessage,
+): message is OpenAIMessageWithReasoning {
+  return (
+    'reasoning' in message &&
+    typeof message.reasoning === 'string' &&
+    message.reasoning !== ''
+  );
+}
+
 /**
  * A model that uses (or is compatible with) OpenAI's Chat Completions API.
  */
@@ -67,7 +84,19 @@ export class OpenAIChatCompletionsModel implements Model {
     const output: protocol.OutputModelItem[] = [];
     if (response.choices && response.choices[0]) {
       const message = response.choices[0].message;
-      
+
+      if (hasReasoningContent(message)) {
+        output.push({
+          type: 'reasoning',
+          content: [],
+          rawContent: [
+            {
+              type: 'reasoning_text',
+              text: message.reasoning,
+            },
+          ],
+        });
+      }
       if (
         message.content !== undefined &&
         message.content !== null &&

packages/agents-openai/src/openaiChatCompletionsStreaming.ts

@@ -9,6 +9,7 @@ type StreamingState = {
   text_content_index_and_output: [number, protocol.OutputText] | null;
   refusal_content_index_and_output: [number, protocol.Refusal] | null;
   function_calls: Record<number, protocol.FunctionCallItem>;
+  reasoning: string;
 };
 
 export async function* convertChatCompletionsStreamToResponses(
@@ -21,6 +22,7 @@ export async function* convertChatCompletionsStreamToResponses(
     text_content_index_and_output: null,
     refusal_content_index_and_output: null,
     function_calls: {},
+    reasoning: '',
   };
 
   for await (const chunk of stream) {
@@ -64,6 +66,14 @@ export async function* convertChatCompletionsStreamToResponses(
       state.text_content_index_and_output[1].text += delta.content;
     }
 
+    if (
+      'reasoning' in delta &&
+      delta.reasoning &&
+      typeof delta.reasoning === 'string'
+    ) {
+      state.reasoning += delta.reasoning;
+    }
+
     // Handle refusals
     if ('refusal' in delta && delta.refusal) {
       if (!state.refusal_content_index_and_output) {
@@ -98,6 +108,15 @@ export async function* convertChatCompletionsStreamToResponses(
 
   // Final output message
   const outputs: protocol.OutputModelItem[] = [];
+
+  if (state.reasoning) {
+    outputs.push({
+      type: 'reasoning',
+      content: [],
+      rawContent: [{ type: 'reasoning_text', text: state.reasoning }],
+    });
+  }
+
   if (
     state.text_content_index_and_output ||
     state.refusal_content_index_and_output