fix(openai): Convert OpenAI responses API usage to tracing format (langchain-ai#9145)

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/chat_models.ts

@@ -107,7 +107,10 @@ import {
   ResponsesTool,
   ResponsesToolChoice,
 } from "./utils/tools.js";
-import { handleMultiModalOutput } from "./utils/output.js";
+import {
+  _convertOpenAIResponsesUsageToLangChainUsage,
+  handleMultiModalOutput,
+} from "./utils/output.js";
 
 const _FUNCTION_CALL_IDS_MAP_KEY = "__openai_function_call_ids__";
 
@@ -1755,7 +1758,9 @@ export class ChatOpenAIResponses<
       content,
       tool_calls,
       invalid_tool_calls,
-      usage_metadata: response.usage,
+      usage_metadata: _convertOpenAIResponsesUsageToLangChainUsage(
+        response.usage
+      ),
       additional_kwargs,
       response_metadata,
     });
@@ -1831,7 +1836,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/langchain-openai/src/tests/chat_models.test.ts

@@ -5,6 +5,7 @@ import { load } from "@langchain/core/load";
 import { it, expect, describe, beforeAll, afterAll, jest } from "@jest/globals";
 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", () => {
@@ -657,4 +658,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/langchain-openai/src/utils/output.ts

@@ -1,6 +1,8 @@
+import { OpenAI as OpenAIClient } from "openai";
 import {
   StandardImageBlock,
   StandardTextBlock,
+  UsageMetadata,
 } from "@langchain/core/messages";
 
 /**
@@ -39,3 +41,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,
+  };
+}