클라우드에 앱 배포하기: langgraph deploy 퀵스타트

이 퀵스타트는 langgraph deploy 명령으로 애플리케이션을 LangSmith Cloud(AWS·GCP)에 배포하는 방법을 보여줍니다. langgraph.json 설정에서 그래프를 내보내는 앱이면 어떤 프레임워크로 만들었든 똑같이 배포됩니다.

출처: Deploy your app to cloud 공식 문서

참고: langgraph deploy 명령은 현재 베타 단계입니다.

사전 준비

Plus 플랜 이상의 LangSmith 계정과 API 키
(선택) Docker — 로컬 빌드용. 원격 빌드에는 불필요. Docker가 없으면 langgraph deploy가 자동으로 원격 빌드를 수행.
(선택) Apple Silicon(M1/M2/M3) — 로컬 빌드에서 linux/amd64 크로스컴파일용 Docker Buildx
LangGraph CLI 설치:

uv tool install langgraph-cli

1. 배포 가능한 앱 만들기

langgraph deploy는 langgraph.json이 그래프를 내보내는 어떤 프로젝트든 배포합니다.

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

langgraph new path/to/your/app --template new-langgraph-project-python
cd path/to/your/app

--template 없이 langgraph new를 실행하면 사용 가능한 템플릿의 인터랙티브 메뉴가 나옵니다.

Bring your own framework — Claude Agent SDK, Strands, CrewAI, AutoGen, Google ADK로 만든 에이전트도 langgraph.json에서 그래프를 노출하기만 하면 같은 CLI로 배포됩니다.

2. API 키 설정

프로젝트 루트의 .env 파일에 LangSmith API 키를 넣습니다.

LANGSMITH_API_KEY=lsv2_...

langgraph deploy가 자동으로 읽습니다. 아니면 인라인으로 넘길 수도 있습니다.

LANGSMITH_API_KEY=lsv2_... langgraph deploy

3. 배포

CLI나 UI에서 배포할 수 있습니다.

CLI로 배포 — 프로젝트 디렉터리에서 실행:

langgraph deploy

이 명령은 기본적으로 프로젝트 디렉터리 이름의 Serverless 배포를 만듭니다. 이름이나 유형을 바꾸려면 --name 또는 --deployment-type dedicated를 쓰세요. 코드를 바꾼 뒤 재실행하면 이름으로 기존 배포를 찾아 그 자리에 갱신합니다. langgraph deploy list로 전체 목록, langgraph deploy logs로 런타임 로그, langgraph deploy delete <ID>로 배포 삭제도 가능합니다.

Studio로 배포 — 로컬 개발 서버를 시작하면 Studio(인터랙티브 에이전트 IDE)가 자동 열립니다.

langgraph dev

그리고 deploy 버튼을 클릭합니다.

4. Studio에서 테스트

Studio는 배포에 직접 연결된 인터랙티브 에이전트 IDE입니다. 코드를 작성하지 않고 메시지를 보내고, 각 노드의 중간 상태를 검사하고, run 도중 상태를 편집하고, 이전 체크포인트에서 재생할 수 있습니다. Deployment가 준비되면 LangSmith 왼쪽 사이드바에서 Deployments를 선택하고, 배포를 골라 세부 정보를 본 뒤, 우측 상단 Studio를 클릭합니다.

5. API 테스트

배포 세부 정보에서 API URL을 복사해 애플리케이션을 호출합니다.

Python SDK (async)

pip install langgraph-sdk

from langgraph_sdk import get_client

client = get_client(url="your-deployment-url", api_key="your-langsmith-api-key")

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

JavaScript SDK

npm install @langchain/langgraph-sdk

const { Client } = await import("@langchain/langgraph-sdk");

const client = new Client({ apiUrl: "your-deployment-url", apiKey: "your-...key" });

const streamResponse = client.runs.stream(
    null, // Threadless run
    "agent", // Assistant ID
    {
        input: {
            "messages": [
                { "role": "user", "content": "Say hello."}
            ]
        },
        streamMode: "messages",
    }
);

for await (const chunk of streamResponse) {
    console.log(`Receiving new event of type: ${chunk.event}...`);
    console.log(JSON.stringify(chunk.data));
    console.log("\n\n");
}

REST API

curl -s --request POST \
    --url <DEPLOYMENT_URL>/runs/stream \
    --header 'Content-Type: application/json' \
    --header "X-Api-Key: *** API KEY>" \
    --data "{
        \"assistant_id\": \"agent\",
        \"input\": {
            \"messages\": [
                {
                    \"role\": \"human\",
                    \"content\": \"Say hello.\"
                }
            ]
        },
        \"stream_mode\": \"updates\"
    }"

다음 단계

Assistants — 같은 그래프를 어시스턴트별로 다른 모델·프롬프트·도구로 배포.
Threads — 여러 run에 걸쳐 상태를 유지해 에이전트가 상호작용 사이 컨텍스트를 기억하게.
Runs — 장시간 작업용 백그라운드 run을 시작하고 결과를 클라이언트로 스트리밍.

더 알아보기 (Learn more)

GitHub 기반 배포와 전체 설정 옵션은 같은 허브의 LangSmith Cloud 배포 가이드를 참고하세요.
로컬에서 langgraph dev로 먼저 개발·테스트하는 법은 로컬 개발/테스트 가이드에서 이어집니다.