Install & Compatibility
Where this runs
tested against v0.4.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.258s · 70.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 1.116s · 79MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_client
✓ from langgraph_sdk import get_client
Used to create an asynchronous client for interacting with the LangGraph API.
get_sync_client
✓ from langgraph_sdk import get_sync_client
Used to create a synchronous client for interacting with the LangGraph API.
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())
Debug
Known issues
gotchaThe `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.fixEnsure 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.
affects: All versions
gotchaThe 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.fixFor 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.
affects: All versions
gotchaBy 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.fixSet 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)`.
affects: All versions
breakingRecent 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.fixReview 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.
affects: Agent Server versions v0.7.12 and above (approximately), SDK versions that interact with these server changes.
breakingThe `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.fixInstall the missing dependency using `pip install typing_extensions`.
affects: All `langgraph-sdk` versions that directly or indirectly depend on `typing_extensions` but do not list it as a mandatory installation requirement, or in environments where it's not otherwise present.
Errors
Common errors & fixes
langgraph_sdk.errors.AuthenticationError
The provided API key is invalid or missing, preventing successful authentication with the LangGraph API.
fixEnsure 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')`.
AttributeError: '_ExecutionRuntime' object has no attribute 'previous'
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.
fixUpgrade `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`.
ModuleNotFoundError: No module named 'langchain_google_genai'
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.
fixInstall the missing package using pip, for example: `pip install langchain-google-genai`. Ensure all necessary project dependencies are installed in the active virtual environment.
langgraph_sdk.errors.APIConnectionError
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.
fixVerify 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.
Upgrade
Version history
0.4.3latest on PyPI · released Aug 19, 2026
Audit
Dependencies
No dependency data recorded yet.