LangGraph CLI: 로컬에서 서버를 빌드·실행하는 커맨드라인 도구

LangGraph CLI는 Agent Server를 로컬에서 빌드하고 실행하는 커맨드라인 도구입니다. 결과 서버는 runs·threads·assistants 등의 모든 API 엔드포인트를 노출하며, 체크포인팅·저장을 위한 관리형 데이터베이스 같은 지원 서비스를 포함합니다.

출처: LangGraph CLI 공식 문서

설치

Docker 설치 확인(docker --version).
CLI 설치:

pip install langgraph-cli

JavaScript는 npx @langchain/langgraph-cli(주문형 최신) 또는 npm install -g @langchain/langgraph-cli(전역, langgraphjs로 사용). 3. 설치 확인: langgraph --help (JS는 npx @langchain/langgraph-cli --help).

주요 명령

명령	역할
`langgraph dev`	Docker 불필요한 경량 로컬 개발 서버. 빠른 테스트에 적합.
`langgraph build`	배포용 LangGraph API 서버의 Docker 이미지 빌드.
`langgraph deploy`	LangGraph 이미지를 빌드해 한 번에 LangSmith Deployments로 배포.
`langgraph dockerfile`	커스텀 빌드를 위해 설정에서 파생된 Dockerfile 생성.
`langgraph up`	Docker 안에서 LangGraph API 서버를 로컬로 시작. 개발에 LangSmith API 키, 프로덕션에 라이선스 필요.

설정 파일 (langgraph.json)

종합 앱을 빌드·실행하려면 LangGraph CLI가 JSON 설정 파일을 요구합니다. 기본 파일명은 langgraph.json이고 현재 디렉터리에서 찾습니다. 주요 필드:

dependencies (필수) — 의존성 배열. "."(로컬 Python 패키지 탐색), pyproject.toml/setup.py/requirements.txt가 있는 디렉터리 경로, 또는 패키지 이름.
graphs (필수) — 그래프 ID에서 컴파일된 그래프 또는 그래프를 만드는 함수가 정의된 경로로의 매핑. 예: ./your_package/your_file.py:variable(CompiledStateGraph 인스턴스) 또는 ./your_package/your_file.py:make_graph(config dict를 받아 StateGraph/CompiledStateGraph를 반환하는 함수).
auth — 인증 핸들러 경로(예: ./your_package/auth.py:auth, v0.0.11+).
base_image — API 서버 기본 이미지. 기본 langchain/langgraph-api(JS는 langchain/langgraphjs-api). 특정 버전으로 고정 가능(0.2.8+).
image_distro — 기본 이미지의 Linux 배포판. debian(기본), wolfi, bookworm, bullseye 중 하나(0.2.11+).
env — .env 파일 경로 또는 환경변수→값 매핑.
store — BaseStore에 시맨틱 검색·TTL 추가 구성.
ui — 에이전트가 내보내는 UI 컴포넌트의 이름 정의(각각 JS/TS 파일 가리킴, 0.1.84+).
python_version — 3.11(기본), 3.12, 3.13.
node_version — node_version: 20으로 LangGraph.js 사용.
pip_config_file / pip_installer — pip 설정 파일 경로, "auto"/"pip"/"uv"(0.3+는 기본 uv pip, 문제 시 "pip"로).
keep_pkg_tools — 최종 이미지에 Python 패키징 도구(pip, setuptools, wheel) 유지 여부(0.3.4+). 기본은 모두 제거.
dockerfile_lines — 부모 이미지 import 뒤 Dockerfile에 추가할 줄 배열.
checkpointer — backend("default"/"mongo"/"custom", 기본 PostgreSQL), path(커스텀 팩토리), ttl, serde 구성.
http — HTTP 서버 구성: 커스텀 Starlette/FastAPI 앱(app), CORS, configurable/logging 헤더, 미들웨어 순서(auth_first/middleware_first), 커스텀 라우트 인증, 라우트 비활성 플래그(disable_meta, disable_assistants, disable_runs, disable_threads, disable_store, disable_ui, disable_mcp, disable_a2a, disable_webhooks), mount_prefix.
webhooks — 나가는(아웃바운드) 웹훅 전달 구성: env_prefix(기본 LG_WEBHOOK_), headers, URL 검증 정책(0.5.36+).
api_version — 사용할 LangGraph API 서버 시맨틱 버전(예: "0.3"). 기본은 최신(0.3.7+).

설정 예시

기본 구성:

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

Wolfi 기본 이미지(더 작고 안전):

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

store에 시맨틱 검색 추가:

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}

index.fields는 문서의 어떤 부분을 임베딩할지 결정합니다. 생략하거나 ["$"]면 전체 문서를, JSON path 표기(["metadata.title", "content.text"])로 특정 필드를 임베딩합니다. embed는 문자열 목록을 받아 임베딩 목록을 반환하는 커스텀 함수 경로를 가리킬 수도 있습니다.

커스텀 인증:

{
  "$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(7일 = 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
    }
  }
}

checkpoint TTL(30일 = 43200분, 10분마다 체크):

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}

HTTP 미들웨어·헤더 커스터마이즈(커스텀 CORS):

{
  "...": "...",
  "http": {
    "cors": {
      "allow_origins": ["https://example.com", "https://app.example.com"],
      "allow_methods": ["GET", "POST"],
      "allow_headers": ["Authorization", "Content-Type"],
      "allow_credentials": true,
      "allow_origin_regex": "^https://.*\\.example\\.com$",
      "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"],
      "max_age": 600
    }
  }
}

웹훅 구성:

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "webhooks": {
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
    },
    "url": {
      "allowed_domains": ["*.mycompany.com"],
      "require_https": true
    }
  }
}

API 버전 고정:

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

내장 라우트 비활성화:

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

disable_meta: true는 /(루트 헬스), /info(버전·구성), /metrics(Prometheus·JSON), /docs(API 문서 UI), /openapi.json을 비활성화합니다. /ok 헬스 체크 엔드포인트는 남아 있어 Kubernetes 같은 오케스트레이터가 liveness·readiness 프로브를 할 수 있습니다.

명령 상세

기본 명령은 Python langgraph, JS langgraphjs(npx @langchain/langgraph-cli). 용법: langgraph [OPTIONS] COMMAND [ARGS].

`dev`

핫 리로딩·디버깅 기능을 가진 개발 모드로 LangGraph API 서버 실행. 이 경량 서버는 Docker 설치가 필요 없고 상태는 로컬 디렉터리에 영속화됩니다. "inmem" extra 설치 필요:

pip install -U "langgraph-cli[inmem]"

주요 옵션: -c/--config(기본 langgraph.json), --host(기본 127.0.0.1), --port(기본 2024), --no-reload, --n-jobs-per-worker(기본 10), --debug-port, --wait-for-client, --no-browser, --studio-url, --allow-blocking, --tunnel(Cloudflare 공용 터널로 원격 프론트엔드 접근).

현재 CLI는 Python 3.11 이상만 지원합니다.

`build`

LangSmith API 서버 Docker 이미지 빌드.

langgraph build -t my-image

주요 옵션: --platform(예: linux/amd64,linux/arm64), -t/--tag(필수), --pull/--no-pull, -c/--config. JS 전용 --build-command, --install-command.

`deploy`

LangGraph 이미지를 빌드해 한 번에 LangSmith Deployments로 배포(베타). 로컬에서 Docker 이미지를 빌드하고 관리형 레지스트리로 푸시한 뒤 배포를 만들거나 갱신합니다. Docker가 없으면 원격 빌드를 트리거합니다. LangSmith Cloud에서만 동작합니다.

langgraph deploy
LANGSMITH_API_KEY=lsv2_... langgraph deploy
langgraph deploy --name my-agent --deployment-type dedicated

주요 옵션: --api-key(LANGGRAPH_HOST_API_KEY/LANGSMITH_API_KEY/LANGCHAIN_API_KEY 또는 .env로도), --name(기본 현재 디렉터리명, LANGSMITH_DEPLOYMENT_NAME 가능), --deployment-id, --deployment-type(새 과금제는 serverless/dedicated, 구 과금제 조직은 dev/prod), --remote/--no-remote, --no-wait, --verbose.

하위 명령: deploy list(배포 목록, --name-contains), deploy revisions list <ID>(개정 목록, --limit 기본 10), deploy delete <ID>(--force로 확인 생략), deploy logs(런타임 로그, -f follow·--start-time/--end-time·-q 검색·--limit 기본 100·--level·--type deploy|build).

`up`

LangGraph API 서버 시작. 로컬 테스트엔 LangSmith 접근 권한이 있는 API 키가, 프로덕션엔 라이선스 키가 필요합니다.

langgraph up

주요 옵션: --wait(서비스 시작까지 대기), --base-image(기본 langchain/langgraph-api), --image(지정 시 빌드 스킵), --postgres-uri, --watch, --debugger-base-url, --debugger-port, --verbose, -c/--config, -d/--docker-compose, -p/--port(기본 8123), --pull/--no-pull, --recreate/--no-recreate.

더 알아보기 (Learn more)

langgraph dev와 langgraph up을 언제 쓸지의 상세 비교는 같은 허브의 로컬 개발/테스트 가이드를 참고하세요.
클라우드로 바로 배포하는 법은 클라우드 배포 퀵스타트에서 이어집니다.