To help you ship LangGraph apps to production faster, check out LangSmith. LangSmith is a unified developer platform for building, testing, and monitoring LLM applications.
uv add langgraph-sdkThis library provides the Python SDK for interacting with the LangGraph API. Use it to connect to a running LangGraph API server, manage assistants and threads, and stream runs from Python applications.
You will need a running LangGraph API server. If you're running a server locally using langgraph-cli, the SDK will automatically point at http://localhost:8123; otherwise, specify the server URL when creating a client.
For full documentation, see the API reference. For conceptual guides and tutorials, see the LangGraph Docs.
from langgraph_sdk import get_client
# If you're using a remote server, initialize the client with `get_client(url=REMOTE_URL)`
client = get_client()
# List all assistants
assistants = await client.assistants.search()
# We auto-create an assistant for each graph you register in config.
agent = assistants[0]
# Start a new thread
thread = await client.threads.create()
# Start a streaming run
input = {"messages": [{"role": "human", "content": "what's the weather in la"}]}
async for chunk in client.runs.stream(
thread["thread_id"], agent["assistant_id"], input=input
):
print(chunk)websockets>=14 and is only available on the async client (AsyncThreadStream). The sync client (SyncThreadStream) uses SSE exclusively.thread.extensions[name] opens a new subscription each time the same name is accessed. Assign the projection to a variable and reuse it within a single session rather than re-indexing across multiple iterations.RuntimeError on in-flight projections.client.threads.stream() returns a context manager that owns the SSE session for one thread. Typed projections — values snapshots, message streams, tool calls, custom events — all share the same underlying connection.
from langgraph_sdk import get_client
import asyncio
client = get_client()
async with client.threads.stream(
thread_id="my-thread",
assistant_id="agent",
) as thread:
await thread.run.start(input={"messages": [{"role": "user", "content": "hi"}]})
# Start all consumers concurrently so they share one SSE connection.
async def get_messages():
return [s async for s in thread.messages]
async def get_tool_calls():
return [c async for c in thread.tool_calls]
messages, tool_calls = await asyncio.gather(get_messages(), get_tool_calls())
for stream in messages:
print(await stream.text) # accumulated text
final = await thread.output # terminal state valuesSee our Releases and Versioning policies.
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
Configuration for LangSmith tracing.
Configuration options for a call.
Represents a checkpoint in the execution process.
Defines the structure and properties of a graph.
Base model for an assistant.
Represents a specific version of an assistant.
Represents an assistant with additional properties.
Paginated response for assistant search results.
Represents an interruption in the execution flow.
Represents a conversation thread.
Represents a task within a thread.
Represents the state of a thread.
Represents the response from updating a thread's state.
Represents a single execution run.
Represents a scheduled task.
Payload for updating a cron job. All fields are optional.
Defines the parameters for initiating a background run.
Represents a single document or data entry in the graph's Store.
Items are used to store cross-thread memories.
Response structure for listing namespaces.
Item with an optional relevance score from search operations.
Response structure for searching items.
Represents a part of a stream response.
Payload for a task start event.
Payload for a task result event.
A task entry within a CheckpointPayload.
The keys present depend on the task's state:
id, name, error, stateid, name, result, interrupts, statePayload for a checkpoint event.
Payload for the metadata control event.
Stream part emitted for stream_mode="values".
Stream part emitted for stream_mode="updates".
Stream part emitted for partial message chunks (messages/partial).
Stream part emitted for complete messages (messages/complete).
Stream part emitted for message metadata (messages/metadata).
Stream part emitted for stream_mode="messages" (raw message+metadata pair).
Stream part emitted for stream_mode="custom".
Stream part emitted for stream_mode="checkpoints".
Stream part emitted for stream_mode="tasks".
Stream part emitted for stream_mode="debug".
Control event with run_id and other run metadata.
Represents a message to be sent to a specific node in the graph.
This type is used to explicitly send messages to nodes in the graph, typically used within Command objects to control graph execution
Represents one or more commands to control graph execution flow and state.
This type defines the control commands that can be returned by nodes to influence graph execution. It lets you navigate to o
Metadata for a run creation request.
Handles incrementally reading lines from text.
Has the same behaviour as the stdllib bytes splitlines, but handling the input iteratively.
Result wrapper returned by :func:swr.
Client for managing recurrent runs (cron jobs) in LangGraph.
A run is a single invocation of an assistant with optional input, config, and context. This client allows scheduling recurring runs to occ
Handle async requests to the LangGraph API.
Adds additional error messaging & content handling above the provided httpx client.
Client for managing threads in LangGraph.
A thread maintains the state of a graph across multiple interactions/invocations (aka runs). It accumulates and persists the graph's state, allowing for cont
Client for managing runs in LangGraph.
A run is a single assistant invocation with optional input, config, context, and metadata. This client manages runs, which can be stateful (on threads) or state
Payload surfaced when the server requests human input for a thread.
Command dispatcher for run.start.
Bound to one AsyncThreadStream; accesses its transport and id allocator.
Scoped streaming handle for one discovered child invocation.
Async handle for one root-scope tool call.
Async context manager for one thread's v3 streaming session.
Construct via client.threads.stream(thread_id=None, *, assistant_id, ...)
rather than instantiating directly.
Client for managing assistants in LangGraph.
This class provides methods to interact with assistants, which are versioned configurations of your graph.
clie
<!--/ADMON-->
Top-level client for LangGraph API.
Client for interacting with the graph's shared storage.
The Store provides a key-value storage system for persisting data across graph executions, allowing for stateful operations and data sharing ac
Warning for beta features in LangGraph SDK.
Raised when attempting to register a duplicate encryption/decryption handler.
Add custom at-rest encryption to your LangGraph application.
.. warning:: This API is in beta and may change in future versions.
The Encryption class provides a system for implementing custom en
Decrypted data and optional replacement ciphertext.
Return this from a decrypt handler when encrypted data should be replaced, such as after rotating its encryption key. Returning plaintext directly
Context passed to encryption/decryption handlers.
Contains arbitrary non-secret key-values that will be stored on encrypt. These key-values are intended to be sent to an external service that manages
Add custom authentication and authorization management to your LangGraph application.
The Auth class provides a unified system for handling authentication and authorization in LangGraph applications.
User objects must at least expose the identity property.
The dictionary representation of a user.
The base ASGI user protocol
A user object that's populated from authenticated requests from the LangGraph studio.
Note: Studio auth can be disabled in your langgraph.json config.
{
"auth": {
"disable_studio_aut
Base class for authentication context.
Provides the fundamental authentication information needed for authorization decisions.
Complete authentication context with resource and action information.
Extends BaseAuthContext with specific resource and action being accessed, allowing for fine-grained access control decisions.
Time-to-live configuration for a thread.
Matches the OpenAPI schema where TTL is represented as an object with an optional strategy and a time value in minutes.
Parameters for creating a new thread.
create_params = {
"thread_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"metadata": {"owner": "us
<!--/ADMON-->
Parameters for reading thread state or run information.
This type is used in three contexts:
Parameters for updating a thread or run.
Called for updates to a thread, thread version, or run cancellation.
Parameters for deleting a thread.
Called for deletes to a thread, thread version, or run
Parameters for searching threads.
Called for searches to threads or runs.
Payload for creating a run.
create_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"thread_id": UUID("123e4567-e89b
<!--/ADMON-->
Payload for creating an assistant.
create_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"graph_id": "graph123",
<!--/ADMON-->
Payload for reading an assistant.
read_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"metadata": {"owner": "user1
<!--/ADMON-->
Payload for updating an assistant.
update_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"graph_id": "graph123",
<!--/ADMON-->
Payload for deleting an assistant.
delete_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}Payload for searching assistants.
search_params = {
"graph_id": "graph123",
"metadata": {"owner": "user123"},
"limit": 10,
"
<!--/ADMON-->
Payload for creating a cron job.
create_params = {
"payload": {"key": "value"},
"schedule": "0 0 * * *",
"cron_id": UUID("123e4567-e
<!--/ADMON-->
Payload for deleting a cron job.
delete_params = {
"cron_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}Payload for reading a cron job.
read_params = {
"cron_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}Payload for updating a cron job.
update_params = {
"cron_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"payload": {"key": "value"},
<!--/ADMON-->
Payload for searching cron jobs.
search_params = {
"assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
"thread_id": UUID("123e4567
<!--/ADMON-->
Operation to retrieve a specific item by its namespace and key.
This dict is mutable — auth handlers can modify namespace to enforce
access scoping (e.g., prepending the user's identity).
Operation to search for items within a specified namespace hierarchy.
This dict is mutable — auth handlers can modify namespace to enforce
access scoping (e.g., prepending the user's identity).
Operation to list and filter namespaces in the store.
This dict is mutable — auth handlers can modify namespace (the prefix)
to enforce access scoping (e.g., prepending the user's identity).
Operation to store, update, or delete an item in the store.
This dict is mutable — auth handlers can modify namespace to enforce
access scoping (e.g., prepending the user's identity).
Operation to delete an item from the store.
This dict is mutable — auth handlers can modify namespace to enforce
access scoping (e.g., prepending the user's identity).
Namespace for type definitions of different API operations.
This class organizes type definitions for create, read, update, delete, and search operations across different resources (threads, assistan
Types for thread-related operations.
Type for thread creation parameters.
Type for creating or streaming a run.
Type for thread read parameters.
Type for thread update parameters.
Type for thread deletion parameters.
Type for thread search parameters.
Types for assistant-related operations.
Type for assistant creation parameters.
Type for assistant read parameters.
Type for assistant update parameters.
Type for assistant deletion parameters.
Type for assistant search parameters.
Types for cron-related operations.
Type for cron creation parameters.
Type for cron read parameters.
Type for cron update parameters.
Type for cron deletion parameters.
Type for cron search parameters.
Types for store-related operations.
Type for store put parameters.
Type for store get parameters.
Type for store search parameters.
Type for store delete parameters.
Type for store list namespaces parameters.
HTTP exception that you can raise to return a specific HTTP error response.
Since this is defined in the auth module, we default to a 401 status code.
Manages subscriptions and fan-out against one shared SSE connection.
Owns the sync shared SSE handle, subscription registry, and fan-out thread.
Yields params.data from events of a single method.
Covers the channels whose projection is just "emit the payload": values,
updates, checkpoints, tasks — the SDK analog of local's
`Values
Yields one chat-model stream per message-start event.
Subsequent events route to the matching stream via stream.dispatch(data).
Mirrors the per-event body of _MessagesProjection._messages_iter
Yields one tool-call handle per tool-started event.
Mirrors the per-event body of _ToolCallsProjection._tool_calls_iter
(_async/stream.py:1168-1217). The thread register/unregister and the
term
Discovers child subgraph handles and fans out events to active ones.
Mirrors the per-event body of _SubgraphsProjection._subgraphs_iter
(_async/stream.py:963-1041) plus _apply_tasks_result. Roo
Yields params.data from one named custom channel.
Mirrors _ExtensionProjection._iter (_async/stream.py:1278-1299), with
an added name filter so it can share one subscription in interleave.
Sync v3 protocol transport bound to one thread id.
v3 protocol transport bound to a single thread_id.
Commands go to POST /threads/{thread_id}/commands (JSON in, JSON out).
open_event_stream opens filtered SSE streams against
`POST /threads/{th
Sync v3 protocol transport using HTTP commands and WebSocket events.
Handle for one async filtered event stream.
Handle for one sync filtered event stream.
Protocol implemented by async SSE and WebSocket transports.
Protocol implemented by sync SSE and WebSocket transports.
v3 protocol transport using HTTP commands and WebSocket events.
Synchronous client for managing cron jobs in LangGraph.
This class provides methods to create and manage scheduled tasks (cron jobs) for automated graph executions.
<!--/ADMON-->
Handle synchronous requests to the LangGraph API.
Provides error messaging and content handling enhancements above the underlying httpx client, mirroring the interface of HttpClient bu
Synchronous client for managing threads in LangGraph.
This class provides methods to create, retrieve, and manage threads, which represent conversations or stateful interactions.
"Examp
Synchronous client for managing runs in LangGraph.
This class provides methods to create, retrieve, and manage runs, which represent individual executions of graphs.
<!--/ADMON-->
Payload surfaced when the server requests human input for a thread.
Command dispatcher for run.start.
Bound to one SyncThreadStream; accesses its transport and id allocator.
Sync handle for one root-scope tool call.
Scoped streaming handle for one discovered child invocation.
Synchronous context manager for one thread's v3 streaming session.
Construct via client.threads.stream(thread_id=None, *, assistant_id, ...)
rather than instantiating directly.
Client for managing assistants in LangGraph synchronously.
This class provides methods to interact with assistants, which are versioned configurations of your graph.
<!--/ADMON-->
Synchronous client for interacting with the LangGraph API.
This class provides synchronous access to LangGraph API endpoints for managing assistants, threads, runs, cron jobs, and data storage.
???+
A client for synchronous operations on a key-value store.
Provides methods to interact with a remote key-value store, allowing storage and retrieval of items within namespaced hierarchies.
Get a value from the cache.
Returns the deserialized value, or None if the key is missing or expired.
Requires Agent Server runtime version 0.7.29 or later.
Set a value in the cache.
Load a cached value using stale-while-revalidate semantics.
This helper is server-side only and is intended for caching internal async dependencies such as auth or metadata lookups.
Create and configure a LangGraphClient.
The client provides programmatic access to LangSmith Deployment. It supports both remote servers and local in-process connections (when running inside a LangGr
Reject reserved protocol channel names before they hit the fallback.
Genuine extension names pass through untouched; only names that
infer_channel treats as built-in methods without an interleave
Strip the dynamic suffix after : from a namespace segment.
Whether event_namespace starts with prefix.
Segments compare literally first; if the prefix segment contains no :,
the candidate is also compared after its dynamic suffix is stripped.
Mirrors `
Whether event_namespace matches any of prefixes within depth.
Map a protocol event's method to its subscription channel.
Returns None for unrecognized methods so new server-side channels (e.g.
from extension transformers) don't break existing clients.
Whether event should be delivered for definition.
Aggregate a set of subscription filters into one covering filter.
Direct port of client/stream/index.ts:#computeUnionFilter.
Whether coverer is a superset of target.
Direct port of client/stream/index.ts:filterCovers. Depth coverage
accounts for namespace-prefix offset: a scoped coverer needs enough depth
to absorb t
Convert an HTTP base URL plus API path into a WebSocket URL.
Get a synchronous LangGraphClient instance.