Discrepancy in docs between Python and JS

[mme]

In LangGraph Python, the recommended way to set up state is to either use MessagesState or to manually set it up. For example the Python quick start describes setting up state like this:

class State(TypedDict):
    # Messages have the type "list". The `add_messages` function
    # in the annotation defines how this state key should be updated
    # (in this case, it appends messages to the list, rather than overwriting them)
    messages: Annotated[list, add_messages]

This is how the JS quickstart recommends to set up state:

// Define the graph state
// See here for more info: https://langchain-ai.github.io/langgraphjs/how-tos/define-state/
const StateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({
    reducer: (x, y) => x.concat(y),
  })
})

These two methods behave fundamentally different, i.e.:

# pseudo code
def some_node(state):
   state["messages"].append(AIMessages("D"))
   return state

If state.messages was [A,B,C] it would be [A,B,C,D] in Python and [A,B,C,A,B,C,D] in Javascript.

In addition, the "Define State" docs do not mention MessagesAnnotation and this method to get the equivalent of the Python behavior:

export const SomeState = Annotation.Root({
  aProperty: Annotation<string>,
  ...MessagesAnnotation.spec,
});

To make it easier for users and to make LangGraph work more alike on Python and JS, I suggest these changes:

• In the docs, recommend to set up state via ...MessagesAnnotation.spec instead of reducer: (x, y) => x.concat(y)
• In the "Define State" section, mention MessagesAnnotation