This repository contains the Python SDK for interacting with the LangSmith Deployment REST API.
To get started with the Python SDK, install the package
pip install -U langgraph-sdkYou will need a running LangGraph API server. If you're running a server locally using langgraph-cli, SDK will automatically point at http://localhost:8123, otherwise
you would need to specify the server URL when creating a client.
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 valuesConfiguration 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.
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.
Payload 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.
Represents one or more commands to control graph execution flow and state.
Metadata for a run creation request.
Handles incrementally reading lines from text.
Result wrapper returned by :func:swr.
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.
Yields one chat-model stream per message-start event.
Yields one tool-call handle per tool-started event.
Discovers child subgraph handles and fans out events to active ones.
Yields params.data from one named custom channel.
Sync v3 protocol transport bound to one thread id.
v3 protocol transport using HTTP commands and WebSocket events.
v3 protocol transport bound to a single thread_id.
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.
Synchronous client for interacting with the LangGraph API.
Synchronous client for managing threads in LangGraph.
Handle synchronous requests to the LangGraph API.
Synchronous client for managing runs in LangGraph.
A client for synchronous operations on a key-value store.
Synchronous client for managing cron jobs in LangGraph.
Client for managing assistants in LangGraph synchronously.
Payload surfaced when the server requests human input for a thread.
Command dispatcher for run.start.
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.
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.
Context passed to encryption/decryption handlers.
Top-level client for LangGraph API.
Client for managing threads in LangGraph.
Handle async requests to the LangGraph API.
Client for managing runs in LangGraph.
Client for interacting with the graph's shared storage.
Client for managing recurrent runs (cron jobs) in LangGraph.
Client for managing assistants in LangGraph.
Payload surfaced when the server requests human input for a thread.
Command dispatcher for run.start.
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.
Add custom authentication and authorization management to your LangGraph application.
HTTP exception that you can raise to return a specific HTTP error response.
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.
Base class for authentication context.
Complete authentication context with resource and action information.
Time-to-live configuration for a thread.
Parameters for creating a new thread.
Parameters for reading thread state or run information.
Parameters for updating a thread or run.
Parameters for deleting a thread.
Parameters for searching threads.
Payload for creating a run.
Payload for creating an assistant.
Payload for reading an assistant.
Payload for updating an assistant.
Payload for deleting an assistant.
Payload for searching assistants.
Payload for creating a cron job.
Payload for deleting a cron job.
Payload for reading a cron job.
Payload for updating a cron job.
Payload for searching cron jobs.
Operation to retrieve a specific item by its namespace and key.
Operation to search for items within a specified namespace hierarchy.
Operation to list and filter namespaces in the store.
Operation to store, update, or delete an item in the store.
Operation to delete an item from the store.
Namespace for type definitions of different API operations.
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.
Get a value from the cache.
Set a value in the cache.
Load a cached value using stale-while-revalidate semantics.
Strip the dynamic suffix after : from a namespace segment.
Whether event_namespace starts with prefix.
Whether event_namespace matches any of prefixes within depth.
Map a protocol event's method to its subscription channel.
Whether event should be delivered for definition.
Aggregate a set of subscription filters into one covering filter.
Whether coverer is a superset of target.
Reject reserved protocol channel names before they hit the fallback.
Convert an HTTP base URL plus API path into a WebSocket URL.
Get a synchronous LangGraphClient instance.
Create and configure a LangGraphClient.
Data models for interacting with the LangGraph API.
The LangGraph client implementations connect to the LangGraph API.
Adapted from httpx_sse to split lines on
Key/value cache for use inside LangGraph deployments.
Stream module for LangGraph SDK v3.
Subscription matching: channel inference + namespace prefix filtering.
Stream controller: subscription registry and fan-out for AsyncThreadStream.
Unbounded async-iterable append-only log with per-iterator cursors.
Synchronous shared-stream fan-out controller for v3 thread streaming.
Per-channel event → items state machines.
Public exports for the v3 streaming transport layer.
Synchronous HTTP/SSE transport for the v3 thread-centric protocol.
Async WebSocket transport for the v3 thread-centric protocol.
HTTP/SSE transport for the v3 thread-centric protocol.
Sync WebSocket transport for the v3 thread-centric protocol.
Shared transport contracts for v3 thread-centric streaming.
Sync LangGraph client.
Synchronous client for managing threads in LangGraph.
Synchronous HTTP client for LangGraph API.
Synchronous client for managing runs in LangGraph.
Synchronous store client for LangGraph SDK.
Synchronous cron client for LangGraph SDK.
Synchronous client for managing assistants in LangGraph.
Synchronous thread-centric streaming surface for the v3 protocol.
Custom encryption support for LangGraph.
Encryption and decryption types for LangGraph.
Async LangGraph client.
Async client for managing threads in LangGraph.
HTTP client for async operations.
Async client for managing runs in LangGraph.
Async Store client for LangGraph SDK.
Async client for managing recurrent runs (cron jobs) in LangGraph.
Async client for managing assistants in LangGraph.
Async thread-centric streaming surface for the v3 protocol.
Shared utility functions for async and sync clients.
Type aliases and constants.
Exceptions used in the auth system.
Authentication and authorization types for LangGraph.
Represents a JSON-like structure, which can be None or a dictionary with string keys and any values.
Wrapper payload for debug events. Discriminate on type.
Discriminated union of all v2 stream part types.
Response type for authorization handlers.
The result of a handler can be: