LangGraph SDK

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.

Install

• pip install langgraph-sdk Install stable version

Imports

• 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.

Quickstart

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())