Figure out what we can do to help explain differences between update vs. values

[eyurtsev]

Privileged issue

• I am a LangChain maintainer, or was asked directly by a LangChain maintainer to create an issue here.

Issue Content

There can be some subtle differences when using update vs. values.

Specifically, b/c update is prior to the reducer, message coercion never takes place.

This means that update and values give different types for the messages!

One option is to use the built in message type everywhere

from typing_extensions import TypedDict, Literal
from langchain_openai import ChatOpenAI
from langgraph.graph import MessagesState, StateGraph, START, END
import uuid

def node(state):
    return {
        "messages": [{
            "role": "ai",
            "content": "hello"
        }]
    }

builder = StateGraph(MessagesState)
builder.add_node("node", node)
builder.add_edge(START, "node")
graph = builder.compile()

for update in graph.stream(
    {'messages': []},
    stream_mode='updates',
):
    print(update)

print('----')

for update in graph.stream(
    {'messages': []},
    stream_mode='values',
):
    print(update)

---

Output from update:

{'node': {'messages': [{'role': 'ai', 'content': 'hello'}]}}

Output from values:
{'messages': []}
{'messages': [AIMessage(content='hello', additional_kwargs={}, response_metadata={}, id='2f277693-67e6-4b5a-9ba0-80877b4ba6ce')]}

Note that it's AIMessage in values, but dict format in update.

While the behavior is as designed, I am not sure if it's as expected by users.