Your interface, spelled three different ways

In TypeScript you write interface and stop thinking. Python has three answers, they are genuinely different at runtime, and picking the wrong one is the most common structural mistake a TypeScript developer makes in their first month here.

TypedDict: your interface, and it stays a dict

from typing import TypedDict, NotRequired

class AgentState(TypedDict):
    messages: list[str]
    step: int
    scratch: NotRequired[str]     # may be absent entirely

At runtime, this creates nothing. A value annotated AgentState is a plain dict. There is no wrapper, no validation, no constructor logic, and no error if you put a key in that the declaration does not name. It is annotation-only, exactly like a TypeScript interface: real to the checker, absent from the output.

That sounds useless until you notice what it buys: the value is still a dict, so it serialises, persists, merges, and crosses a process boundary without ceremony.

Which is precisely why LangGraph state is a TypedDict. State gets checkpointed, written to Postgres, resumed in another process. A dict does all that natively and an object does not.

from typing import Annotated, TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]
    remaining_steps: int

Annotated[T, extra] is worth pausing on. It attaches metadata to a type without changing the type: to a checker this is still list, and the second argument is a payload that a library reads. LangGraph reads it to find the reducer that merges concurrent writes to that key. You will meet Annotated constantly in this ecosystem, and it is always this pattern: a type, plus something the framework picks up.

NotRequired and Required mark individual keys (3.11 and later). total=False in the class header makes every key optional at once, which is the older and blunter form.

dataclass: a real object, with the boilerplate generated

from dataclasses import dataclass, field

@dataclass
class RetryPolicy:
    attempts: int = 3
    backoff: float = 1.5
    tags: list[str] = field(default_factory=list)

p = RetryPolicy(attempts=5)
p.attempts                      # attribute access, not p["attempts"]
p == RetryPolicy(attempts=5)    # True. __eq__ is generated.
repr(p)                         # 'RetryPolicy(attempts=5, backoff=1.5, tags=[])'

The decorator reads the annotated class attributes and generates __init__, __repr__ and __eq__. That is the whole feature. It is the closest thing Python has to a plain data class, it is in the standard library, and it is the right default for objects that live inside your program.

The useful options:

@dataclass(frozen=True)    # immutable. Also makes instances hashable.
@dataclass(slots=True)     # no __dict__. Less memory, faster, no ad-hoc attributes.
@dataclass(kw_only=True)   # every field must be passed by keyword
@dataclass(order=True)     # generates __lt__ and friends, so instances sort

frozen=True is worth reaching for by default on anything that represents a value rather than an entity. slots=True incidentally fixes the typo hazard from module 1: with slots, p.atempts = 9 raises AttributeError instead of silently creating a field.

Dataclasses do not validate. RetryPolicy(attempts="five") constructs happily, because the annotation is a hint and the generated __init__ just assigns.

Protocol: structural typing, arriving late and arriving right

from typing import Protocol

class SupportsClose(Protocol):
    def close(self) -> None: ...

def cleanup(resource: SupportsClose) -> None:
    resource.close()

Any class with a matching close method satisfies SupportsClose. It does not import it, subclass it, or know it exists. This is TypeScript’s interface semantics, and it is the closest thing in Python to how you already think.

Two things this makes possible that nominal typing cannot:

• Describing a type you do not own. Write a Protocol matching a third-party class and your code is typed against the shape rather than the vendor.
• Testing without mocking frameworks. A five-line stub class satisfies the protocol and your production code cannot tell.

@runtime_checkable goes on the protocol and enables isinstance checks against it. Use it sparingly: it checks method names only, not signatures, so it can say yes to something that will explode on call.

Choosing

The rough map: TypedDict for data on the wire, dataclass for objects in memory, Protocol for the interface between them.

The pattern you will actually meet

Real agent code uses all three within a single file, and once you can see why, the file stops looking arbitrary:

class GraphState(TypedDict):              # persisted by a checkpointer
    messages: Annotated[list, add_messages]

@dataclass(frozen=True)
class Context:                            # in-memory, passed at invoke time
    user_id: str
    locale: str = "en"

class Store(Protocol):                    # whatever backend we were handed
    def get(self, key: str) -> dict | None: ...
    def put(self, key: str, value: dict) -> None: ...

State is a dict because it crosses a boundary. Context is a frozen dataclass because it is an in-process value nobody should mutate. Store is a protocol because the code does not care what the backend is.

Where this goes

None of these three validate anything. The next lesson is the one that does, and it is the single most important Python library for the work you are about to do.