langgraph[patch]: format messages in state

libs/langgraph/langgraph/graph/message.py

@@ -1,8 +1,21 @@
 import uuid
-from typing import Annotated, TypedDict, Union, cast
+import warnings
+from functools import partial
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    Literal,
+    Optional,
+    Sequence,
+    TypedDict,
+    Union,
+    cast,
+)
 
 from langchain_core.messages import (
     AnyMessage,
+    BaseMessage,
     BaseMessageChunk,
     MessageLikeRepresentation,
     RemoveMessage,
@@ -15,7 +28,32 @@
 Messages = Union[list[MessageLikeRepresentation], MessageLikeRepresentation]
 
 
-def add_messages(left: Messages, right: Messages) -> Messages:
+def _add_messages_wrapper(func: Callable) -> Callable[[Messages, Messages], Messages]:
+    def _add_messages(
+        left: Optional[Messages] = None, right: Optional[Messages] = None, **kwargs: Any
+    ) -> Union[Messages, Callable[[Messages, Messages], Messages]]:
+        if left is not None and right is not None:
+            return func(left, right, **kwargs)
+        elif left is not None or right is not None:
+            msg = (
+                f"Must specify non-null arguments for both 'left' and 'right'. Only "
+                f"received: '{'left' if left else 'right'}'."
+            )
+            raise ValueError(msg)
+        else:
+            return partial(func, **kwargs)
+
+    _add_messages.__doc__ = func.__doc__
+    return cast(Callable[[Messages, Messages], Messages], _add_messages)
+
+
+@_add_messages_wrapper
+def add_messages(
+    left: Messages,
+    right: Messages,
+    *,
+    format: Optional[Literal["langchain-openai"]] = None,
+) -> Messages:
     """Merges two lists of messages, updating existing messages by ID.
 
     By default, this ensures the state is "append-only", unless the
@@ -25,6 +63,14 @@
         left: The base list of messages.
         right: The list of messages (or single message) to merge
             into the base list.
+        format: The format to return messages in. If None then messages will be
+            returned as is. If 'langchain-openai' then messages will be returned as
+            BaseMessage objects with their contents formatted to match OpenAI message
+            format, meaning contents can be string, 'text' blocks, or 'image_url' blocks
+            and tool responses are returned as their own ToolMessages.
+
+            **REQUIREMENT**: Must have ``langchain-core>=0.3.11`` installed to use this
+            feature.
 
     Returns:
         A new list of messages with the messages from `right` merged into `left`.
@@ -58,8 +104,59 @@
         >>> graph = builder.compile()
         >>> graph.invoke({})
         {'messages': [AIMessage(content='Hello', id=...)]}
+
+        >>> from typing import Annotated
+        >>> from typing_extensions import TypedDict
+        >>> from langgraph.graph import StateGraph, add_messages
+        >>>
+        >>> class State(TypedDict):
+        ...     messages: Annotated[list, add_messages(format='langchain-openai')]
+        ...
+        >>> def chatbot_node(state: State) -> list:
+        ...     return {"messages": [
+        ...         {
+        ...             "role": "user",
+        ...             "content": [
+        ...                 {
+        ...                     "type": "text",
+        ...                     "text": "Here's an image:",
+        ...                     "cache_control": {"type": "ephemeral"},
+        ...                 },
+        ...                 {
+        ...                     "type": "image",
+        ...                     "source": {
+        ...                         "type": "base64",
+        ...                         "media_type": "image/jpeg",
+        ...                         "data": "1234",
+        ...                     },
+        ...                 },
+        ...             ]
+        ...         },
+        ...     ]}
+        >>> builder = StateGraph(State)
+        >>> builder.add_node("chatbot", chatbot_node)
+        >>> builder.set_entry_point("chatbot")
+        >>> builder.set_finish_point("chatbot")
+        >>> graph = builder.compile()
+        >>> graph.invoke({"messages": []})
+        {
+            'messages': [
+                HumanMessage(
+                    content=[
+                        {"type": "text", "text": "Here's an image:"},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": "data:image/jpeg;base64,1234"},
+                        },
+                    ],
+                ),
+            ]
+        }
         ```
 
+    ..versionchanged:: 0.2.40
+
+        Support for 'format="langchain-openai"' flag added.
     """
     # coerce to list
     if not isinstance(left, list):
@@ -100,6 +197,15 @@
 
             merged.append(m)
     merged = [m for m in merged if m.id not in ids_to_remove]
+
+    if format == "langchain-openai":
+        merged = _format_messages(merged)
+    elif format:
+        msg = f"Unrecognized {format=}. Expected one of 'langchain-openai', None."
+        raise ValueError(msg)
+    else:
+        pass
+
     return merged
 
 
@@ -156,3 +262,19 @@
 
 class MessagesState(TypedDict):
     messages: Annotated[list[AnyMessage], add_messages]
+
+
+def _format_messages(messages: Sequence[BaseMessage]) -> list[BaseMessage]:
+    try:
+        from langchain_core.messages import convert_to_openai_messages
+    except ImportError:
+        msg = (
+            "Must have langchain-core>=0.3.11 installed to use automatic message "
+            "formatting (format='langchain-openai'). Please update your langchain-core "
+            "version or remove the 'format' flag. Returning un-formatted "
+            "messages."
+        )
+        warnings.warn(msg)
+        return list(messages)
+    else:
+        return convert_to_messages(convert_to_openai_messages(messages))

libs/langgraph/langgraph/graph/state.py

@@ -762,8 +762,12 @@ def _is_field_binop(typ: Type[Any]) -> Optional[BinaryOperatorAggregate]:
         if len(meta) >= 1 and callable(meta[-1]):
             sig = signature(meta[0])
             params = list(sig.parameters.values())
-            if len(params) == 2 and all(
-                p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD) for p in params
+            if (
+                sum(
+                    p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+                    for p in params
+                )
+                == 2
             ):
                 return BinaryOperatorAggregate(typ, meta[0])
             else:

libs/langgraph/langgraph/pregel/remote.py

@@ -209,7 +209,7 @@ def _create_state_snapshot(self, state: ThreadState) -> StateSnapshot:
                     interrupts=tuple(interrupts),
                     state=self._create_state_snapshot(task["state"])
                     if task["state"]
-                    else {"configurable": task["checkpoint"]}
+                    else cast(RunnableConfig, {"configurable": task["checkpoint"]})
                     if task["checkpoint"]
                     else None,
                     result=task.get("result"),