LangGraph Studio中AgentState未初始化引发KeyError问题求助

你遇到的KeyError核心原因是错误地同时使用@dataclass和TypedDict修饰同一个AgentState类。这两个是Python中互斥的类型定义方式：

• TypedDict用于定义字典的键类型，本质是字典结构，通过键访问（state["key"]）
• @dataclass用于创建数据类，本质是对象实例，通过属性访问（state.key）
  混用时LangGraph无法正确识别状态结构，导致默认值不生效、状态无法完整传递。

方案1：使用TypedDict+LangGraph默认值注解 #

保留字典式访问，用LangGraph的DefaultValue注解为TypedDict字段设置默认值，替换原dataclass的field：

from typing import TypedDict, Annotated, List
from langchain_core.documents import Document
from langchain_core.messages import AnyMessage
from langgraph.graph import add_messages, DefaultValue

class AgentState(TypedDict):
    """Represents the input state for the agent."""
    
    messages: Annotated[List[AnyMessage], add_messages]
    label: Annotated[dict, DefaultValue(lambda: {"type": "general", "logic": ""})]
    document_evaluation: Annotated[str, DefaultValue("GOOD")]
    documents: Annotated[List[Document], DefaultValue(list)]
    search_results: Annotated[str, DefaultValue("")]
    RAG_attempts: Annotated[int, DefaultValue(0)]

对应的节点代码无需修改（依然用state["RAG_attempts"]访问）。

方案2：使用纯Dataclass #

移除TypedDict继承，仅保留@dataclass，节点中改用属性访问：

修改后的AgentState #

from dataclasses import dataclass, field
from typing import List, Annotated
from langchain_core.documents import Document
from langchain_core.messages import AnyMessage
from langgraph.graph import add_messages

@dataclass(kw_only=True)
class AgentState:
    """Represents the input state for the agent."""
    
    messages: Annotated[List[AnyMessage], add_messages]
    label: dict = field(default_factory=lambda: {"type": "general", "logic": ""})
    document_evaluation: str = field(default="GOOD")
    documents: List[Document] = field(default_factory=list)
    search_results: str = field(default="")
    RAG_attempts: int = field(default=0)

修改后的evaluator节点 #

def evaluator(state: AgentState, *, config: RunnableConfig) -> dict:
    print("⚙️ Current Process: evaluator")
    configuration = AgentConfiguration.from_runnable_config(config)

    reval_attempts = state.RAG_attempts  # 改为属性访问

1. 编译StateGraph时确保传入正确的状态类型：

from langgraph.graph import StateGraph

graph_builder = StateGraph(AgentState)
# 添加节点、边逻辑...
graph = graph_builder.compile()

2. 初始化智能体时，若未传入完整字段，确认默认值是否生效：
   • TypedDict方式：initial_state = {"messages": [HumanMessage(content="你的问题")]}
   • Dataclass方式：initial_state = AgentState(messages=[HumanMessage(content="你的问题")])

内容的提问来源于stack exchange，提问作者Ariel Nurieli