로컬 서버 실행하기

로컬 서버 실행하기 (Run a local server)

이 가이드는 LangGraph 애플리케이션을 로컬에서 실행하는 방법을 보여줘요. langgraph dev 명령으로 인메모리 에이전트 서버를 띄우고, Studio에서 그래프를 시각화·디버깅하며, SDK나 REST API로 직접 통신해 보는 흐름이에요.

출처: 공식문서

사전 준비 (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

추가 템플릿: 템플릿 없이 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. 에이전트 서버 실행

로컬에서 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 명령은 에이전트 서버를 인메모리 모드로 시작해요. 이 모드는 개발·테스트에 적합합니다. 프로덕션용으로는 영구 저장소 백엔드에 접근하는 에이전트 서버를 배포하세요. 자세한 내용은 Platform setup overview를 참고해요.

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

Studio는 LangGraph API 서버에 연결해서 애플리케이션을 로컬에서 시각화·상호작용·디버깅할 수 있는 특수 UI예요. langgraph dev 명령 출력의 URL을 방문해 그래프를 테스트해요.

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

커스텀 호스트/포트에서 실행되는 에이전트 서버가 있다면 URL의 baseUrl 쿼리 파라미터를 바꾸면 돼요. 예를 들어 서버가 http://myhost:3000에서 돌고 있다면:

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

Safari 호환성: Safari는 localhost 서버 연결에 제약이 있어서, 보안 터널을 만들려면 명령에 --tunnel 플래그를 쓰세요.

langgraph dev --tunnel

7. API 테스트

Python SDK (비동기)

  1. LangGraph Python SDK 설치:
pip install langgraph-sdk
  1. 어시스턴트에 메시지 보내기 (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 (동기)

  1. SDK 설치 후:
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 앱이 로컬에서 실행되니, 배포와 고급 기능을 살펴볼 차례예요.

더 알아보기 (Learn more)