LangGraph Python SDK

LangGraph Python SDK (langgraph-sdk)

LangGraph REST API와 상호작용하기 위한 Python SDK 참조 문서야.

LangGraph 앱을 더 빨리 프로덕션에 출시하는 데 도움이 되도록 LangSmith를 확인해 봐. LangSmith는 LLM 애플리케이션을 구축·테스트·모니터링하기 위한 통합 개발자 플랫폼이야.

빠른 설치 (Quick Install)

uv add langgraph-sdk

이게 뭔가요? (What is this?)

이 라이브러리는 LangGraph API와 상호작용하기 위한 Python SDK를 제공해. 실행 중인 LangGraph API 서버에 연결하고, 어시스턴트와 스레드를 관리하며, Python 애플리케이션에서 실행(runs)을 스트리밍하는 데 사용해.

실행 중인 LangGraph API 서버가 필요해. langgraph-cli로 로컬에서 서버를 실행 중이라면 SDK가 자동으로 http://localhost:8123을 가리켜. 그렇지 않으면 클라이언트를 만들 때 서버 URL을 지정해야 해.

문서 (Documentation)

전체 문서는 API 참조를, 개념 가이드와 튜토리얼은 LangGraph 문서를 참고해.

퀵 스타트 (Quick Start)

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)

알려진 제한사항 (Known Limitations)

WebSocket 전송은 websockets>=14가 필요하며 비동기 클라이언트(AsyncThreadStream)에서만 사용할 수 있어. 동기 클라이언트(SyncThreadStream)는 SSE만 사용해.
thread.extensions[name] 은 같은 이름에 접근할 때마다 새 구독을 연다. 프로젝션을 변수에 배정하고 단일 세션 내에서 재사용하는 것이 좋아.
동기 스트리밍은 백그라운드 스레드에서 수명주기 watcher를 구동한다. 장기 실행 동기 세션은 컨텍스트 관리자가 종료될 때까지 해당 스레드를 점유한다.
재연결 시도는 공유 SSE fan-out과 수명주기 watcher 모두 기본적으로 5회로 제한된다. 지속적인 네트워크 분할은 진행 중인 프로젝션에서 RuntimeError로 표면화된다.

스레드 중심 스트리밍 (Thread-Centric Streaming, v3)

client.threads.stream()은 한 스레드의 SSE 세션을 소유하는 컨텍스트 관리자를 반환해. 타입이 지정된 프로젝션(값 스냅샷, 메시지 스트림, 도구 호출, 커스텀 이벤트)은 모두 동일한 기본 연결을 공유해.

from langgraph_sdk import get_client
import asyncio

client = get_client()

async with client.threads.stream(
    thread_id="...",
    assistant_id="...",
    input={"messages": [{"role": "user", "content": "hi"}]},
) as stream:
    async for part in stream:
        print(part)

모듈 목록 (Modules)

langgraph-sdk 참조 문서의 주요 모듈은 다음과 같아:

Client — get_client(), AsyncLangGraphClient / LangGraphClient
Auth / Authorization — 인증 및 인가 핸들러 타입
Schema — 메시지, 어시스턴트, 스레드, 실행, 스트림 파트 관련 타입
Errors — LangGraphError, APIError 등 예외 타입
Stream / Transport — HTTP/SSE 전송 및 스트리밍 프로토콜
SSE — SSE 이벤트 파싱 유틸리티
Cache / Encryption — 내부 캐시·암호화 헬퍼
Runtime — 런타임 관련 헬퍼

출처: 문서

LangGraph Python SDK