Skip to main content
LangGraph CLI는 LangGraph API 서버를 로컬에서 빌드하고 실행하기 위한 커맨드라인 도구입니다. 생성된 서버는 실행, 스레드, 어시스턴트 등을 위한 모든 API 엔드포인트를 노출하며, 체크포인트 및 저장소를 위한 관리형 데이터베이스와 같은 지원 서비스를 포함합니다.

​
설치

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

​
주요 명령어

명령어수행 작업
langgraph dev경량 로컬 개발 서버를 시작합니다 (Docker 불필요). 빠른 테스트에 이상적입니다.
langgraph build배포를 위한 LangGraph API 서버의 Docker 이미지를 빌드합니다.
langgraph dockerfile사용자 정의 빌드를 위해 설정 파일에서 파생된 Dockerfile을 생성합니다.
langgraph upDocker에서 LangGraph API 서버를 로컬로 시작합니다. Docker 실행 필요; 로컬 개발을 위한 LangSmith API 키 필요; 프로덕션 사용을 위한 라이선스 필요.
JS의 경우 npx @langchain/langgraph-cli <command>를 사용하세요 (전역 설치 시 langgraphjs 사용).

​
설정 파일

LangGraph CLI는 이 스키마를 따르는 JSON 설정 파일이 필요합니다. 다음 속성들을 포함합니다:
LangGraph CLI는 기본적으로 현재 디렉터리의 langgraph.json 설정 파일을 사용합니다.
  • Python
  • JS
키설명
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입니다. 빌드를 특정 버전의 langgraph 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)를 추가하기 위한 설정. 다음 필드를 포함합니다:
  • 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: 체크포인트의 기본 수명 주기(분 단위) (정수); 새로 생성된 체크포인트/스레드에만 적용됨 (기존 데이터는 변경되지 않음). 지정된 전략이 적용되기 전에 체크포인트가 보관되는 기간을 정의합니다.
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"). 기본값은 최신입니다. 각 릴리스에 대한 자세한 내용은 서버 변경 로그를 확인하세요.

​
예제

  • Python
  • JS

​
기본 설정

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

​
Wolfi 베이스 이미지 사용

image_distro 필드를 사용하여 베이스 이미지의 Linux 배포판을 지정할 수 있습니다. 유효한 옵션은 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"]
  • 지정된 필드가 없는 문서도 여전히 저장되지만 해당 필드에 대한 임베딩은 없습니다
  • index 매개변수를 사용하여 put 시점에 특정 항목에 임베딩할 필드를 재정의할 수 있습니다
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}
Common model dimensions
  • 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 항목 수명 주기 설정

store.ttl 키를 사용하여 BaseStore의 항목/메모리에 대한 기본 데이터 만료를 설정할 수 있습니다. 이는 항목이 마지막으로 액세스된 후 얼마나 오래 보관되는지를 결정합니다 (refresh_on_read에 따라 읽기가 타이머를 새로 고칠 수 있음). 이러한 기본값은 get, search 등의 해당 인수를 수정하여 호출별로 재정의할 수 있습니다.ttl 설정은 다음 선택적 필드를 포함하는 객체입니다:
  • refresh_on_read: true(기본값)인 경우, get 또는 search를 통해 항목에 액세스하면 만료 타이머가 재설정됩니다. 쓰기(put)에서만 TTL을 새로 고치려면 false로 설정하세요.
  • default_ttl: 항목의 기본 수명(분 단위). 새로 생성된 항목에만 적용됩니다; 기존 항목은 수정되지 않습니다. 설정하지 않으면 항목은 기본적으로 만료되지 않습니다.
  • sweep_interval_minutes: 시스템이 만료된 항목을 삭제하기 위해 백그라운드 프로세스를 실행하는 빈도(분). 설정하지 않으면 자동으로 검색이 발생하지 않습니다.
다음은 7일 TTL(10080분)을 활성화하고, 읽기 시 새로 고치며, 매시간 검색하는 예입니다:
{
  "$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
    }
  }
}

​
체크포인트 수명 주기 설정

checkpointer 키를 사용하여 체크포인트의 수명 주기(TTL)를 설정할 수 있습니다. 이는 지정된 전략(예: 삭제)에 따라 자동으로 처리되기 전에 체크포인트 데이터가 보관되는 기간을 결정합니다. 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 버전 고정

(v0.3.7에 추가됨)api_version 키를 사용하여 LangGraph 서버의 API 버전을 고정할 수 있습니다. 서버가 특정 버전의 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” 추가 패키지가 설치되어야 합니다:
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 이미지로 빌드합니다. 로컬로 빌드된 이미지로 LangSmith API 서버를 실행하려면 --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