MessagesAnnotation is a predefined state schema in LangGraph that structures the agent's state around a messages key using the add_messages reducer. It is the recommended shape because it automatically handles message appending, deduplication, and ordering, making it ideal for conversational agents where the message list grows over time.
MessagesAnnotation is a convenience type (a TypedDict with an Annotated field) that tells LangGraph to treat the messages key as a list of BaseMessage objects and to use the add_messages reducer to update it. This reducer merges new messages into the existing list by matching on message IDs: if a message with the same ID already exists, it is replaced; otherwise, it is appended. This prevents duplicates and allows updates. It is the recommended shape because it simplifies state management for agent graphs that rely on a growing conversation history, ensuring that message order is preserved and that tool call round trips work correctly.