docs: Add warning about state schema definition in LangGraph #1881
Conversation
When extending state schemas like AgentState or MessagesState, custom fields must be explicitly defined in the TypedDict, otherwise they will be silently ignored. This warning clarifies the proper way to extend state schemas with custom fields and references issue #34108. The warning is placed in the Schema section of the Graph API documentation with clear examples of incorrect vs correct usage.
github-actions
bot
added
langgraph
There was a problem hiding this comment.
Pull request overview
This PR adds a warning callout to the Graph API documentation to help developers avoid a common pitfall when extending LangGraph state schemas. The warning addresses issue #34108 by documenting that custom fields must be explicitly defined using TypedDict when extending state classes like AgentState or MessagesState, otherwise they will be silently ignored.
Key changes:
- Added a warning section explaining the requirement to use TypedDict for extending state schemas
- Included code examples showing both incorrect and correct approaches
- Referenced the related GitHub issue for additional context
| ### Defining All State Keys | ||
|
|
||
| When extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph. | ||
|
|
There was a problem hiding this comment.
The heading "Defining All State Keys" is positioned inside a warning callout. According to Mintlify documentation patterns and the examples found in this repository (e.g., line 58 uses <Warning> without a heading inside), warning callouts typically don't include headings. The heading structure could interfere with the document's table of contents and navigation.
Consider removing the heading and incorporating that information into the opening sentence of the warning, or restructure this as a regular section with the warning callout inside it.
| ### Defining All State Keys | |
| When extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph. | |
| When defining all state keys: when extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph. |
| :::warning | ||
| ### Defining All State Keys | ||
|
|
||
| When extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph. | ||
|
|
||
| For example: | ||
|
|
||
| ```python | ||
| from langgraph.graph import MessagesState | ||
|
|
||
| # ✗ WRONG - custom fields are not defined in the schema | ||
| class WrongState(MessagesState): | ||
| authenticated: bool # This field will be silently ignored! | ||
| user_id: str # This field will be silently ignored! | ||
|
|
||
| # ✓ CORRECT - use TypedDict to properly extend the schema | ||
| from typing_extensions import TypedDict | ||
|
|
||
| class CorrectState(MessagesState, TypedDict): | ||
| authenticated: bool # Properly defined | ||
| user_id: str # Properly defined | ||
| ``` | ||
|
|
||
| This applies to any custom state you create by extending existing state schemas. Always use `TypedDict` to ensure your custom fields are properly declared and will be persisted in your graph state. | ||
|
|
||
| See [#34108](https://github.com/langchain-ai/langgraph/issues/34108) for more context. | ||
| ::: |
There was a problem hiding this comment.
This warning callout is only wrapped in Python-specific language fences (:::python would be needed), but it's placed outside of any language-specific block. Since this warning discusses Python-specific concepts (TypedDict, MessagesState), it should either be:
- Wrapped in :::python / ::: fences to indicate it's Python-specific, or
- Include a JavaScript/TypeScript equivalent example if this issue also applies to JavaScript/TypeScript users.
Looking at the context, the Schema section has both :::python and :::js blocks (lines 74-84), so this warning should follow the same pattern to maintain consistency with the documentation structure.
|
|
||
| This applies to any custom state you create by extending existing state schemas. Always use `TypedDict` to ensure your custom fields are properly declared and will be persisted in your graph state. | ||
|
|
||
| See [#34108](https://github.com/langchain-ai/langgraph/issues/34108) for more context. |
There was a problem hiding this comment.
The GitHub issue reference uses the wrong repository. The link references github.com/langchain-ai/langgraph/issues/34108, but according to the PR description, this should reference langchain-ai/langchain#34108. The issue number suggests this is in the langchain repository, not langgraph.
The link should be updated to reference the correct repository or use a full URL format if cross-repository references are needed.
| See [#34108](https://github.com/langchain-ai/langgraph/issues/34108) for more context. | |
| See [#34108](https://github.com/langchain-ai/langchain/issues/34108) for more context. |
1 participant
This PR implements the suggestion from langchain-ai/langchain#34230 to add documentation about the importance of properly defining state schema when extending existing state classes.
Changes
Why This Matters
When extending state schemas like
AgentStateorMessagesState, developers often forget to use TypedDict to extend the schema. This silently results in custom fields being ignored in the graph state, leading to confusing bugs. This warning helps prevent this issue.Closes langchain-ai/langchain#34108 (documentation)