Principle:Langchain ai Langgraph SDK Data Models
| Attribute | Value |
|---|---|
| Knowledge Sources | LangGraph |
| Domains | SDK, Types |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
SDK data models are the canonical TypedDict definitions that represent all LangGraph Server API entities -- assistants, threads, runs, crons, store items, and graph schemas -- in the Python SDK client.
Description
The SDK data model layer provides a comprehensive set of TypedDict classes that mirror the LangGraph Server API's data structures. Every API response is deserialized into one of these types, and request payloads reference them or their associated literal unions.
Core entity types include:
Assistant-- A configured graph instance withassistant_id,graph_id,config,context,metadata,version,name,description, and timestamps.AssistantVersionextends this for version-specific snapshots.Thread-- A conversation thread withthread_id,status,values,interrupts,metadata, and timestamps.Run-- A single graph execution withrun_id,thread_id,assistant_id,status,metadata,multitask_strategy, and timestamps.Cron-- A scheduled recurring execution withcron_id,schedule,payload,enabled,next_run_date,end_time, and timestamps.
State types include ThreadState (full state snapshot with values, next nodes, checkpoint, parent_checkpoint, tasks, and interrupts), ThreadTask (individual task with id, name, error, interrupts, checkpoint, state, and result), and Checkpoint (with thread_id, checkpoint_ns, checkpoint_id, and checkpoint_map).
Store types include Item (a document with namespace, key, value, and timestamps), SearchItem (extending Item with a relevance score), ListNamespaceResponse, and SearchItemsResponse.
Schema and config types include GraphSchema (describing input, output, state, config, and context JSON schemas), Config, StreamPart (a named tuple for stream responses), Command (for graph control flow), and Send (for directing messages to nodes).
The module also defines literal type aliases for status enums (RunStatus, ThreadStatus), strategy enums (MultitaskStrategy, OnConflictBehavior, DisconnectMode), streaming modes (StreamMode, ThreadStreamMode), and sort/select field enums.
Usage
Import these types when working with the LangGraph Python SDK to get full type safety for API interactions. They serve as return types from SDK client methods and as type annotations for request parameters, enabling IDE autocompletion, static type checking, and documentation generation across client code.
Theoretical Basis
The SDK data model layer implements the Data Transfer Object (DTO) pattern, providing lightweight, typed containers that define the exact shape of data exchanged between client and server. By using TypedDict rather than full dataclasses, the models remain compatible with raw dictionary operations while still providing type safety through static analysis tools.
The use of literal type unions for status fields and strategy enums creates a closed vocabulary that constrains valid values at the type level. This shifts error detection from runtime to static analysis time, reducing the likelihood of invalid API calls. The enum-like pattern (RunStatus = Literal["pending", "running", "error", ...]) provides the benefits of enumeration without the runtime overhead of Python enum classes.
The separation of entity types (Assistant, Thread, Run) from state types (ThreadState, ThreadTask) reflects the distinction between resource identity and resource state. An entity persists across its lifecycle while its state represents a point-in-time snapshot. This separation enables efficient polling, diffing, and caching strategies in SDK clients, and aligns with REST principles where entity resources have stable URIs while state is queried on demand.