로컬 서버 실행하기

LangGraph 애플리케이션을 실제로 돌려보려면 먼저 로컬 환경에서 서버를 띄울 수 있어야 해요. 이번 가이드에서는 langgraph-cli를 설치하고, 템플릿으로 앱을 만든 뒤 langgraph dev 명령으로 로컬 서버를 실행하는 전체 과정을 차근차근 따라가 볼게요. 개발용 인메모리 서버라서 빠르게 시작해 실험하기에 딱 좋아요.

출처: 문서

본문

사전 준비 (Prerequisites)

시작하기 전에 필요한 게 하나 있어요.

LangSmith의 API 키 — 무료로 가입할 수 있어요.

1. LangGraph CLI 설치

# Python >= 3.11 is required.
pip install -U "langgraph-cli[inmem]"

uv를 쓴다면 아래처럼 설치하면 돼요.

# Python >= 3.11 is required.
uv add "langgraph-cli[inmem]"

2. LangGraph 앱 만들기

new-langgraph-project-python 템플릿으로 새 앱을 만들어요. 이 템플릿은 단일 노드 애플리케이션을 보여주는데, 여기에 여러분만의 로직을 붙여 확장하면 돼요.

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

추가 템플릿 (Additional templates) 템플릿을 지정하지 않고 langgraph new를 실행하면 사용 가능한 템플릿 목록에서 고를 수 있는 인터랙티브 메뉴가 나타나요.

3. 의존성 설치

새 LangGraph 앱의 루트에서 edit 모드로 의존성을 설치해요. 그래야 로컬에서 수정한 내용이 서버에 바로 반영돼요.

cd path/to/your/app
pip install -e .

uv를 쓴다면:

cd path/to/your/app
uv sync

4. `.env` 파일 만들기

새 LangGraph 앱의 루트에 .env.example이 있어요. .env 파일을 만들고 .env.example의 내용을 복사한 뒤 필요한 API 키를 채워 넣으면 돼요.

LANGSMITH_API_KEY=lsv2...

5. Agent 서버 실행

langgraph dev 명령으로 LangGraph API 서버를 로컬에서 시작해요.

langgraph dev

기대할 수 있는 출력 예시는 아래와 같아요.

INFO:langgraph_api.cli:

        Welcome to

╦  ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬
║  ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤
╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴  ┴ ┴

- 🚀 API: http://127.0.0.1:2024
- 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- 📚 API Docs: http://127.0.0.1:2024/docs

This in-memory server is designed for development and testing.
For production use, please use LangSmith Deployment.

langgraph dev는 Agent Server를 인메모리 모드로 실행해요. 이 모드는 개발·테스트에 적합해요. 프로덕션에선 영구 스토리지 백엔드에 접근할 수 있는 환경에서 Agent Server를 배포해야 하죠. 자세한 내용은 Platform 설정 개요를 참고해요.

6. Studio에서 애플리케이션 테스트

Studio는 LangGraph API 서버에 연결해 애플리케이션을 시각화하고, 상호작용하며, 디버깅할 수 있는 전용 UI예요. langgraph dev 실행 결과로 나온 URL을 방문해 Studio에서 그래프를 테스트해 보세요.

>    - LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

Agent Server가 커스텀 호스트/포트에서 실행 중이라면 URL의 baseUrl 쿼리 파라미터를 바꾸면 돼요. 예를 들어 서버가 http://myhost:3000에서 실행 중이라면:

https://smith.langchain.com/studio/?baseUrl=http://myhost:3000

Safari 호환성 (Safari compatibility) Safari는 localhost 서버 연결에 제약이 있어서, 명령에 --tunnel 플래그를 붙여 보안 터널을 만들 수 있어요.

langgraph dev --tunnel

7. API 테스트

Python SDK (async)

LangGraph Python SDK를 설치해요.
```
pip install langgraph-sdk
```

어시스턴트에게 메시지를 보내요. (threadless run)

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())

Python SDK (sync)

LangGraph Python SDK를 설치해요.
```
pip install langgraph-sdk
```

어시스턴트에게 메시지를 보내요. (threadless run)

from langgraph_sdk import get_sync_client

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

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?",
    }],
    },
    stream_mode="messages-tuple",
):
    print(f"Receiving new event of type: {chunk.event}...")
    print(chunk.data)
    print("\n\n")

Rest API

curl -s --request POST \
    --url "http://localhost:2024/runs/stream" \
    --header 'Content-Type: application/json' \
    --data "{
        \"assistant_id\": \"agent\",
        \"input\": {
            \"messages\": [
                {
                    \"role\": \"human\",
                    \"content\": \"What is LangGraph?\"
                }
            ]
        },
        \"stream_mode\": \"messages-tuple\"
    }"

다음 단계 (Next steps)

이제 LangGraph 앱이 로컬에서 돌아가요. 배포와 고급 기능을 살펴보며 한 걸음 더 나아가 보세요.

Deployment quickstart: LangSmith로 LangGraph 앱을 배포해요.
LangSmith: LangSmith의 기초 개념을 배워요.
SDK Reference: SDK API 레퍼런스를 살펴봐요.

더 알아보기 (Learn more)

Deployment quickstart: 로컬에서 만든 앱을 실제로 배포하는 방법을 다뤄요.
LangSmith: LangSmith의 핵심 개념과 관찰 가능성(observability) 기능을 설명해요.

로컬 서버 실행하기