How to define and update state in LangGraph: TypedDict vs Pydantic

Getting Started with LangGraph State: TypedDict vs. Pydantic

Welcome! If you’re building smart AI agents with LangGraph, you know how important it is for your agent to remember things. This “memory” is what we call state. Managing this state properly helps your agent make sense of long conversations or complex tasks.

In this guide, we’re going to explore how to effectively define and update state in LangGraph. We will look at two main tools: Python’s built-in TypedDict and the powerful Pydantic library. By the end, you’ll understand which one is best for your projects to LangGraph define state TypedDict Pydantic efficiently.

What is State in LangGraph?

Imagine your LangGraph agent as a chef following a recipe. The “state” is like the chef’s mental notes about what ingredients are in the bowl, what steps have been completed, and what to do next. It’s the information that passes between different steps of your agent.

This state is a dictionary, a collection of key-value pairs, that your agent uses to keep track of its progress. Each time a step in your agent’s workflow finishes, it can update this state. This updated state is then handed over to the next step, allowing for complex, multi-turn interactions. For a deeper dive into multi-step agents, check out LangGraph StateGraph: Building a Multi-Step AI Agent.

Why Define Your LangGraph State?

Defining your LangGraph state is like writing down a clear plan for your chef’s notes. When you clearly tell LangGraph what kind of information your state should hold, you make your agent smarter and more reliable. This is also known as creating a LangGraph state schema.

A defined schema helps prevent mistakes because you know exactly what kind of data to expect at each step. It makes your code easier to read and understand for anyone working on it. Plus, it helps with debugging, as you can quickly see if the state contains the right information.

By defining your state, you ensure your agent consistently handles information correctly. This leads to more robust and predictable AI agent behavior. Now, let’s look at how TypedDict and Pydantic can help us achieve this clear definition.

Defining LangGraph State with TypedDict

TypedDict is a special type from Python’s typing module. It lets you create dictionaries where you specify the type of value for each key. Think of it as a blueprint for your dictionary.

It’s straightforward to use and comes built-in with Python, meaning you don’t need to install anything extra. For simpler projects or when you just need basic type checking, TypedDict LangGraph state definition is a great choice.

How to Use TypedDict for LangGraph State

To use TypedDict, you simply define a new class that inherits from TypedDict. Inside this class, you list the keys your state will have and their corresponding Python types. This provides clear instructions on what your state should look like.

Let’s imagine our agent needs to track the user’s question, the tools it has used, and the final answer. We can define this using TypedDict. It’s a quick way to get started with a structured LangGraph define state TypedDict Pydantic approach.

from typing import List, TypedDict, Optional

class AgentState(TypedDict):
    """
    Represents the state of our agent.
    - user_question: The original question from the user.
    - tool_output: List of outputs from tool calls.
    - final_answer: The ultimate answer generated by the agent.
    - num_iterations: How many steps the agent has taken.
    """
    user_question: str
    tool_output: List[str]
    final_answer: Optional[str]
    num_iterations: int

In this example, AgentState tells us that user_question must be a string, tool_output a list of strings, final_answer an optional string (meaning it might not be there initially), and num_iterations an integer. This simple definition makes your state structure immediately clear.

Updating State with TypedDict

When you use TypedDict, updating the state means returning a new dictionary that contains changes. LangGraph then merges these changes into the current state. You can update individual fields or even add new ones if your TypedDict allows it (e.g., if you used total=False for extra fields, though less common for strict state).

You typically return a dictionary where keys match those in your TypedDict. For example, if a node in your graph generates a tool output, it will return a dictionary like {"tool_output": ["Tool result text"]}. LangGraph automatically knows how to combine these updates.

def update_tool_output(state: AgentState) -> dict:
    """A dummy function to simulate a tool call updating the state."""
    current_tool_output = state.get("tool_output", [])
    new_output = "Processed data from tool X."
    updated_tool_output = current_tool_output + [new_output]
    print(f"--- Updating tool_output to: {updated_tool_output}")
    return {"tool_output": updated_tool_output}

def provide_final_answer(state: AgentState) -> dict:
    """A dummy function to simulate generating a final answer."""
    question = state["user_question"]
    tool_results = state["tool_output"]
    # Imagine an LLM generates this based on question and tool_results
    answer = f"Based on your question '{question}' and tool results {tool_results}, the final answer is: Example final response."
    print(f"--- Updating final_answer to: {answer}")
    return {"final_answer": answer}

# Example of how state updates would look in a node function
# The node function receives the full state and returns a dictionary of updates
# LangGraph then merges this dictionary into the overall state.

When your LangGraph agent runs, each step receives the current state. It then performs its task and returns a dictionary of changes. LangGraph intelligently merges these changes back into the main state, creating a complete and up-to-date record for the next step.

Pros of TypedDict for LangGraph State

• Simplicity: It’s very easy to define and understand, especially for those new to state management.
• No Extra Dependencies: TypedDict is part of Python’s standard library, so you don’t need to install anything new.
• Runtime Performance: It’s just a dictionary at runtime, so there’s no overhead from object creation or validation.
• Good for Basic Type Checking: Provides basic static type checking hints for your code editor.

Cons of TypedDict for LangGraph State

• No Runtime Validation: TypedDict only helps with type hints before your code runs. It won’t stop you from putting a string into an integer field during runtime, which can cause errors.
• Limited Features: It lacks advanced features like default values, custom validators, or nested data structures with specific checks.
• Manual Merging: While LangGraph handles the merging of dictionaries, TypedDict itself doesn’t offer fancy ways to define how fields should be combined (e.g., append to a list vs. replace a value). You handle this logic within your node functions.
• Less Expressive for Complex States: For very complex states with nested data or specific rules, TypedDict can become cumbersome.

Defining LangGraph State with Pydantic BaseModel

Pydantic is a powerful data validation and parsing library that uses Python type hints. It’s widely used for defining data structures, especially in web frameworks. When you use Pydantic BaseModel LangGraph state becomes much more robust.

Pydantic not only defines the types but also validates them when you create a new state object. If you try to put a string where an integer should be, Pydantic will tell you immediately. This makes your agent much more reliable.

How to Use Pydantic BaseModel for LangGraph State

To define your state with Pydantic, you create a class that inherits from pydantic.BaseModel. Inside, you declare your state fields with their types, just like with TypedDict. However, Pydantic brings a lot more to the table.

You can set default values, make fields optional, and even add complex validation rules. This gives you much finer control over your state’s structure and contents. This is a very common approach for modern LangGraph define state TypedDict Pydantic patterns.

First, you’ll need to install Pydantic: pip install pydantic.

from typing import List, Optional
from pydantic import BaseModel, Field

class AgentState(BaseModel):
    """
    Represents the state of our agent using Pydantic.
    - user_question: The original question from the user.
    - tool_output: List of outputs from tool calls. Default to empty list.
    - final_answer: The ultimate answer generated by the agent. Optional.
    - num_iterations: How many steps the agent has taken. Default to 0.
    """
    user_question: str
    tool_output: List[str] = Field(default_factory=list) # Use default_factory for mutable defaults
    final_answer: Optional[str] = None
    num_iterations: int = 0

    # Pydantic allows for custom validation methods
    def validate_user_question_length(self):
        if len(self.user_question) < 5:
            raise ValueError("User question must be at least 5 characters long.")
        return self

Here, AgentState is a Pydantic model. Notice default_factory=list for tool_output and num_iterations=0. These ensure the state starts with sensible defaults. If you try to create AgentState with wrong types, Pydantic will raise an error right away, which is super helpful for catching bugs early.

Updating State with Pydantic

Updating state with Pydantic in LangGraph requires a slightly different approach. LangGraph still expects your node functions to return a dictionary of updates. However, when you return a dictionary from a node function, LangGraph automatically tries to update the current state.

If your state is a Pydantic BaseModel, you can define a special update method directly on your model. This method tells LangGraph exactly how to merge new information into your Pydantic state object. This is a powerful feature for defining complex merging logic.

from typing import List, Optional, Self # Self for Python 3.11+, otherwise use 'AgentState' directly
from pydantic import BaseModel, Field

class AgentState(BaseModel):
    user_question: str
    tool_output: List[str] = Field(default_factory=list)
    final_answer: Optional[str] = None
    num_iterations: int = 0

    def update(self, new_values: dict) -> Self: # Using Self for type hinting the return type
        """
        Custom update logic for Pydantic BaseModel.
        This method will be called by LangGraph's StateGraph to merge updates.
        """
        # Create a copy to modify
        updated_state = self.copy(deep=True)

        # Apply updates
        if "user_question" in new_values:
            updated_state.user_question = new_values["user_question"]
        if "tool_output" in new_values:
            # Example: Extend the list instead of replacing it
            updated_state.tool_output.extend(new_values["tool_output"])
        if "final_answer" in new_values:
            updated_state.final_answer = new_values["final_answer"]
        if "num_iterations" in new_values:
            # Example: Increment the counter instead of just setting it
            updated_state.num_iterations += new_values["num_iterations"] # Assuming new_values["num_iterations"] is 1

        return updated_state

# Example node function using Pydantic state
def pydantic_update_tool_output(state: AgentState) -> dict:
    """A dummy function to simulate a tool call updating the state."""
    # When using Pydantic, your node functions *still* return a dict for updates.
    # The `update` method on AgentState handles how these dicts are merged.
    new_output = "Processed data from tool Y with Pydantic."
    print(f"--- Node returning update for tool_output: {[new_output]}")
    return {"tool_output": [new_output], "num_iterations": 1} # Indicate 1 iteration occurred

def pydantic_provide_final_answer(state: AgentState) -> dict:
    """A dummy function to simulate generating a final answer."""
    question = state.user_question # Access fields as attributes
    tool_results = state.tool_output
    answer = f"Pydantic agent answer: '{question}' processed with {tool_results}."
    print(f"--- Node returning update for final_answer: {answer}")
    return {"final_answer": answer}

Notice how the update method in AgentState explicitly defines how to handle each field. For tool_output, we extend the list, and for num_iterations, we increment it. This is much more powerful than simple dictionary merging. This capability is key to flexible LangGraph define state TypedDict Pydantic choices.

Pros of Pydantic for LangGraph State

• Runtime Validation: Pydantic validates data types and even custom rules when an object is created or updated. This catches errors early.
• Rich Features: You get default values, optional fields, nested models, custom validators, and more. This allows for very expressive LangGraph state schema definitions.
• Better Data Integrity: Ensures your state always conforms to its defined schema, reducing unexpected bugs.
• Improved Readability: Clearly defines the structure of your state, making your code easier to understand and maintain.
• Custom Merging Logic: With the update method, you can define exactly how new information integrates into your existing state.
• Serialization/Deserialization: Pydantic models can easily be converted to and from JSON, which is useful for logging, saving, or transmitting state.

Cons of Pydantic for LangGraph State

• Extra Dependency: You need to install the pydantic library.
• Slightly More Complex: Defining models and understanding their features can be a bit more involved than TypedDict.
• Runtime Overhead: There’s a small performance cost for validation, though usually negligible for typical agent states.
• Boilerplate for Simple States: For very simple states, Pydantic might feel like overkill.

Comparing TypedDict and Pydantic for LangGraph State

Now that we’ve seen both TypedDict and Pydantic, let’s compare them side-by-side. This will help you decide which tool to use for LangGraph define state TypedDict Pydantic in your projects.

Feature	TypedDict	Pydantic BaseModel
Primary Purpose	Type hinting for dictionaries	Data validation, parsing, and serialization
Runtime Validation	No (only static type checking)	Yes, enforces types and rules at runtime
Dependencies	None (built-in Python)	pydantic library required
Default Values	Not directly supported for fields (can set via __init__ if subclassed, but typically handled outside)	Yes, easily defined for fields
Optional Fields	Yes, using Optional[Type] or total=False	Yes, using Optional[Type] or Field(default=None)
Nested Structures	Dictionaries of TypedDicts	Nested Pydantic models for rich structures
Custom Validation Logic	No, must be handled in application code	Yes, via field validators or model validators
Serialization (JSON)	Manual conversion to/from dict	Built-in methods (.model_dump(), .model_validate())
Complexity for Updates	Node functions return dict, LangGraph merges. Logic for list appending vs. replacing handled in node.	Node functions return dict, Pydantic model’s update method handles custom merging logic.
Use Case	Simple states, quick prototyping, minimal dependencies	Complex states, strict data integrity, production applications, advanced LangGraph state schema

When to Use Which?

Choosing between TypedDict and Pydantic depends on your project’s needs and complexity. Both are valid options for LangGraph define state TypedDict Pydantic.

Choose TypedDict if:

• You’re building a simple agent and want to get started quickly.
• You prefer to keep your dependencies minimal.
• Runtime validation isn’t a critical requirement, and you’re confident in your data inputs.
• Your state structure is mostly flat and doesn’t require complex nested types or validation rules.

Choose Pydantic BaseModel if:

• You’re building a complex, production-ready agent where data integrity is paramount.
• You need robust runtime validation to catch errors early.
• Your state involves nested data structures or requires custom validation logic.
• You want to define explicit merging strategies for state updates using the update method.
• You benefit from features like default values, serialization, and clear error messages.
• You’re working on a team where a strict LangGraph state schema benefits collaboration.

Many developers lean towards Pydantic for anything beyond a basic example due to its robustness and developer experience benefits. For building reliable RAG applications, having well-defined state can be crucial, as discussed in Building RAG Applications with LangChain Vector Store in 2026.

Updating State in LangGraph: A Deeper Look

Regardless of whether you use TypedDict or Pydantic, the core mechanism for updating state in LangGraph remains similar: your node functions return a dictionary of changes, and LangGraph merges these changes into the current state. This process is how your agent remembers what has happened and evolves its understanding.

How LangGraph Merges State

LangGraph’s StateGraph uses a simple merging strategy by default. When a node returns a dictionary, LangGraph updates the existing state with the new key-value pairs. If a key already exists, its value is replaced. If a key is new, it’s added.

This default behavior is perfect for replacing entire values, like updating a final_answer. However, for lists or counters, you often want to append or increment, not replace.

Customizing Merging Logic

This is where Pydantic shines with its update method. As shown earlier, you can specifically tell LangGraph how to merge certain fields. For TypedDict, you must handle this logic inside your node functions.

Let’s illustrate with an example. Suppose your state has a tool_history list.

With TypedDict (logic in node):

from typing import List, TypedDict

class MyTypedDictState(TypedDict):
    query: str
    tool_history: List[str]

def add_to_history_typeddict(state: MyTypedDictState) -> dict:
    current_history = state.get("tool_history", [])
    new_entry = "Tool A executed."
    updated_history = current_history + [new_entry]
    return {"tool_history": updated_history} # Return the *new* list

Here, the node function explicitly fetches the current list, adds to it, and then returns the entire new list to replace the old one.

With Pydantic (logic in model’s update method):

from typing import List, Self # Self for Python 3.11+
from pydantic import BaseModel, Field

class MyPydanticState(BaseModel):
    query: str
    tool_history: List[str] = Field(default_factory=list)

    def update(self, new_values: dict) -> Self:
        updated_state = self.copy(deep=True)
        if "tool_history" in new_values:
            updated_state.tool_history.extend(new_values["tool_history"]) # Custom logic to extend
        if "query" in new_values:
            updated_state.query = new_values["query"]
        return updated_state

def add_to_history_pydantic(state: MyPydanticState) -> dict:
    # Node returns a *partial* list of new items
    return {"tool_history": ["Tool B executed."]}

In the Pydantic example, the node simply returns the new item. The update method on MyPydanticState knows to extend the tool_history list rather than replacing it. This separation of concerns makes your node functions cleaner and your state management more robust. This explicit control over merging is a key differentiator when you LangGraph define state TypedDict Pydantic.

Practical Example: A Simple LangGraph Agent

Let’s put everything together with a practical example. We’ll create a very simple agent that takes a question, simulates a tool call, and then generates a final answer. We’ll show how to define and update the state using both TypedDict and Pydantic.

First, let’s define our agent’s nodes and edges. For simplicity, our nodes will be basic Python functions. For more advanced agents, you might integrate with LangChain tools or LLMs, as demonstrated in LangChain Google Gemini Function Calling Agent with Custom Tools.

Example with TypedDict

Here, we’ll use our AgentState defined earlier with TypedDict.

# --- TypedDict Example ---
from typing import List, TypedDict, Optional
from langgraph.graph import StateGraph, END

# 1. Define the state using TypedDict
class TypedDictAgentState(TypedDict):
    user_question: str
    tool_output: List[str]
    final_answer: Optional[str]
    num_iterations: int

# 2. Define node functions
def call_tool_node_typeddict(state: TypedDictAgentState) -> dict:
    print(f"--- Calling tool for question: {state['user_question']}")
    # Simulate a tool call returning some data
    tool_result = f"Data related to '{state['user_question']}' from simulated tool."
    
    current_tool_output = state.get("tool_output", [])
    updated_tool_output = current_tool_output + [tool_result]

    current_iterations = state.get("num_iterations", 0)
    updated_iterations = current_iterations + 1
    
    print(f"--- Tool returned: {tool_result}")
    return {"tool_output": updated_tool_output, "num_iterations": updated_iterations}

def generate_answer_node_typeddict(state: TypedDictAgentState) -> dict:
    print(f"--- Generating answer for question: {state['user_question']}")
    question = state["user_question"]
    tool_results = state["tool_output"]
    # Imagine an LLM synthesizing an answer
    answer = f"Final answer based on: '{question}' and tool results: {tool_results}. This took {state['num_iterations']} steps."
    print(f"--- Final answer generated: {answer}")
    return {"final_answer": answer}

# 3. Build the LangGraph
typed_dict_graph_builder = StateGraph(TypedDictAgentState)

typed_dict_graph_builder.add_node("call_tool", call_tool_node_typeddict)
typed_dict_graph_builder.add_node("generate_answer", generate_answer_node_typeddict)

typed_dict_graph_builder.set_entry_point("call_tool")
typed_dict_graph_builder.add_edge("call_tool", "generate_answer")
typed_dict_graph_builder.add_edge("generate_answer", END)

typed_dict_app = typed_dict_graph_builder.compile()

# 4. Run the agent
print("\n--- Running TypedDict Agent ---")
initial_state_typeddict = {
    "user_question": "What is the capital of France?",
    "tool_output": [],
    "final_answer": None,
    "num_iterations": 0
}

final_state_typeddict = typed_dict_app.invoke(initial_state_typeddict)
print(f"\nFinal State (TypedDict):\n{final_state_typeddict}")
print(f"Agent answered: {final_state_typeddict['final_answer']}")

In the TypedDict example, each node function is responsible for knowing how to update the list (tool_output) and the counter (num_iterations) by explicitly fetching the current value, modifying it, and returning the new value.

Example with Pydantic

Now, let’s use our AgentState with Pydantic. Remember, we define the merging logic in the update method of the Pydantic model itself.

# --- Pydantic Example ---
from typing import List, Optional, Self
from pydantic import BaseModel, Field
from langgraph.graph import StateGraph, END

# 1. Define the state using Pydantic BaseModel with a custom update method
class PydanticAgentState(BaseModel):
    user_question: str
    tool_output: List[str] = Field(default_factory=list)
    final_answer: Optional[str] = None
    num_iterations: int = 0

    def update(self, new_values: dict) -> Self:
        updated_state = self.copy(deep=True) # Start with a copy

        if "user_question" in new_values:
            updated_state.user_question = new_values["user_question"]
        
        if "tool_output" in new_values:
            # Custom logic: extend the list rather than replace
            updated_state.tool_output.extend(new_values["tool_output"])
        
        if "final_answer" in new_values:
            updated_state.final_answer = new_values["final_answer"]
        
        if "num_iterations" in new_values:
            # Custom logic: increment the counter
            updated_state.num_iterations += new_values["num_iterations"]
        
        return updated_state

# 2. Define node functions
# Node functions for Pydantic state expect a PydanticAgentState instance
# and should return a dict of updates, *not* a new PydanticAgentState instance.
def call_tool_node_pydantic(state: PydanticAgentState) -> dict:
    print(f"--- Calling tool for question: {state.user_question}")
    tool_result = f"Pydantic tool data for '{state.user_question}'."
    print(f"--- Tool returned: {tool_result}")
    
    # Node returns updates. The PydanticAgentState.update method handles how these merge.
    return {"tool_output": [tool_result], "num_iterations": 1}

def generate_answer_node_pydantic(state: PydanticAgentState) -> dict:
    print(f"--- Generating answer for question: {state.user_question}")
    question = state.user_question
    tool_results = state.tool_output
    answer = f"Pydantic final answer for: '{question}' with tool results: {tool_results}. Took {state.num_iterations} steps."
    print(f"--- Final answer generated: {answer}")
    return {"final_answer": answer}

# 3. Build the LangGraph with Pydantic state
pydantic_graph_builder = StateGraph(PydanticAgentState)

pydantic_graph_builder.add_node("call_tool", call_tool_node_pydantic)
pydantic_graph_builder.add_node("generate_answer", generate_answer_node_pydantic)

pydantic_graph_builder.set_entry_point("call_tool")
pydantic_graph_builder.add_edge("call_tool", "generate_answer")
pydantic_graph_builder.add_edge("generate_answer", END)

pydantic_app = pydantic_graph_builder.compile()

# 4. Run the agent
print("\n--- Running Pydantic Agent ---")
initial_state_pydantic = PydanticAgentState(user_question="Tell me about AI advancements.")

# LangGraph automatically handles initial state if it's a Pydantic model
final_state_pydantic = pydantic_app.invoke(initial_state_pydantic)
print(f"\nFinal State (Pydantic):\n{final_state_pydantic.model_dump_json(indent=2)}")
print(f"Agent answered: {final_state_pydantic.final_answer}")

In the Pydantic example, the node functions are simpler; they just return the changes. The PydanticAgentState’s update method then applies these changes according to its predefined logic (extending lists, incrementing counters). This separation makes the code cleaner and more maintainable.

You can see how Pydantic adds a layer of abstraction and control over state updates, which can be invaluable for more complex LangGraph define state TypedDict Pydantic scenarios.

Best Practices for LangGraph State Management

Regardless of whether you choose TypedDict or Pydantic, here are some tips for managing your LangGraph state effectively:

• Keep State Minimal: Only store the information truly needed by your agent. Overloading the state makes it harder to manage and can slow things down.
• Clear Naming: Use clear and descriptive names for your state fields. This makes your code easier to understand for everyone.
• Be Specific with Types: Use the most precise types possible (e.g., List[str] instead of just List). This helps with clarity and error prevention.
• Handle Defaults: Ensure your state has sensible default values for fields that might be empty initially. Both TypedDict (via application logic) and Pydantic (via Field or default_factory) support this.
• Immutable Updates: Aim for “immutable” updates where possible. Instead of changing a list in place, create a new list with the changes. LangGraph’s merging mechanism encourages this by expecting new dictionaries.
• Log State Changes: For debugging, it’s very helpful to log the state before and after each node executes. This helps you trace how information flows through your agent.
• Consider Serialization: If you need to save or load your agent’s state (e.g., to persist conversations), Pydantic models are much easier to serialize to and from JSON.

By following these practices, you can build more robust and maintainable LangGraph agents. Managing your state well is key to creating powerful AI applications, much like using effective strategies for building RAG applications with tools and techniques as discussed in LangChain Weaviate Hybrid Search for Scalable RAG and LangChain Semantic Text Splitter: Chunking by Meaning.

Conclusion

Defining and updating state is a fundamental part of building effective LangGraph agents. We’ve explored two primary methods for this: TypedDict and Pydantic. Both offer ways to create a clear LangGraph state schema, but they cater to different needs.

TypedDict is excellent for simplicity, quick starts, and basic type hinting without extra dependencies. It’s a good choice for smaller projects or when you prioritize minimal overhead. However, it lacks runtime validation and advanced features.

Pydantic BaseModel provides robust runtime validation, rich features like default values and custom validators, and powerful control over state merging. It’s the preferred choice for complex, production-grade agents where data integrity and maintainability are crucial. The ability to define custom update logic directly on the model is a significant advantage.

By understanding the strengths and weaknesses of each, you can make an informed decision on how to LangGraph define state TypedDict Pydantic in your next project. Choose the tool that best fits your agent’s complexity and your development workflow, setting you up for success in building intelligent AI applications.