로컬 개발 & 테스트: langgraph dev vs langgraph up

Agent Server 애플리케이션을 로컬에서 개발하고 테스트하는 방법을 다룹니다. LangGraph CLI는 워크플로의 서로 다른 단계에 최적화된 두 개의 로컬 명령을 제공합니다.

langgraph dev — 빠른 반복을 위한 경량 개발 서버.
langgraph up — 검증을 위한 프로덕션과 유사한 테스트 환경.

출처: Local development & testing 공식 문서

기능	`langgraph dev`	`langgraph up`
Docker 필요	아니요	예
설치	`pip install langgraph-cli[inmem]`	`pip install langgraph-cli`
주 사용처	빠른 개발·테스트	프로덕션 유사 검증
상태 지속성	인메모리 + 로컬 디렉터리에 pickle	PostgreSQL
핫 리로드	예(기본)	선택(`--watch` 플래그)
기본 포트	`2024`	`8123`
리소스 사용량	가벼움	무거움(서버·PostgreSQL·Redis용 도커 컨테이너를 빌드·실행)
IDE 디버깅	내장 DAP 지원	일반 컨테이너 디버깅
커스텀 인증	예	예(라이선스 키 필요)

개발 워크플로

일반적인 작업 흐름은 개발 → 로컬 테스트 → 검증 → 배포 순서입니다.

일상 개발 — langgraph dev로 빠른 반복.
주기적 검증 — langgraph up으로 큰 변경 테스트.
배포 전 체크 — langgraph up --recreate로 새 빌드 실행.
배포 — LangSmith UI나 Control Plane API로 프로덕션에 푸시.

`langgraph dev`

langgraph dev는 활발한 개발 중 속도와 편의를 위해 설계된, 환경에서 직접 도는 경량 서버입니다.

Docker 불필요 — 환경에서 직접 실행.
핫 리로딩 — 코드를 바꾸면 자동 재로드.
빠른 시작 — 몇 초면 준비.
내장 DAP(Debug Adapter Protocol) 지원 — 서버에 IDE 디버거를 붙여 줄 단위 중단점·디버깅.
로컬 저장 — 상태는 로컬 디렉터리에 영속화.

dev 서버는 프로덕션과 같은 통합 테스트 스위트로 테스트되므로, 최소 리소스로 개발 중에도 동작이 동일함을 보장합니다.

시작해 보기

사전 준비: LangSmith API 키(무료 가입)와 Python용 uv 또는 TypeScript용 npx.

LangGraph 앱 생성 — new-langgraph-project-python 또는 new-langgraph-project-js 템플릿으로 생성:

uvx --from langgraph-cli@latest langgraph new path/to/your/app --template new-langgraph-project-python

의존성 설치:

cd path/to/your/app
uv sync --dev -U

Agent Server 실행:

uv run langgraph dev

샘플 출력:

>    Ready!
>
>    - API: http://localhost:2024
>
>    - Docs: http://localhost:2024/docs
>
>    - Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

API 테스트 — LangGraph Python SDK 설치 후 스레드 없는 run으로 메시지 전송:

pip install langgraph-sdk

from langgraph_sdk import get_client
import asyncio

client = get_client(url="http://localhost:2024")

async def main():
    async for chunk in client.runs.stream(
        None,  # Threadless run
        "agent", # Name of assistant. Defined in langgraph.json.
        input={
        "messages": [{
            "role": "human",
            "content": "What is LangGraph?",
            }],
        },
    ):
        print(f"Receiving new event of type: {chunk.event}...")
        print(chunk.data)
        print("\n\n")

asyncio.run(main())

사용 사례

일상 피처 개발 — 코드를 바꾸면 서버가 자동 재로드. 컨테이너 재빌드 없이 즉시 테스트.
빠른 프로토타이핑·실험 — Docker 셋업 없이 몇 초 만에 서버 기동.
Docker 없는 환경 — CI/CD 파이프라인이나 경량 VM에서: langgraph dev --no-browser
디버거 첨부 — --debug-port로 IDE 디버거를 붙여 단계별 디버깅.

`langgraph up`

langgraph up은 프로덕션 인프라를 흉내 내는 전체 Docker 기반 스택을 오케스트레이션합니다.

빌드·의존성 검증 — 빌드 프로세스와 의존성 테스트.
격리된 네트워킹 — 현실적인 컨테이너 네트워킹.
프로덕션 검증 — 배포 준비 상태 확인.

# Docker가 도는지 확인
docker ps

# 프로덕션 유사 스택 시작
langgraph up

서버는 전체 영속 저장소와 함께 http://localhost:8123에서 시작됩니다.

사용 사례

배포 전 검증 — 새 빌드로 최종 체크 실행: langgraph up --recreate — 컨테이너 안 의존성 해석과 빌드 문제를 잡아냄.
대형 피처 검증 — 큰 변경 후 주기적으로 전체 프로덕션 스택 테스트.
Docker 트러블슈팅 — 프로덕션에서만 나타나는 컨테이너 특유 문제·네트워킹·환경변수 디버깅.

배포 전 체크리스트

배포 전에 langgraph up으로 확인할 것:

모든 의존성이 컨테이너에 올바르게 설치되는지
애플리케이션이 오류 없이 시작되는지
그래프가 성공적으로 실행되는지
모든 환경변수가 올바르게 동작하는지
인증/권한 부여가 예상대로 동작하는지

의존성 설정

langgraph dev와 langgraph up 모두 설정 파일에서 애플리케이션 의존성을 읽지만, 다른 환경에서 실행합니다. langgraph dev는 Docker 없이 로컬 환경(Python/Node.js)에서 코드를 직접 실행하고, langgraph up은 Docker 컨테이너를 빌드해 그 격리된 컨테이너 안에서 실행합니다.

`langgraph.json` 파일

dependencies 필드는 CLI에 애플리케이션 코드가 어디 있는지를 알려줍니다. 패키지 설정(pyproject.toml, setup.py, requirements.txt, package.json)이 있는 디렉터리, 특정 하위 디렉터리("./my_agent"), 또는 특정 패키지("my-package==1.0.0")를 가리킬 수 있습니다.

{
  "dependencies": ["."],
  "graphs": {
    "my_agent": "./my_agent/agent.py:graph"
  },
  "env": "./.env"
}

패키지 의존성 파일(pyproject.toml, requirements.txt, package.json)은 애플리케이션이 필요한 무엇(what) 패키지를 정의합니다.

이 이중 파일 접근은 관심사를 분리합니다. langgraph.json은 애플리케이션 구조·위치를, 패키지 설정 파일은 언어별 패키지 의존성을 다룹니다.

의존성 해석 과정

langgraph up은 다음 단계로 의존성을 설치합니다.

langgraph.json이 코드를 어디에서 찾을지 알려줌(dependencies: ["."]는 현재 디렉터리).
그 디렉터리에서 패키지 설정 파일(pyproject.toml/requirements.txt/package.json)을 찾음.
설정 파일에서 패키지 목록을 읽음.
언어에 맞는 패키지 매니저(uv/pip, JavaScript는 npm)로 설치.

트러블슈팅

설치에 문제가 있으면 pip로 전환해 보세요.

{
  "dependencies": ["."],
  "pip_installer": "pip"
}

그리고 재빌드: langgraph up --recreate

로컬 Docker 셋업 디버깅

프로덕션 배포가 성공해도 로컬 langgraph up이 실패할 수 있습니다. 프로덕션은 관리형 인프라를 쓰는 반면 langgraph up은 전체 스택을 로컬에서 돌리기 때문입니다.

Docker 구성 문제 — langgraph up은 로컬 Docker 필요(docker ps로 확인). Cloud 배포는 로컬 Docker를 쓰지 않습니다. 해결: Docker 설치 또는 langgraph dev 사용.
포트 충돌 — langgraph up은 8123, 5432, 6379 포트 사용. lsof -i :8123 등으로 확인. 해결: 충돌 서비스 중지 또는 --port 플래그.
리소스 제약 — PostgreSQL·Redis·API 서버 컨테이너가 더 많은 RAM·디스크 필요. 해결: 리소스 확보 또는 langgraph dev 사용.
네트워크 구성 — VPN·방화벽·기업 프록시가 로컬 Docker 네트워킹에 영향. 해결: langgraph dev로 테스트하거나 VPN/방화벽을 잠시 꺼서 격리.

다음 단계

로컬에서 LangGraph 앱이 돌고 나면 배포할 준비가 된 것입니다.

호스팅 선택 — Cloud(가장 빠른 셋업, 완전 관리, 권장) 또는 Self-hosted(자체 인프라에서 완전 통제).
앱 배포 — 클라우드 배포 퀵스타트 또는 전체 Cloud 셋업 가이드.
기능 탐색 — Studio(시각화·상호작용·디버깅 UI), LangSmith Deployment API, Python/JS SDK.

더 알아보기 (Learn more)

CLI 모든 명령의 상세는 같은 허브의 LangGraph CLI 문서를 참고하세요.
애플리케이션 구조, Studio, 트러블슈팅도 공식 문서에서 이어집니다.

로컬 개발 & 테스트: langgraph dev vs langgraph up