From 23c3fa65d4cd6769ec6eee5459efc93e1d66762e Mon Sep 17 00:00:00 2001
From: Mason Daugherty <mason@langchain.dev>
Date: Mon, 11 Aug 2025 09:16:16 -0400
Subject: [PATCH] feat(docs): enhance `ResponseMetadata` documentation with
 provider field usage notes (#32472)

---
 libs/core/langchain_core/v1/messages.py          | 16 ++++++++++++++++
 .../runnables/__snapshots__/test_graph.ambr      | 16 ++++++++++++++++
 .../runnables/__snapshots__/test_runnable.ambr   | 16 ++++++++++++++++
 3 files changed, 48 insertions(+)

diff --git a/libs/core/langchain_core/v1/messages.py b/libs/core/langchain_core/v1/messages.py
index e8fcca0f506..d198e1e028f 100644
--- a/libs/core/langchain_core/v1/messages.py
+++ b/libs/core/langchain_core/v1/messages.py
@@ -110,6 +110,22 @@ class ResponseMetadata(TypedDict, total=False):
     The common fields (``model_provider``, ``model_name``) provide a baseline
     contract while preserving flexibility for provider innovations.
 
+    .. note::
+        Not all providers will return the metadata required by this class. In this case,
+        it is acceptable to inject these fields with values at invocation.
+
+        For instance, requests to OpenAI's responses API will not return a provider
+        field in the raw response, as it can be inferred that by making the request, the
+        provider responding is OpenAI. In this case, it is safe to set the
+        ``model_provider`` field to ``'openai'`` when creating the message.
+
+        On the other hand, ``model_name`` is often returned, and in such cases it is
+        expected that you populate this field with the unmodified model name (such as
+        ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+        model name should you artifically set this field - in which case, the value
+        should be set to the ``model`` or ``model_name`` parameter passed in during
+        invocation.
+
     """
 
     model_provider: str
diff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr
index 56df846c956..99369d64521 100644
--- a/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr
+++ b/libs/core/tests/unit_tests/runnables/__snapshots__/test_graph.ambr
@@ -1450,6 +1450,22 @@
                 
                 The common fields (``model_provider``, ``model_name``) provide a baseline
                 contract while preserving flexibility for provider innovations.
+                
+                .. note::
+                    Not all providers will return the metadata required by this class. In this case,
+                    it is acceptable to inject these fields with values at invocation.
+                
+                    For instance, requests to OpenAI's responses API will not return a provider
+                    field in the raw response, as it can be inferred that by making the request, the
+                    provider responding is OpenAI. In this case, it is safe to set the
+                    ``model_provider`` field to ``'openai'`` when creating the message.
+                
+                    On the other hand, ``model_name`` is often returned, and in such cases it is
+                    expected that you populate this field with the unmodified model name (such as
+                    ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+                    model name should you artifically set this field - in which case, the value
+                    should be set to the ``model`` or ``model_name`` parameter passed in during
+                    invocation.
               ''',
               'properties': dict({
                 'model_name': dict({
diff --git a/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr b/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr
index 7a2c7b40621..b597633170d 100644
--- a/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr
+++ b/libs/core/tests/unit_tests/runnables/__snapshots__/test_runnable.ambr
@@ -10455,6 +10455,22 @@
           
           The common fields (``model_provider``, ``model_name``) provide a baseline
           contract while preserving flexibility for provider innovations.
+          
+          .. note::
+              Not all providers will return the metadata required by this class. In this case,
+              it is acceptable to inject these fields with values at invocation.
+          
+              For instance, requests to OpenAI's responses API will not return a provider
+              field in the raw response, as it can be inferred that by making the request, the
+              provider responding is OpenAI. In this case, it is safe to set the
+              ``model_provider`` field to ``'openai'`` when creating the message.
+          
+              On the other hand, ``model_name`` is often returned, and in such cases it is
+              expected that you populate this field with the unmodified model name (such as
+              ``'o1-2024-12-17'``). Only in situations where the provider does not return a
+              model name should you artifically set this field - in which case, the value
+              should be set to the ``model`` or ``model_name`` parameter passed in during
+              invocation.
         ''',
         'properties': dict({
           'model_name': dict({