Merge

Author: jacoblee93

.changeset/brown-hounds-divide.md

@@ -0,0 +1,5 @@
+---
+"@langchain/openai": patch
+---
+
+fix(openai): Convert OpenAI responses API usage to tracing format

libs/langchain-openai/src/utils/output.ts

@@ -0,0 +1,68 @@
+import { OpenAI as OpenAIClient } from "openai";
+import {
+  StandardImageBlock,
+  StandardTextBlock,
+  UsageMetadata,
+} from "@langchain/core/messages";
+
+/**
+ * Handle multi modal response content.
+ *
+ * @param content The content of the message.
+ * @param messages The messages of the response.
+ * @returns The new content of the message.
+ */
+export function handleMultiModalOutput(
+  content: string,
+  messages: unknown
+): (StandardImageBlock | StandardTextBlock)[] | string {
+  /**
+   * Handle OpenRouter image responses
+   * @see https://openrouter.ai/docs/features/multimodal/image-generation#api-usage
+   */
+  if (
+    messages &&
+    typeof messages === "object" &&
+    "images" in messages &&
+    Array.isArray(messages.images)
+  ) {
+    const images = messages.images
+      .filter((image) => typeof image?.image_url?.url === "string")
+      .map(
+        (image) =>
+          ({
+            type: "image",
+            url: image.image_url.url as string,
+            source_type: "url",
+          } as const)
+      );
+    return [{ type: "text", text: content, source_type: "text" }, ...images];
+  }
+
+  return content;
+}
+
+export function _convertOpenAIResponsesUsageToLangChainUsage(
+  usage?: OpenAIClient.Responses.ResponseUsage
+): UsageMetadata {
+  // TODO: Remove raw OpenAI usage details in v1
+  const inputTokenDetails = {
+    ...(usage?.input_tokens_details?.cached_tokens != null && {
+      ...usage?.input_tokens_details,
+      cache_read: usage?.input_tokens_details?.cached_tokens,
+    }),
+  };
+  const outputTokenDetails = {
+    ...(usage?.output_tokens_details?.reasoning_tokens != null && {
+      ...usage?.output_tokens_details,
+      reasoning: usage?.output_tokens_details?.reasoning_tokens,
+    }),
+  };
+  return {
+    input_tokens: usage?.input_tokens ?? 0,
+    output_tokens: usage?.output_tokens ?? 0,
+    total_tokens: usage?.total_tokens ?? 0,
+    input_token_details: inputTokenDetails,
+    output_token_details: outputTokenDetails,
+  };
+}

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

@@ -99,6 +99,7 @@ import {
   getStructuredOutputMethod,
   interopZodResponseFormat,
   handleMultiModalOutput,
+  _convertOpenAIResponsesUsageToLangChainUsage,
 } from "./utils/output.js";
 import {
   _convertMessagesToOpenAIParams,
@@ -1449,7 +1450,9 @@ export class ChatOpenAIResponses<
       content,
       tool_calls,
       invalid_tool_calls,
-      usage_metadata: response.usage,
+      usage_metadata: _convertOpenAIResponsesUsageToLangChainUsage(
+        response.usage
+      ),
       additional_kwargs,
       response_metadata,
     });
@@ -1527,7 +1530,10 @@ export class ChatOpenAIResponses<
     } else if (chunk.type === "response.completed") {
       const msg = this._convertResponsesMessageToBaseMessage(chunk.response);
 
-      usage_metadata = chunk.response.usage;
+      usage_metadata = _convertOpenAIResponsesUsageToLangChainUsage(
+        chunk.response.usage
+      );
+
       if (chunk.response.text?.format?.type === "json_schema") {
         additional_kwargs.parsed ??= JSON.parse(msg.text);
       }

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

@@ -5,6 +5,7 @@ import { toJsonSchema } from "@langchain/core/utils/json_schema";
 import { load } from "@langchain/core/load";
 import { tool } from "@langchain/core/tools";
 import { ChatOpenAI } from "../chat_models.js";
+import { _convertOpenAIResponsesUsageToLangChainUsage } from "../utils/output.js";
 
 describe("ChatOpenAI", () => {
   describe("should initialize with correct values", () => {
@@ -632,4 +633,70 @@ describe("ChatOpenAI", () => {
       ]);
     });
   });
+
+  describe("Responses API usage metadata conversion", () => {
+    it("should convert OpenAI Responses usage to LangChain format with cached tokens", () => {
+      const usage = {
+        input_tokens: 100,
+        output_tokens: 50,
+        total_tokens: 150,
+        input_tokens_details: {
+          cached_tokens: 75,
+          text_tokens: 25,
+        },
+        output_tokens_details: {
+          reasoning_tokens: 10,
+          text_tokens: 40,
+        },
+      };
+
+      const result = _convertOpenAIResponsesUsageToLangChainUsage(usage as any);
+
+      expect(result).toEqual({
+        input_tokens: 100,
+        output_tokens: 50,
+        total_tokens: 150,
+        input_token_details: {
+          cached_tokens: 75,
+          text_tokens: 25,
+          cache_read: 75,
+        },
+        output_token_details: {
+          reasoning_tokens: 10,
+          text_tokens: 40,
+          reasoning: 10,
+        },
+      });
+    });
+
+    it("should handle missing usage details gracefully", () => {
+      const usage = {
+        input_tokens: 100,
+        output_tokens: 50,
+        total_tokens: 150,
+      };
+
+      const result = _convertOpenAIResponsesUsageToLangChainUsage(usage as any);
+
+      expect(result).toEqual({
+        input_tokens: 100,
+        output_tokens: 50,
+        total_tokens: 150,
+        input_token_details: {},
+        output_token_details: {},
+      });
+    });
+
+    it("should handle undefined usage", () => {
+      const result = _convertOpenAIResponsesUsageToLangChainUsage(undefined);
+
+      expect(result).toEqual({
+        input_tokens: 0,
+        output_tokens: 0,
+        total_tokens: 0,
+        input_token_details: {},
+        output_token_details: {},
+      });
+    });
+  });
 });

libs/providers/langchain-openai/src/utils/output.ts

@@ -1,3 +1,4 @@
+import { OpenAI as OpenAIClient } from "openai";
 import {
   InteropZodType,
   isZodSchemaV3,
@@ -6,7 +7,7 @@ import {
 import { toJSONSchema as toJSONSchemaV4, parse as parseV4 } from "zod/v4/core";
 import { ResponseFormatJSONSchema } from "openai/resources";
 import { zodResponseFormat } from "openai/helpers/zod";
-import { ContentBlock } from "@langchain/core/messages";
+import { ContentBlock, UsageMetadata } from "@langchain/core/messages";
 
 const SUPPORTED_METHODS = [
   "jsonSchema",
@@ -161,3 +162,28 @@ export function handleMultiModalOutput(
 
   return content;
 }
+
+export function _convertOpenAIResponsesUsageToLangChainUsage(
+  usage?: OpenAIClient.Responses.ResponseUsage
+): UsageMetadata {
+  // TODO: Remove raw OpenAI usage details in v1
+  const inputTokenDetails = {
+    ...(usage?.input_tokens_details?.cached_tokens != null && {
+      ...usage?.input_tokens_details,
+      cache_read: usage?.input_tokens_details?.cached_tokens,
+    }),
+  };
+  const outputTokenDetails = {
+    ...(usage?.output_tokens_details?.reasoning_tokens != null && {
+      ...usage?.output_tokens_details,
+      reasoning: usage?.output_tokens_details?.reasoning_tokens,
+    }),
+  };
+  return {
+    input_tokens: usage?.input_tokens ?? 0,
+    output_tokens: usage?.output_tokens ?? 0,
+    total_tokens: usage?.total_tokens ?? 0,
+    input_token_details: inputTokenDetails,
+    output_token_details: outputTokenDetails,
+  };
+}