State schema design

A LangGraph StateGraph passes a dict between nodes. If every node defines its own fields ad hoc, you end up with dictionaries that look different at every step and no compiler help when one subagent typos a key. A TypedDict fixes this. It documents the contract every node respects and gives you type hints in your editor.

agent_graph.py
python
from typing import Any, Dict, List, Optional, TypedDict


class ClaimState(TypedDict, total=False):
    """State shared across every node in the graph.

    The supervisor populates route; each subagent appends to messages
    and fills answer plus citations. Downstream turns re-use messages so
    the graph has short-term conversation memory.
    """
    messages: List[Dict[str, str]]       # [{role, content}, ...]
    user_input: str                      # latest user message
    customer_id: Optional[str]           # optional binding for SQL subagents
    route: str                           # one of: policy | billing | claims | escalation
    retrieved_docs: List[Dict[str, Any]] # policy RAG hits
    customer_record: Optional[Dict[str, Any]]
    claims_record: List[Dict[str, Any]]
    answer: str
    citations: List[str]

total=False means every field is optional. The supervisor writes route. The RAG subagent writes retrieved_docs, answer, citations. The billing subagent writes customer_record, answer. Each node only sets the fields it owns, and LangGraph merges them into the running state.

Which node writes which field

The field ownership map across supervisor and four specialist subagents.

Quiz: Quiz

Loading practice…