LangGraph Cheatsheet

Commands

LangGraph 개발, 로컬 서버, Docker 검증, 배포 명령을 실행 목적과 함께 정리했습니다. 처음 진입자는 langgraph dev 한 줄만 익혀도 그래프를 띄워볼 수 있고, 배포 전 점검은 langgraph up으로 production-like 환경에서 한 번 더 확인하는 흐름이 표준입니다.

Local Development Commands

Install

pip install -U langgraphPython 프로젝트에 LangGraph 핵심 라이브러리를 설치합니다. 그래프 정의와 실행 API를 사용할 수 있게 됩니다.
pip install langgraph-cliLangGraph CLI를 설치합니다. Docker 기반 local server, build, deploy 명령을 사용할 때 필요합니다.
pip install -U "langgraph-cli[inmem]"Docker 없이 `langgraph dev`를 빠르게 실행하기 위한 개발용 설치 방식입니다. 로컬 프로토타입에 적합합니다.
langgraph --helpCLI가 정상 설치됐는지 확인하고 사용 가능한 명령을 봅니다.

Run locally

langgraph dev빠른 로컬 개발 서버를 실행합니다. hot reload와 LangGraph Studio 연동을 확인할 때 사용합니다.
langgraph dev --port 2024개발 서버 포트를 명시합니다. 기본 포트 충돌이 있을 때 사용합니다.
langgraph dev --config langgraph.json특정 LangGraph 설정 파일을 지정해 개발 서버를 실행합니다.
uv run langgraph devuv 기반 Python 프로젝트에서 현재 가상환경과 의존성으로 개발 서버를 실행합니다.
npx @langchain/langgraph-cli devJavaScript/TypeScript 프로젝트에서 LangGraph 개발 서버를 실행합니다.

Invoke from code

graph.invoke(input)컴파일된 그래프를 동기 방식으로 한 번 실행합니다. 간단한 테스트와 단일 요청에 사용합니다.
await graph.ainvoke(input)비동기 환경에서 그래프를 한 번 실행합니다. 웹 서버나 async tool 흐름에 적합합니다.
graph.stream(input)그래프 실행 중간 결과를 순차적으로 받습니다. UI 업데이트나 디버깅에 유용합니다.
async for event in graph.astream(input)비동기 streaming으로 node update, message, custom event를 처리합니다.
graph.get_state(config)thread_id 기준으로 현재 checkpoint state를 조회합니다.
graph.update_state(config, values)중단된 그래프나 저장된 state를 외부에서 수정합니다. human-in-the-loop에 사용합니다.

Build / Deploy / Config Commands

Server / Docker

langgraph upDocker 기반 local server를 실행합니다. 배포와 유사한 환경에서 의존성/시작 오류를 검증합니다.
langgraph up --recreate이미지와 컨테이너를 새로 만들어 실행합니다. 배포 전 fresh build 검증에 적합합니다.
langgraph buildLangGraph API server용 Docker image를 빌드합니다.
langgraph dockerfilelanggraph.json 기준 Dockerfile을 생성합니다. 배포 환경을 직접 제어해야 할 때 사용합니다.
langgraph deployLangSmith Deployments로 build/deploy 흐름을 실행합니다.

langgraph.json

dependencies앱 실행에 필요한 로컬 패키지, 프로젝트 루트, 외부 패키지를 선언합니다.
graphsassistant 이름과 graph export 경로를 매핑합니다. 서버가 어떤 그래프를 노출할지 결정합니다.
env.env 파일 경로를 지정합니다. API key와 secret은 코드가 아니라 env로 분리합니다.
authcustom auth handler를 연결합니다. production API 접근 제어에 필요합니다.
base_image서버 이미지의 base Docker image를 지정합니다. 런타임 요구사항이 특수할 때 사용합니다.
image_distro이미지 배포판을 선택합니다. 의존성 호환성을 맞출 때 확인합니다.
store.indexlong-term memory store의 semantic search index를 설정합니다. embedding dimension 확인이 중요합니다.
store.ttlstore item의 time-to-live 정책을 지정합니다. 오래된 memory 정리에 사용합니다.
checkpointercheckpoint backend를 지정합니다. resume, interrupt, fault recovery의 기반입니다.
httpcustom route를 정의합니다. graph endpoint 외 별도 API를 노출할 때 사용합니다.
webhooks외부 이벤트를 graph 실행과 연결합니다.
api_versionLangGraph platform API version을 명시합니다.

Graph export

./your_package/graph.py:graphPython 파일에서 컴파일된 graph 객체를 export하는 기본 패턴입니다.
./your_package/graph.py:make_graphfactory 함수로 graph를 생성해 export합니다. 환경별 graph 구성에 유용합니다.
./src/graph.ts:graphTypeScript 프로젝트에서 graph 객체를 export하는 패턴입니다.
./src/graph.ts:makeGraphTypeScript graph factory를 export하는 패턴입니다.
CompiledStateGraphcompile() 이후 실행 가능한 graph 객체입니다. invoke/stream 대상입니다.
StateGraph factorystate schema와 설정에 따라 graph를 동적으로 구성하는 함수 패턴입니다.

Workflows

그래프를 만드는 기본 루틴과 운영 가능한 에이전트로 확장하는 루틴을 나눠 정리했습니다. checkpointer를 안 붙이면 멀티턴 도중 state가 사라지고, conditional_edges가 없으면 사용자 입력에 따라 다른 길로 가는 분기 자체가 불가능해집니다. 처음부터 이 두 가지를 같이 설계하는 게 안전합니다.

Basic / Project Workflow

Graph API flow

State schema 정의그래프 전체가 공유할 작업 메모리를 먼저 정의합니다. TypedDict, dataclass, Pydantic을 사용할 수 있습니다.
StateGraph(State)state schema를 기준으로 graph builder를 만듭니다. node와 edge는 이 builder에 등록합니다.
add_node(name, fn)LLM 호출, tool 실행, 검증, 라우팅 같은 처리 단위를 node로 등록합니다.
add_edge(START, node)그래프 시작점을 첫 node에 연결합니다.
add_conditional_edges(node, router)state를 보고 다음 node를 동적으로 결정합니다. router agent, tool 선택, 분기에 사용합니다.
add_edge(node, END)마지막 node를 종료 지점에 연결합니다.
compile()그래프 구조를 검증하고 실행 가능한 객체로 만듭니다. 실행 전 필수 단계입니다.
invoke / stream완성된 graph를 단일 실행하거나 streaming으로 실행합니다.

Functional API flow

@entrypoint함수 하나를 workflow 시작점으로 만듭니다. 기존 Python control flow를 유지하고 싶을 때 적합합니다.
@taskAPI 호출, 파일 쓰기, 랜덤/시간 의존 작업 같은 side effect를 캡슐화합니다. 재개 시 중복 실행 위험을 줄입니다.
task.result()entrypoint 내부에서 task 결과를 회수합니다.
previous같은 thread의 이전 checkpoint 값을 읽습니다. 누적 요약이나 반복 작업에 유용합니다.
configRunnableConfig와 thread_id 등 runtime 설정을 참조합니다.
storelong-term memory store에 접근합니다. 사용자별 메모리나 지식 검색에 사용합니다.

State design

TypedDict / dataclass / Pydanticstate schema를 명시하는 대표 방식입니다. 단순하면 TypedDict, 검증이 필요하면 Pydantic을 고려합니다.
MessagesStatemessages key와 message reducer가 포함된 prebuilt state입니다. 대화형 agent에 적합합니다.
add_messages reducermessage list를 append/update 가능한 방식으로 병합합니다. tool call 결과 관리에 유용합니다.
overwrite reducer같은 key가 업데이트될 때 새 값으로 덮어씁니다. 단일 결과 값에 적합합니다.
append reducer여러 node가 같은 key에 결과를 추가할 때 사용합니다. 병렬 실행 결과 수집에 필요합니다.
partial state updatenode는 전체 state가 아니라 변경할 key만 반환하는 방식이 일반적입니다.
router returnrouter는 다음 node 이름, END, Command, Send 등을 반환해 흐름을 제어합니다.

Advanced / Production Workflow

Human-in-the-loop

interrupt(payload)사람의 승인, 수정, 검토가 필요한 지점에서 그래프 실행을 멈춥니다.
Command(resume=...)interrupt 이후 사용자의 입력을 전달해 그래프를 재개합니다.
thread_id 유지resume하려면 동일 thread_id로 checkpoint를 찾아야 합니다.
checkpoint 필요interrupt, resume, 장애 복구를 쓰려면 checkpointer를 설계 초기에 붙이는 것이 좋습니다.
approval gate외부 전송, 삭제, 결제, 배포처럼 위험한 행동 전 승인 지점을 둡니다.
side effect 중복 방지resume 이후 API 호출이나 파일 쓰기가 반복되지 않도록 @task 또는 checkpoint 경계를 명확히 둡니다.

Parallel / routing

conditional edge routerstate를 보고 다음 node를 선택합니다. 문의 분류, tool 선택, 오류 처리 분기에 사용합니다.
Command(update=..., goto=...)state update와 routing을 한 node에서 함께 처리합니다.
Send(node, state)동적으로 여러 node 실행을 생성합니다. map-reduce, 병렬 리서치, batch 처리에 적합합니다.
fan-out / fan-in여러 작업을 병렬 실행한 뒤 reducer로 결과를 합치는 패턴입니다.
subgraph복잡한 workflow를 작은 graph로 분리합니다. 재사용성과 테스트 가능성이 좋아집니다. 쉽게 말하면 "함수처럼 재사용 가능한 미니 그래프"로 큰 그래프를 깔끔하게 쪼개는 도구입니다.
super-step병렬 node들이 같은 단계에서 실행되고 다음 단계로 넘어가는 실행 단위입니다.

Production checks

langgraph dev빠른 local iteration에 사용합니다. node 흐름과 streaming을 확인합니다.
langgraph upDocker 기반 production-like 검증에 사용합니다. 의존성, env, server startup 문제를 잡습니다.
store TTLlong-term memory가 무한히 쌓이지 않도록 보존 기간을 설계합니다.
checkpoint TTLresume 가능한 상태의 보존 기간을 정합니다. 비용과 개인정보 정책에 영향을 줍니다.
auth handlerproduction endpoint 접근 권한을 검증합니다. custom route도 같은 정책을 따라야 합니다.
sensitive headers로그에 인증 토큰이나 개인정보가 남지 않도록 제외합니다.
semantic index dimsembedding model과 index dimension이 맞는지 확인합니다. mismatch는 검색 오류를 만듭니다.

Shortcuts

자주 쓰는 LangGraph API와 control primitive를 코드와 설명 쌍으로 정리했습니다. StateGraph, MessagesState, Command, Send, interrupt처럼 이름만 봐선 감이 안 오는 핵심 키워드에는 "쉽게 말하면" 한 줄을 덧붙여, 처음 보는 분도 어디에 쓰는 도구인지 바로 감을 잡을 수 있게 했습니다.

Graph API Primitives

Build graph

StateGraph(State)state schema를 기반으로 graph builder를 만듭니다. Graph API의 시작점입니다. 쉽게 말하면 "공유 메모지(state)를 들고 다닐 노드 지도"를 만드는 단계입니다.
START그래프 시작을 나타내는 virtual node입니다. 첫 node로 edge를 연결합니다.
END그래프 종료를 나타내는 virtual node입니다. 작업 완료 지점에 연결합니다.
add_node(name, fn)이름과 실행 함수를 묶어 node를 등록합니다.
add_edge(a, b)정적인 실행 순서를 정의합니다. a 다음에 b를 실행합니다.
add_conditional_edges(node, router)router 결과에 따라 다음 node를 결정합니다. 쉽게 말하면 "if/else 분기"를 그래프 위에 그리는 도구입니다.
compile(checkpointer=...)graph를 실행 가능한 객체로 컴파일하고 필요하면 checkpoint backend를 연결합니다.

Run graph

invoke동기 단일 실행입니다. 테스트와 간단한 API 요청에 적합합니다.
ainvoke비동기 단일 실행입니다. async server나 tool 흐름에 적합합니다.
stream동기 streaming 실행입니다. 중간 결과를 UI나 로그로 보여줄 때 사용합니다.
astream비동기 streaming 실행입니다. async UI/event pipeline에 적합합니다.
get_state현재 thread의 checkpoint state를 조회합니다.
update_state저장된 state를 외부에서 수정합니다. human correction에 사용합니다.
RunnableConfigthread_id, tags, metadata 등 runtime 설정을 담습니다.
configurable.thread_idcheckpoint와 resume의 기준이 되는 thread 식별자입니다.

Messages

MessagesStatemessages 중심 graph를 빠르게 만들 수 있는 prebuilt state입니다. 쉽게 말하면 ChatGPT처럼 대화 기록을 이어가는 챗봇용 기본 state 양식입니다.
add_messagesmessage list를 안전하게 append/update하는 reducer입니다.
HumanMessage사용자 입력 message를 나타냅니다.
AIMessage모델 응답 message를 나타냅니다. tool call 정보도 포함할 수 있습니다.
ToolMessagetool 실행 결과를 모델 대화 흐름에 다시 넣는 message입니다.
message id update동일 ID message를 덮어써 streaming이나 수정 결과를 반영합니다.
tool call result appendtool call 결과를 message history에 추가해 다음 LLM 호출 컨텍스트로 사용합니다.

Functional / Control Primitives

Functional API

@entrypoint(checkpointer=...)함수를 durable workflow 시작점으로 만듭니다. checkpointer를 붙이면 resume이 가능합니다.
@task재시작/재개 시 side effect 중복을 줄이는 작업 단위입니다.
.result()task 실행 결과를 entrypoint 내부에서 회수합니다.
previous이전 checkpoint state를 entrypoint 인자로 받습니다.
storelong-term memory store를 함수에서 사용합니다.
writercustom streaming data를 외부로 보냅니다.
configRunnableConfig와 thread_id에 접근합니다.
timeouttask 또는 workflow 실행 제한 시간을 설정합니다.
retry_policy실패한 task 재시도 정책을 지정합니다.

Control

Command(update=..., goto=...)state update와 다음 이동을 한 번에 반환합니다. routing node에 적합합니다. 쉽게 말하면 "메모지에 결과 적고, 동시에 다음 노드 가리키기"를 한 번에 처리합니다.
Command(resume=...)interrupt 이후 사용자 입력이나 승인 결과를 전달합니다.
Send(node, state)동적으로 여러 node 실행을 생성합니다. 병렬 fan-out에 사용합니다. 쉽게 말하면 "리스트 10개를 동시에 같은 노드에 뿌려서 한꺼번에 처리"하는 map-reduce 패턴입니다.
interrupt(payload)사람 입력이 필요한 지점에서 실행을 멈추고 payload를 전달합니다. 쉽게 말하면 결제, 발송, 삭제 같은 위험한 행동 직전에 "사람한테 한 번 물어보고 가는 정지 버튼"입니다.
checkpointergraph 실행 중간 상태를 저장합니다. resume, history, fault recovery에 필요합니다. 쉽게 말하면 게임의 "자동 저장 슬롯"입니다. 이게 없으면 멀티턴 대화가 매번 처음부터 시작됩니다.
InMemorySaver개발용 메모리 checkpointer입니다. production persistence와 구분해야 합니다.
BaseStorelong-term memory와 semantic search를 위한 store 인터페이스입니다.

When to choose

Graph API구조, 시각화, 명시적 node/edge, 복잡한 분기가 중요한 경우 선택합니다.
Functional API기존 Python 함수 흐름을 유지하면서 persistence와 interrupt를 붙이고 싶을 때 선택합니다.
Commandstate 업데이트와 routing 결정을 같은 node에서 처리해야 할 때 사용합니다.
Send입력 개수에 따라 실행할 node 수가 동적으로 달라질 때 사용합니다.
interrupt사람 승인이나 수정 없이는 진행하면 안 되는 workflow에 사용합니다.
checkpointresume, 장애 복구, human-in-the-loop이 필요하면 처음부터 설계합니다.

Coverage / Omitted Items

LangGraph는 공식 문서 기준으로 구성했습니다.

Graph API, Functional API, CLI, local server, langgraph.json, checkpoint, interrupt, Command, Send처럼 에이전트 workflow 설계에 직접 쓰는 항목을 포함했습니다.

전체 API reference의 모든 class와 method를 복제하지는 않았습니다. 이 페이지는 실무 치트시트 목적상 command, workflow, shortcut primitive를 우선합니다.

Sources

출처

LangGraph 공식 문서 기준으로 명령어, Graph API, Functional API, local server 항목을 확인했습니다.

LangGraph Overview Graph API Use Graph API Functional API Use Functional API LangGraph CLI Local Development