LangGraph CLI는 LangGraph API 서버를 로컬에서 구축하고 실행할 수 있는 커맨드라인 도구입니다. 이 서버는 runs, threads, assistants 등 모든 API 엔드포인트를 제공하며, 체크포인팅 및 스토리지를 위한 관리형 데이터베이스와 같은 지원 서비스를 포함합니다.

​
설치

  1. Docker가 설치되어 있는지 확인하세요 (예: docker --version).
  2. CLI를 설치하세요: 
    pip install langgraph-cli
  3. 설치를 확인하세요 
    langgraph --help

​
빠른 명령어

Command동작 설명
langgraph dev가벼운 로컬 개발 서버를 시작합니다 (Docker 불필요). 빠른 테스트에 적합합니다.
langgraph build배포를 위한 LangGraph API 서버의 Docker 이미지를 빌드합니다.
langgraph dockerfile커스텀 빌드를 위한 설정에서 파생된 Dockerfile을 출력합니다.
langgraph upLangGraph API 서버를 Docker에서 로컬로 시작합니다. Docker 실행 필요; 로컬 개발에는 LangSmith API 키, 프로덕션에는 라이선스 필요.
JS에서는 npx @langchain/langgraph-cli <command> (또는 글로벌 설치 시 langgraphjs)를 사용하세요.

​
설정 파일

LangGraph CLI는 schema를 따르는 JSON 설정 파일이 필요합니다. 주요 속성은 다음과 같습니다:
LangGraph CLI는 기본적으로 현재 디렉터리의 langgraph.json 설정 파일을 사용합니다.
  • Python
  • JS
Key설명
dependencies필수. LangSmith API 서버의 의존성 배열입니다. 다음 중 하나를 지정할 수 있습니다:
  • 단일 마침표(".")는 로컬 Python 패키지를 찾습니다.
  • pyproject.toml, setup.py 또는 requirements.txt가 위치한 디렉터리 경로.
    예를 들어, requirements.txt가 프로젝트 루트에 있으면 "./"로 지정합니다. local_package라는 하위 디렉터리에 있으면 "./local_package"로 지정합니다. "requirements.txt" 문자열 자체는 지정하지 않습니다.
  • Python 패키지 이름.
graphs필수. 그래프 ID와 컴파일된 그래프 또는 그래프를 생성하는 함수가 정의된 경로의 매핑. 예시:
  • ./your_package/your_file.py:variable에서 variable은 langgraph.graph.state.CompiledStateGraph 인스턴스입니다.
  • ./your_package/your_file.py:make_graph에서 make_graph는 설정 딕셔너리(langchain_core.runnables.RunnableConfig)를 받아 langgraph.graph.state.StateGraph 또는 langgraph.graph.state.CompiledStateGraph 인스턴스를 반환하는 함수입니다. 런타임에 그래프 재구성하는 방법 참고.
auth(v0.0.11에서 추가됨) 인증 핸들러 경로를 포함하는 인증 설정. 예시: ./your_package/auth.py:auth에서 auth는 langgraph_sdk.Auth 인스턴스입니다. 자세한 내용은 인증 가이드 참고.
base_image선택 사항. LangGraph API 서버에 사용할 베이스 이미지. 기본값은 langchain/langgraph-api 또는 langchain/langgraphjs-api입니다. "langchain/langgraph-server:0.2"처럼 특정 버전으로 고정할 수 있습니다. 자세한 내용은 https://hub.docker.com/r/langchain/langgraph-server/tags 참고. (langgraph-cli==0.2.8에서 추가됨)
image_distro선택 사항. 베이스 이미지에 사용할 Linux 배포판. "debian", "wolfi", "bookworm", "bullseye" 중 하나여야 합니다. 생략 시 기본값은 "debian"입니다. langgraph-cli>=0.2.11에서 사용 가능.
env.env 파일 경로나 환경 변수와 값의 매핑.
storeBaseStore에 의미론적 검색 및/또는 TTL(Time-to-live)을 추가하는 설정. 다음 필드 포함:
  • index (선택): embed, dims, 선택적 fields 필드를 가진 의미론적 검색 인덱싱 설정.
  • ttl (선택): 항목 만료 설정. 선택적 필드: refresh_on_read(boolean, 기본값 true), default_ttl(float, 분 단위 수명; 신규 항목에만 적용; 기존 항목은 변경 없음; 기본값은 만료 없음), sweep_interval_minutes(integer, 만료 항목 확인 주기, 기본값 없음).
ui선택 사항. 에이전트가 내보내는 UI 컴포넌트의 명명된 정의로, 각각 JS/TS 파일을 가리킵니다. (langgraph-cli==0.1.84에서 추가됨)
python_version3.11, 3.12, 3.13 중 하나. 기본값은 3.11.
node_versionLangGraph.js를 사용하려면 node_version: 20을 지정하세요.
pip_config_filepip 설정 파일 경로.
pip_installer(v0.3에서 추가됨) 선택 사항. Python 패키지 설치 도구 선택자. "auto", "pip", "uv" 중 하나로 설정할 수 있습니다. 0.3 버전부터 기본 전략은 uv pip 실행이며, 더 빠른 빌드를 제공합니다. 드물게 uv가 의존성 그래프나 pyproject.toml 구조를 처리하지 못할 경우 "pip"로 지정해 이전 방식으로 되돌릴 수 있습니다.
keep_pkg_tools(v0.3.4에서 추가됨) 최종 이미지에 Python 패키징 도구(pip, setuptools, wheel)를 유지할지 제어합니다. 허용 값:
  • true : 세 도구 모두 유지(제거하지 않음).
  • false / 생략 : 세 도구 모두 제거(기본 동작).
  • list[str] : 유지할 도구 이름. 각 값은 “pip”, “setuptools”, “wheel” 중 하나여야 합니다.
. 기본적으로 세 도구 모두 제거됩니다.
dockerfile_lines부모 이미지 import 이후 Dockerfile에 추가할 라인 배열.
checkpointer체크포인터 설정. ttl 필드는 다음 키를 가진 객체:
  • strategy: 만료된 체크포인트 처리 방법(예: "delete").
  • sweep_interval_minutes: 만료 체크포인트 확인 주기(정수).
  • default_ttl: 체크포인트의 기본 TTL(분 단위, 정수); 신규 체크포인트/스레드에만 적용(기존 데이터 변경 없음). 지정된 전략이 적용되기 전까지 체크포인트가 유지되는 기간.
httpHTTP 서버 설정. 다음 필드 포함:
  • app: 커스텀 Starlette/FastAPI 앱 경로(예: "./src/agent/webapp.py:app"). 커스텀 라우트 가이드 참고.
  • cors: allow_origins, allow_methods, allow_headers 등 CORS 설정.
  • configurable_headers: 실행의 설정값으로 제외/포함할 요청 헤더 정의.
  • disable_assistants: /assistants 라우트 비활성화
  • disable_mcp: /mcp 라우트 비활성화
  • disable_meta: /ok, /info, /metrics, /docs 라우트 비활성화
  • disable_runs: /runs 라우트 비활성화
  • disable_store: /store 라우트 비활성화
  • disable_threads: /threads 라우트 비활성화
  • disable_ui: /ui 라우트 비활성화
  • disable_webhooks: 모든 라우트에서 실행 완료 시 웹훅 호출 비활성화
  • mount_prefix: 마운트된 라우트의 접두사(예: “/my-deployment/api”)
api_version(v0.3.7에서 추가됨) 사용할 LangGraph API 서버의 시맨틱 버전(예: "0.3"). 기본값은 최신 버전. 각 릴리스의 세부 사항은 서버 changelog 참고.

​
예시

  • Python
  • JS

​
기본 설정

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  }
}

​
Wolfi 베이스 이미지 사용

베이스 이미지의 Linux 배포판은 image_distro 필드로 지정할 수 있습니다. 허용 값은 debian, wolfi, bookworm, bullseye입니다. Wolfi는 더 작고 안전한 이미지를 제공하므로 권장됩니다. langgraph-cli>=0.2.11에서 사용 가능합니다.
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "image_distro": "wolfi"
}

​
store에 의미론적 검색 추가

모든 배포에는 DB 기반 BaseStore가 포함됩니다. langgraph.json에 “index” 설정을 추가하면 배포의 BaseStore에서 의미론적 검색을 사용할 수 있습니다.index.fields 설정은 문서의 어떤 부분을 임베딩할지 결정합니다:
  • 생략하거나 ["$"]로 설정하면 전체 문서가 임베딩됩니다
  • 특정 필드를 임베딩하려면 JSON 경로 표기법 사용: ["metadata.title", "content.text"]
  • 지정된 필드가 없는 문서도 저장되지만 해당 필드의 임베딩은 생성되지 않습니다
  • put 시 index 파라미터로 항목별로 임베딩 필드를 오버라이드할 수 있습니다
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}
주요 모델 차원
  • openai:text-embedding-3-large: 3072
  • openai:text-embedding-3-small: 1536
  • openai:text-embedding-ada-002: 1536
  • cohere:embed-english-v3.0: 1024
  • cohere:embed-english-light-v3.0: 384
  • cohere:embed-multilingual-v3.0: 1024
  • cohere:embed-multilingual-light-v3.0: 384

​
커스텀 임베딩 함수로 의미론적 검색

커스텀 임베딩 함수를 사용해 의미론적 검색을 하려면, 커스텀 임베딩 함수 경로를 지정할 수 있습니다:
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "./embeddings.py:embed_texts",
      "dims": 768,
      "fields": ["text", "summary"]
    }
  }
}
store 설정의 embed 필드는 문자열 리스트를 받아 임베딩 리스트를 반환하는 커스텀 함수를 참조할 수 있습니다. 예시 구현:
# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
    """Custom embedding function for semantic search."""
    # Implementation using your preferred embedding model
    return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors

​
커스텀 인증 추가

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false
  }
}
자세한 내용은 인증 개념 가이드와 커스텀 인증 설정 실습 가이드를 참고하세요.

​
Store 항목 TTL(Time-to-Live) 설정

BaseStore의 항목/메모리에 대한 기본 만료를 store.ttl 키로 설정할 수 있습니다. 항목이 마지막으로 접근된 후 얼마나 유지될지 결정합니다(refresh_on_read에 따라 읽기 시 타이머가 갱신될 수 있음). 이 기본값은 get, search 등 호출별로 오버라이드할 수 있습니다.ttl 설정은 선택적 필드를 가진 객체입니다:
  • refresh_on_read: true(기본값)이면 get 또는 search로 항목을 접근할 때 만료 타이머가 리셋됩니다. false로 설정하면 쓰기(put) 시에만 TTL이 갱신됩니다.
  • default_ttl: 항목의 기본 수명(분 단위). 신규 항목에만 적용되며, 기존 항목은 변경되지 않습니다. 설정하지 않으면 기본적으로 만료되지 않습니다.
  • sweep_interval_minutes: 시스템이 만료된 항목을 삭제하는 백그라운드 프로세스를 얼마나 자주 실행할지(분 단위). 설정하지 않으면 자동 스위핑이 발생하지 않습니다.
7일 TTL(10080분), 읽기 시 갱신, 1시간마다 스위핑하는 예시:
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080
    }
  }
}

​
체크포인트 TTL(Time-to-Live) 설정

체크포인트의 TTL은 checkpointer 키로 설정할 수 있습니다. 체크포인트 데이터가 지정된 전략(예: 삭제)에 따라 자동 처리되기 전까지 얼마나 유지될지 결정합니다. ttl 설정은 다음을 포함합니다:
  • strategy: 만료된 체크포인트에 적용할 동작(현재 "delete"만 허용).
  • sweep_interval_minutes: 시스템이 만료 체크포인트를 확인하는 주기(분 단위).
  • default_ttl: 체크포인트의 기본 수명(분 단위). 배포 후 생성된 체크포인트/스레드에만 적용되며, 기존 데이터는 변경되지 않습니다.
기본 TTL을 30일(43200분)로 설정하는 예시:
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}
이 예시에서는 30일이 지난 체크포인트가 삭제되며, 10분마다 확인합니다.

​
API 버전 고정(Pinning)

(v0.3.7에서 추가됨)LangGraph 서버의 API 버전을 api_version 키로 고정할 수 있습니다. 서버가 특정 API 버전을 사용하도록 보장하고 싶을 때 유용합니다. 기본적으로 클라우드 배포의 빌드는 최신 안정 버전을 사용합니다. api_version 키를 특정 버전으로 설정해 고정할 수 있습니다.
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "api_version": "0.2"
}

​
명령어

사용법
  • Python
  • JS
LangGraph CLI의 기본 명령어는 langgraph입니다.
langgraph [OPTIONS] COMMAND [ARGS]

​
dev

  • Python
  • JS
핫 리로딩 및 디버깅 기능을 갖춘 개발 모드로 LangGraph API 서버를 실행합니다. 이 경량 서버는 Docker 설치가 필요 없으며 개발 및 테스트에 적합합니다. 상태는 로컬 디렉터리에 저장됩니다.
현재 CLI는 Python >= 3.11만 지원합니다.
설치이 명령어는 “inmem” extra 설치가 필요합니다:
pip install -U "langgraph-cli[inmem]"
사용법
langgraph dev [OPTIONS]
옵션
옵션기본값설명
-c, --config FILElanggraph.json의존성, 그래프, 환경 변수를 선언하는 설정 파일 경로
--host TEXT127.0.0.1서버를 바인딩할 호스트
--port INTEGER2024서버를 바인딩할 포트
--no-reload자동 리로드 비활성화
--n-jobs-per-worker INTEGER워커당 작업 수. 기본값은 10
--debug-port INTEGER디버거가 수신할 포트
--wait-for-clientFalse서버 시작 전 디버거 클라이언트가 디버그 포트에 연결될 때까지 대기
--no-browser서버 시작 시 브라우저 자동 열기 생략
--studio-url TEXT연결할 Studio 인스턴스 URL. 기본값은 https://smith.langchain.com
--allow-blockingFalse코드 내 동기 I/O 블로킹 작업에 대해 오류 발생하지 않음 (0.2.6에서 추가됨)
--tunnelFalse원격 프론트엔드 접근을 위해 Cloudflare를 통한 공개 터널로 로컬 서버 노출. Safari 등 브라우저 또는 네트워크에서 localhost 연결 차단 문제 방지
--help명령어 문서 표시

​
build

  • Python
  • JS
LangSmith API 서버 Docker 이미지를 빌드합니다.사용법
langgraph build [OPTIONS]
옵션
옵션기본값설명
--platform TEXTDocker 이미지를 빌드할 대상 플랫폼. 예: langgraph build --platform linux/amd64,linux/arm64
-t, --tag TEXT필수. Docker 이미지 태그. 예: langgraph build -t my-image
--pull / --no-pull--pull최신 원격 Docker 이미지로 빌드. 로컬 빌드 이미지를 사용하려면 --no-pull 사용.
-c, --config FILElanggraph.json의존성, 그래프, 환경 변수를 선언하는 설정 파일 경로.
--build-command TEXT*빌드 명령어 실행. langgraph.json 파일이 있는 디렉터리에서 실행. 예: langgraph build --build-command "yarn run turbo build"
--install-command TEXT*설치 명령어 실행. langgraph build를 실행하는 디렉터리에서 실행. 예: langgraph build --install-command "yarn install"
--help명령어 문서 표시.
*JS 배포만 지원되며, Python 배포에는 영향 없음.

​
up

  • Python
  • JS
LangGraph API 서버를 시작합니다. 로컬 테스트에는 LangSmith 접근 권한이 있는 LangSmith API 키가 필요합니다. 프로덕션 사용에는 라이선스 키가 필요합니다.사용법
langgraph up [OPTIONS]
옵션
옵션기본값설명
--wait서비스가 시작될 때까지 대기 후 반환. —detach 암시적 적용
--base-image TEXTlangchain/langgraph-apiLangGraph API 서버에 사용할 베이스 이미지. 버전 태그로 특정 버전 고정 가능.
--image TEXTlanggraph-api 서비스에 사용할 Docker 이미지. 지정 시 빌드 생략하고 해당 이미지를 직접 사용.
--postgres-uri TEXT로컬 데이터베이스데이터베이스에 사용할 Postgres URI.
--watch파일 변경 시 재시작
--debugger-base-url TEXThttp://127.0.0.1:[PORT]디버거가 LangGraph API에 접근할 때 사용할 URL.
--debugger-port INTEGER디버거 이미지를 로컬로 풀링하고 지정한 포트에서 UI 제공
--verbose서버 로그에서 더 많은 출력 표시.
-c, --config FILElanggraph.json의존성, 그래프, 환경 변수를 선언하는 설정 파일 경로.
-d, --docker-compose FILE추가 서비스 실행을 위한 docker-compose.yml 파일 경로.
-p, --port INTEGER8123노출할 포트. 예: langgraph up --port 8000
--pull / --no-pullpull최신 이미지를 풀링. 로컬 빌드 이미지를 사용하려면 --no-pull 사용. 예: langgraph up --no-pull
--recreate / --no-recreateno-recreate설정이나 이미지가 변경되지 않아도 컨테이너 재생성
--help명령어 문서 표시.

​
dockerfile

  • Python
  • JS
LangSmith API 서버 Docker 이미지를 빌드하기 위한 Dockerfile을 생성합니다.사용법
langgraph dockerfile [OPTIONS] SAVE_PATH
옵션
옵션기본값설명
-c, --config FILElanggraph.json설정 파일 경로. 의존성, 그래프, 환경 변수 선언.
--help메시지 표시 후 종료.
예시:
langgraph dockerfile -c langgraph.json Dockerfile
생성되는 Dockerfile 예시:
FROM langchain/langgraph-api:3.11

ADD ./pipconf.txt /pipconfig.txt

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_community langchain_anthropic langchain_openai wikipedia scikit-learn

ADD ./graphs /deps/__outer_graphs/src
RUN set -ex && \
    for line in '[project]' \
                'name = "graphs"' \
                'version = "0.1"' \
                '[tool.setuptools.package-data]' \
                '"*" = ["**/*"]'; do \
        echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
    done

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'
langgraph dockerfile 명령어는 langgraph.json 파일의 모든 설정을 Dockerfile 명령어로 변환합니다. 이 명령어를 사용할 때는 langgraph.json 파일을 업데이트할 때마다 다시 실행해야 변경 사항이 Dockerfile 빌드/실행에 반영됩니다.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I