官方拿来做性能压测的状态，正是一个"字段多、每个都带校验"的 Pydantic 模型。节选前几个字段：

class State(BaseModel):
    messages: Annotated[list, operator.add] = Field(default_factory=list)

    @field_validator("messages", mode="after")
    @classmethod
    def validate_messages(cls, v):
        if not isinstance(v, list):
            raise TypeError("messages must be a list")
        for msg in v:
            if not isinstance(msg, dict):
                raise TypeError("messages must be a list of dicts")
        return v

    trigger_events: Annotated[list, operator.add] = Field(default_factory=list)
    ...
    primary_issue_medium: Annotated[str, lambda x, y: y or x] = Field(default="email")
    autoresponse: Annotated[dict | None, lambda _, y: y] = Field(default=None)  # 总是覆盖

它的建图部分和 TypedDict 完全一样（Pydantic 只是换了 state 的"壳"）：

    builder = StateGraph(State)                 # 直接把 BaseModel 当 state
    builder.add_edge(START, "one")
    builder.add_node("one", partial(read_write, "messages", ["trigger_events", ...]))
    ...
    builder.add_conditional_edges(
        "six", lambda state: END if len(state.messages) > n else "one")   # 注意 state.messages 属性访问

D04 讲 attach_node 时见过一个 mapper，注释写着"coerce state dict to schema class (eg. pydantic model)"。它由 _pick_mapper 挑出：

def _pick_mapper(state_keys, schema):
    if state_keys == ["__root__"]:
        return None
    if isclass(schema) and (issubclass(schema, BaseModel) or is_dataclass(schema)):
        return partial(_coerce_state, schema)      # ★是 Pydantic/dataclass → 用 coerce
    return None                                    # 是 TypedDict → 不转，直接给 dict

_S = TypeVar("_S")

def _coerce_state(schema, input: dict) -> _S:
    return schema(**input)                         # ★关键：用 dict 构造模型实例

它挂载在 PregelNode 的 mapper 上（D04 见过的那段）：

            if input_schema in self.schema_to_mapper:
                mapper = self.schema_to_mapper[input_schema]      # 缓存：同 schema 复用
            else:
                mapper = _pick_mapper(input_channels, input_schema)
                self.schema_to_mapper[input_schema] = mapper
            self.nodes[key] = PregelNode(
                ...
                mapper=mapper,     # 读出 dict 后，用它 coerce 成模型实例交给你的函数
                bound=node.runnable)

LangGraph 内部经常需要动态造一个 pydantic 模型（比如为 JSON schema、输入校验）。造模型时，如果你的字段名以 _ 开头、或撞上 pydantic 的保留名（如 schema、model_*），会被自动改名：

def _remap_field_definitions(field_definitions):
    remapped = {}
    for key, value in field_definitions.items():
        if key.startswith("_") or key in _RESERVED_NAMES:      # 撞保留字/下划线开头
            if isinstance(value, FieldInfo):
                raise NotImplementedError("Remapping ... not supported if ... Field instance ...")
            type_, default_ = value
            remapped[f"private_{key}"] = (                     # ★改名成 private_xxx
                type_,
                Field(default=default_, alias=key,             # 但保留原名作为 alias
                      serialization_alias=key,
                      title=key.lstrip("_").replace("_", " ").title()))
        else:
            remapped[key] = value
    return remapped

LangGraph 用一个函数判断某个复杂类型能不能交给 pydantic 处理（决定要不要走校验路径）：

def is_supported_by_pydantic(type_) -> bool:
    if is_dataclass(type_):
        return True
    if isinstance(type_, type) and issubclass(type_, BaseModel):
        return True
    if hasattr(type_, "__orig_bases__"):
        for base in type_.__orig_bases__:
            if base is TypedDict:                    # typing_extensions.TypedDict
                return True
            elif base is typing.TypedDict:           # 标准库 typing.TypedDict
                if sys.version_info >= (3, 12):      # 仅 3.12+ pydantic 才支持
                    return True
    return False

✋ 10 分钟动手

# 1. 读真实压测状态（字段多+每个带 validator）
sed -n '14,70p' libs/langgraph/bench/pydantic_state.py

# 2. 看 coerce 引爆点：schema(**input)
sed -n '1718,1732p' libs/langgraph/langgraph/graph/state.py

# 3. 看保留字重映射 + 支持判定
sed -n '152,178p' libs/langgraph/langgraph/_internal/_pydantic.py
sed -n '252,275p' libs/langgraph/langgraph/_internal/_pydantic.py

# 4. 亲手感受"脏数据被挡在门外"
python3 -c "
from langgraph.graph import StateGraph, START, END
from pydantic import BaseModel
class S(BaseModel):
    count: int
def bad(s): return {'count': 'not-an-int'}   # 故意写脏值
g=StateGraph(S); g.add_node('n', bad); g.add_edge(START,'n'); g.add_edge('n',END)
try:
    g.compile().invoke({'count': 1})
except Exception as e:
    print(type(e).__name__, '被拦住了')   # 下一个节点读到脏值时 ValidationError
"