fix(openai): respect useResponsesApi: false as explicit opt-out

When useResponsesApi is explicitly set to false, the auto-detection
logic (built-in tools, model preferences, etc.) no longer overrides
it. This fixes 404 errors when using third-party API providers with
non-standard tool types.

Closes #10428

Author: jackjin1997

.changeset/fix-use-responses-api-false.md

@@ -0,0 +1,7 @@
+---
+"@langchain/openai": patch
+---
+
+fix(openai): respect useResponsesApi: false as explicit opt-out
+
+When useResponsesApi is explicitly set to false, the auto-detection logic no longer overrides it. This fixes 404 errors when using third-party API providers with non-standard tool types.

libs/langchain-core/src/messages/block_translators/openai.ts

@@ -283,6 +283,21 @@ export function convertToV1FromResponses(
             text: String(text),
           };
         }
+      } else if (_isContentBlock(block, "reasoning")) {
+        const summary = _isArray(block.summary)
+          ? block.summary.reduce<string>((acc, item) => {
+              if (_isObject(item) && _isString(item.text)) {
+                return `${acc}${item.text}`;
+              }
+              return acc;
+            }, "")
+          : _isString(block.reasoning)
+            ? block.reasoning
+            : "";
+        yield {
+          type: "reasoning",
+          reasoning: summary,
+        };
       }
     }
     for (const toolCall of message.tool_calls ?? []) {

libs/langchain-core/src/messages/block_translators/tests/openai.test.ts

@@ -252,6 +252,71 @@ describe("openaiTranslator", () => {
       expect(message2.content).toEqual(expected);
     });
 
+    it("should translate reasoning blocks in content array to reasoning content blocks", () => {
+      const message = new AIMessage({
+        content: [
+          {
+            type: "reasoning",
+            id: "rs_abc123",
+            summary: [
+              { type: "summary_text", text: "Let me think about this..." },
+            ],
+            index: 0,
+          },
+          {
+            type: "function_call",
+            name: "task",
+            arguments: '{"description":"do something"}',
+            call_id: "call_xyz789",
+            index: 1,
+          },
+        ],
+        tool_calls: [
+          {
+            id: "call_xyz789",
+            name: "task",
+            args: { description: "do something" },
+          },
+        ],
+        response_metadata: { model_provider: "openai" },
+      });
+
+      const blocks = message.contentBlocks;
+      const reasoningBlock = blocks.find((b) => b.type === "reasoning");
+      const toolCallBlock = blocks.find((b) => b.type === "tool_call");
+
+      expect(reasoningBlock).toEqual({
+        type: "reasoning",
+        reasoning: "Let me think about this...",
+      });
+      expect(toolCallBlock).toEqual({
+        type: "tool_call",
+        id: "call_xyz789",
+        name: "task",
+        args: { description: "do something" },
+      });
+    });
+
+    it("should handle reasoning block with pre-parsed reasoning string in content array", () => {
+      const message = new AIMessage({
+        content: [
+          {
+            type: "reasoning",
+            reasoning: "Already parsed reasoning text",
+          },
+          { type: "text", text: "Hello" },
+        ],
+        response_metadata: { model_provider: "openai" },
+      });
+
+      const expected: Array<ContentBlock.Standard> = [
+        { type: "reasoning", reasoning: "Already parsed reasoning text" },
+        { type: "text", text: "Hello" },
+      ];
+
+      expect(message.contentBlocks).toEqual(expected);
+    });
+
     it("should translate responses chunk and include tool_call when args parse", () => {
       const chunk1 = new AIMessageChunk({
         content: [{ type: "text", text: "Processing ", index: 0 }],

libs/providers/langchain-openai/src/chat_models/index.ts

@@ -593,8 +593,10 @@ export class ChatOpenAI<
   CallOptions extends ChatOpenAICallOptions = ChatOpenAICallOptions,
 > extends BaseChatOpenAI<CallOptions> {
   /**
-   * Whether to use the responses API for all requests. If `false` the responses API will be used
-   * only when required in order to fulfill the request.
+   * Whether to use the responses API. When `true`, always use the Responses API.
+   * When explicitly set to `false`, never use the Responses API (even if
+   * auto-detection would otherwise enable it). When not set, the Responses API
+   * is used automatically when required to fulfill the request.
    */
   useResponsesApi = false;
 
@@ -610,6 +612,9 @@ export class ChatOpenAI<
     return [...super.callKeys, "useResponsesApi"];
   }
 
+  /** Whether the user explicitly set `useResponsesApi` to `false`. */
+  private _useResponsesApiExplicitlyDisabled = false;
+
   protected fields?: ChatOpenAIFields;
 
   constructor(model: string, fields?: Omit<ChatOpenAIFields, "model">);
@@ -622,11 +627,17 @@ export class ChatOpenAI<
     super(fields);
     this.fields = fields;
     this.useResponsesApi = fields?.useResponsesApi ?? false;
+    this._useResponsesApiExplicitlyDisabled =
+      fields?.useResponsesApi === false;
     this.responses = fields?.responses ?? new ChatOpenAIResponses(fields);
     this.completions = fields?.completions ?? new ChatOpenAICompletions(fields);
   }
 
   protected _useResponsesApi(options: this["ParsedCallOptions"] | undefined) {
+    if (this._useResponsesApiExplicitlyDisabled) {
+      return false;
+    }
+
     const usesBuiltInTools = options?.tools?.some(isBuiltInTool);
     const hasResponsesOnlyKwargs =
       options?.previous_response_id != null ||

libs/providers/langchain-openai/src/chat_models/tests/index.test.ts

@@ -1680,4 +1680,66 @@ describe("ChatOpenAI", () => {
       expect(result.text).toEqual("Foo bar");
     });
   });
+
+  describe("useResponsesApi: false should override auto-detection", () => {
+    it("should use chat completions endpoint when useResponsesApi is explicitly false, even with non-standard tool types", async () => {
+      let requestedUrl = "";
+      const mockFetch = vi.fn().mockImplementation(async (url: string) => {
+        requestedUrl = url;
+        return new Response(
+          JSON.stringify({
+            id: "chatcmpl-123",
+            object: "chat.completion",
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "test response" },
+                finish_reason: "stop",
+              },
+            ],
+            usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      });
+
+      const model = new ChatOpenAI({
+        model: "kimi-k2",
+        apiKey: "test-key",
+        useResponsesApi: false,
+        configuration: {
+          baseURL: "https://api.example.com/v1",
+          fetch: mockFetch,
+        },
+      });
+
+      await model.invoke(
+        [{ role: "user", content: "test" }],
+        {
+          tools: [
+            {
+              type: "builtin_function",
+              function: { name: "$web_search" },
+            },
+          ],
+        } as any
+      );
+
+      expect(requestedUrl).toContain("/chat/completions");
+      expect(requestedUrl).not.toContain("/responses");
+    });
+
+    it("should still auto-detect responses API when useResponsesApi is not explicitly set", () => {
+      const model = new ChatOpenAI({
+        model: "gpt-4o",
+        apiKey: "test-key",
+      });
+
+      // Access protected method for testing
+      const useResponses = (model as any)._useResponsesApi({
+        tools: [{ type: "web_search_preview" }],
+      });
+      expect(useResponses).toBe(true);
+    });
+  });
 });