LangGraph SDK

raw JSON →
0.3.12 verified Tue May 12 auth: no python install: verified quickstart: verified

The LangGraph SDK (langgraph-sdk) is a Python client for interacting with the LangGraph API (also known as LangSmith Deployment REST API), allowing programmatic access to manage Assistants, Threads, Runs, and Cron jobs. Currently at version 0.3.12, it provides both synchronous and asynchronous clients, serving as a key interface for deploying and managing stateful AI agents orchestrated by the LangGraph framework. The library is part of the actively developed LangChain ecosystem.

pip install langgraph-sdk

Common errors

error langgraph_sdk.errors.AuthenticationError ↓
cause The provided API key is invalid or missing, preventing successful authentication with the LangGraph API.
fix
Ensure the LANGSMITH_API_KEY environment variable is correctly set with a valid API key, or pass it directly when initializing the client, e.g., client = get_client(api_key='your_api_key').
error AttributeError: '_ExecutionRuntime' object has no attribute 'previous' ↓
cause This is a known bug in specific `langgraph-sdk` and `langgraph-api` versions (including 0.3.12) where internal runtime objects are missing expected attributes during graph schema serialization.
fix
Upgrade langgraph-sdk and langgraph-api to versions where this bug is resolved. If an upgrade is not immediately available, the suggested fix involves modifying libs/sdk-py/langgraph_sdk/runtime.py to add previous: Any = field(default=None) to _ExecutionRuntime and both context: Any = field(default=None) and previous: Any = field(default=None) to _ReadRuntime.
error ModuleNotFoundError: No module named 'langchain_google_genai' ↓
cause A required LangChain integration package, such as `langchain-google-genai` for using the Google Gemini LLM, is not installed in the Python environment where the LangGraph application is being run.
fix
Install the missing package using pip, for example: pip install langchain-google-genai. Ensure all necessary project dependencies are installed in the active virtual environment.
error langgraph_sdk.errors.APIConnectionError ↓
cause The `langgraph-sdk` client failed to establish a connection with the LangGraph API endpoint, which can be due to network issues, an incorrect API URL, or the API server being unreachable.
fix
Verify that the url parameter provided to the get_client function or the LANGGRAPH_API_URL environment variable is correct. Ensure the LangGraph API server is running and accessible from your environment, and check for any network connectivity problems or firewall restrictions.

Warnings

gotcha The `langgraph-sdk` acts as a client and requires a separate, running LangGraph API server to operate. It does not embed the server. If `langgraph-cli` is used locally, the SDK defaults to `http://localhost:8123`, otherwise the server URL must be explicitly provided during client initialization. ↓
fix Ensure a LangGraph API server is deployed and running. Pass the correct server URL to `get_client(url='YOUR_SERVER_URL')` or set the `LANGGRAPH_SERVER_URL` environment variable.
gotcha The primary `get_client()` function returns an asynchronous client. For synchronous operations, it is crucial to use `get_sync_client()` instead. Attempting to use the asynchronous client in a synchronous context without proper `await` calls or an event loop will lead to runtime errors or unexpected behavior. ↓
fix For asynchronous code, use `from langgraph_sdk import get_client` and `await` its methods. For synchronous code, use `from langgraph_sdk import get_sync_client` and call its methods directly.
gotcha By default, `get_client()` (and `get_sync_client()`) attempts to load the API key from the `LANGGRAPH_API_KEY` environment variable. If the key is not set or you explicitly want to connect without an API key (e.g., for an unsecured local development server), you must pass `api_key=None` to the client constructor. ↓
fix Set the `LANGGRAPH_API_KEY` environment variable or explicitly provide the API key using `client = get_client(api_key='YOUR_KEY')` or disable it with `client = get_client(api_key=None)`.
breaking Recent updates to the underlying LangGraph Agent Server API (which the SDK interacts with) have changed header handling. Headers previously included automatically in runs must now be explicitly allowed by setting `configurable_headers` in the server's configuration. Additionally, the format of stream event IDs for resumable streams has changed to `ms-seq`, although backward compatibility is currently maintained for older formats. This may require adjustments if relying on specific header propagation or event ID parsing. ↓
fix Review your LangGraph API server configuration to ensure `configurable_headers` are set as needed. Update any custom stream parsing logic to handle the new `ms-seq` event ID format, even if backward compatibility is currently in place, to future-proof your integration.
breaking The `langgraph-sdk` requires the `typing_extensions` package, but it was not found in the environment. This typically indicates a missing dependency that needs to be explicitly installed for the SDK to function. ↓
fix Install the missing dependency using `pip install typing_extensions`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.28s 23.3M
3.10 alpine (musl) - - 0.33s 23.3M
3.10 slim (glibc) wheel 2.7s 0.21s 24M
3.10 slim (glibc) - - 0.25s 24M
3.11 alpine (musl) wheel - 0.43s 25.6M
3.11 alpine (musl) - - 0.61s 25.6M
3.11 slim (glibc) wheel 2.7s 0.38s 26M
3.11 slim (glibc) - - 0.39s 26M
3.12 alpine (musl) wheel - 0.60s 17.3M
3.12 alpine (musl) - - 0.66s 17.4M
3.12 slim (glibc) wheel 2.4s 0.59s 18M
3.12 slim (glibc) - - 0.63s 18M
3.13 alpine (musl) wheel - - 16.7M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 2.4s - 17M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - 0.25s 22.2M
3.9 alpine (musl) - - 0.24s 22.2M
3.9 slim (glibc) wheel 3.2s 0.23s 23M
3.9 slim (glibc) - - 0.37s 23M

Imports

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to initialize an asynchronous LangGraph client, connect to a running LangGraph API server (which can be local or remote), and then list the deployed assistants. It highlights the use of `get_client` and retrieving basic information about agents.

import os
import asyncio
from langgraph_sdk import get_client

# Ensure the LangGraph API server is running and accessible.
# By default, it looks for a server at http://localhost:8123
# and LANGGRAPH_API_KEY in environment variables.
LANGGRAPH_SERVER_URL = os.environ.get('LANGGRAPH_SERVER_URL', 'http://localhost:8123')
LANGGRAPH_API_KEY = os.environ.get('LANGGRAPH_API_KEY', 'your_api_key_here') # Replace with actual key or set env var

async def main():
    try:
        client = get_client(url=LANGGRAPH_SERVER_URL, api_key=LANGGRAPH_API_KEY)
        print(f"Connected to LangGraph server at: {LANGGRAPH_SERVER_URL}")

        # List all assistants (agents/graphs deployed on the server)
        assistants_page = await client.assistants.search(limit=10)
        assistants = assistants_page.results # Access the results attribute

        if assistants:
            print(f"Found {len(assistants)} assistants:")
            for assistant in assistants:
                print(f"  - ID: {assistant.assistant_id}, Name: {assistant.name}, Version: {assistant.public_version}")
            # Example: Get details of the first assistant
            first_assistant = await client.assistants.get(assistant_id=assistants[0].assistant_id)
            print(f"\nDetails for first assistant ({first_assistant.name}):\n{first_assistant.model_dump_json(indent=2)}")
        else:
            print("No assistants found on the server.")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Please ensure a LangGraph API server is running and accessible, and LANGGRAPH_API_KEY is correctly set.")

if __name__ == "__main__":
    asyncio.run(main())
last verified Tue May 12
next check Sat Jun 27