독립형 Agent Server 배포

독립형 Agent Server 배포 (Self-host standalone servers)

제어 평면 없이 Docker, Docker Compose, 또는 Kubernetes로 독립형 Agent Server를 직접 배포하는 방법을 설명해요. 운영 준비가 됐고, 에이전트를 돌리는 가장 가벼운 옵션이기도 합니다.

출처: 독립형 Agent Server 배포 (Self-host standalone servers)

서버를 독립적으로 배포하면서도 트레이싱은 LangSmith(자체호스팅 또는 Cloud)로 보내 옵저버빌리티와 평가를 계속 활용할 수 있어요.

개요

Agent Server와 그 뒷단 서비스(PostgreSQL, Redis 등)로 이루어진 단순화된 데이터 평면을 여러분이 관리합니다.

컴포넌트 책임 실행 위치 관리 주체
제어 평면 해당 없음 해당 없음 해당 없음
데이터 평면 Agent Server / Postgres·Redis 등 자체 인프라 여러분

이 옵션은 스케일링과 배포, CI/CD 파이프라인을 완전히 통제하면서, 원하면 LangSmith와 통합해 트레이싱·평가를 쓸 수 있게 해줍니다.

경고 — 독립형 서버를 서버리스 환경에서는 운영하지 마세요. 규모 0으로 스케일링되면 태스크가 유실될 수 있고, 스케일업도 안정적으로 동작하지 않아요.

워크플로

  1. langgraph-cli 또는 Studio로 그래프를 로컬에서 정의하고 테스트해요.
  2. 에이전트를 Docker 이미지로 패키징합니다.
  3. 선택한 컴퓨트 플랫폼(Kubernetes, Docker, VM)에 Agent Server를 배포해요.
  4. 선택 사항으로 트레이스와 평가를 LangSmith(자체호스팅 또는 SaaS)로 보고하도록 API 키와 엔드포인트를 구성합니다.

지원 컴퓨트 플랫폼

  • Kubernetes — LangSmith Helm 차트로 Kubernetes 클러스터에서 Agent Server를 운영. 운영 등급 배포에서 권장하는 옵션이에요.
  • Docker — Docker를 지원하는 어떤 컴퓨트 플랫폼(로컬 개발 머신, VM, ECS 등)에서든 실행. 개발 또는 소규모 워크로드에 적합.

경고 (운영 배포 주의) — 운영에는 유지 관리되는 LangSmith Helm 차트를 쓰세요. LangChain이 정기적으로 테스트하는 운영 경로가 바로 이것입니다. 다른 오케스트레이터는 정기 테스트 대상이 아니에요.

Kubernetes가 아닌 배포에는 직접 구현하고 유지해야 하는 알려진 공백이 있습니다. Helm 차트가 발전하면서 이들 배포는 테스트된 운영 경로에서 더 멀어질 수 있어요.

  • 독립 큐 자동스케일링 — 버스트가 많은 쓰기 부하 워크로드용 스케일링 정책과 큐 메트릭 구성.
  • 우아한 런 드레이닝 — 배포·스케일다운 이벤트 때 진행 중 런이 끝나도록 종료 드레이닝과 충분한 종료 윈도우 구성.
  • 분리 모드 배선 — 별도 API·큐 서비스의 프로비저닝과 연결. Helm 차트는 queue.enabled가 true일 때 이를 처리합니다.
  • 참조 스케일링 설정 — Agent Server 스케일링 설정(api.replicas, queue.replicas, numberOfJobsPerWorker, 읽기 레플리카 포함)을 오케스트레이터 태스크 정의와 스케일링 정책으로 옮김.
  • 버전 업그레이드와 지원 — 태스크 정의 유지와 버전 업데이트 적용. LangChain은 지원되는 Helm 차트 버전 업데이트를 테스트하고 제공합니다.

사전 준비

  1. LangGraph CLI로 애플리케이션을 로컬에서 테스트해요.

  2. LangGraph CLI로 Docker 이미지를 빌드합니다 (예: langgraph build).

  3. 데이터 평면 배포에는 다음 환경 변수가 필요해요.

  4. REDIS_URI: Redis 인스턴스 연결 정보. Redis는 백그라운드 런의 실시간 출력을 스트리밍하기 위한 pub-sub 브로커로 사용돼요. 값은 유효한 Redis 연결 URI여야 합니다.

    공유 Redis 인스턴스 — 여러 자체호스팅 배포가 같은 Redis 인스턴스를 공유할 수 있어요. 예를 들어 Deployment A는 REDIS_URI를 redis://<hostname_1>:<port>/1로, Deployment B는 redis://<hostname_1>:<port>/2로 설정할 수 있습니다. 1과 2는 같은 인스턴스 안의 서로 다른 DB 번호이고 <hostname_1>은 공유돼요. 같은 DB 번호를 서로 다른 배포에 함께 쓸 수 없습니다.

  5. DATABASE_URI: Postgres 연결 정보. Postgres는 assistants·threads·runs를 저장하고, 스레드 상태와 장기 메모리를 유지하며, '정확히 한 번(exactly once)' 의미론으로 백그라운드 태스크 큐 상태를 관리해요. 값은 유효한 Postgres 연결 URI여야 합니다.

    공유 Postgres 인스턴스 — 여러 자체호스팅 배포가 같은 Postgres 인스턴스를 공유할 수 있어요. 예를 들어 Deployment A는 DATABASE_URI를 postgres://<user>:***@/<database_name_1>?host=<hostname_1>으로, Deployment B는 postgres://<user>:***@/<database_name_2>?host=<hostname_1>으로 설정할 수 있습니다. <database_name_1>과 database_name_2는 같은 인스턴스 안의 서로 다른 DB이고 <hostname_1>은 공유돼요. 같은 DB를 서로 다른 배포에 함께 쓸 수 없습니다.

    참고 — 체크포인트 데이터는 PostgreSQL 대신 MongoDB에 저장할 수도 있어요. 다른 모든 서버 데이터에는 여전히 PostgreSQL이 필요합니다. 자세한 내용은 Configure checkpointer backend를 보세요.

  6. LANGSMITH_API_KEY: LangSmith API 키.

  7. LANGGRAPH_CLOUD_LICENSE_KEY: LangSmith 라이선스 키. 서버 시작 시 한 번 인증에 사용됩니다.

  8. LANGSMITH_ENDPOINT: 자체호스팅 LangSmith 인스턴스로 트레이스를 보내려면 LANGSMITH_ENDPOINT를 그 인스턴스의 호스트네임으로 설정해요. URL에 마지막 슬래시를 붙이지 마세요 — 인증 오류를 일으킬 수 있어요.

  9. 네트워크에서 https://beacon.langchain.com으로의 이그레스. 에어갭 모드가 아니라면 라이선스 검증과 사용 보고에 필요합니다. Egress 문서를 참고하세요.

참고 — Agent Server 서비스는 0.14.0부터 기본적으로 IPv4와 IPv6 모두에서 리슨합니다. 듀얼 스택 클러스터는 추가 설정이 필요 없어요. 단일 주소 패밀리로 리슨하려면 LANGGRAPH_SERVER_HOST를 IPv4 전용이면 0.0.0.0, IPv6 전용이면 ::로 설정하세요. Self-hosted Agent Server 환경 변수 참고.

Kubernetes

이 Helm 차트로 Kubernetes 클러스터에 Agent Server를 배포하세요. 운영 독립형 배포에는 권장되는 설정입니다.

Helm 차트(v0.2.6+)는 번들 인스턴스(개발/테스트) 또는 외부 배포(운영)로 MongoDB 체크포인팅을 지원합니다. values 파일에서 mongo.enabled: true를 설정하세요. 전체 구성은 Configure checkpointer backend를 참고해요.

Docker

경고 — 이 Docker 예제는 로컬 개발·테스트용입니다. 운영에는 Kubernetes 배포를 사용하세요.

다음 docker 명령을 실행합니다.

docker run \
    --env-file .env \
    -p 8123:8000 \
    -e REDIS_URI="foo" \
    -e DATABASE_URI="bar" \
    -e LANGSMITH_API_KEY="baz" \
    my-image

참고 — my-image를 사전 준비 단계에서 langgraph build로 만든 이미지 이름으로 바꾸고, REDIS_URI, DATABASE_URI, LANGSMITH_API_KEY에 알맞은 값을 넣어야 해요. 추가 환경 변수가 필요하면 비슷한 방식으로 전달하면 됩니다.

Docker Compose

경고 — 이 Docker Compose 예제는 로컬 개발·테스트용입니다. 운영에는 Kubernetes 배포를 사용하세요.

다음 Docker Compose 파일을 사용합니다.

volumes:
    langgraph-data:
        driver: local
services:
    langgraph-redis:
        image: redis:6
        healthcheck:
            test: redis-cli ping
            interval: 5s
            timeout: 1s
            retries: 5
    langgraph-postgres:
        image: postgres:16
        ports:
            - "5432:5432"
        environment:
            POSTGRES_DB: postgres
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
        volumes:
            - langgraph-data:/var/lib/postgresql/data
        healthcheck:
            test: pg_isready -U postgres
            start_period: 10s
            timeout: 1s
            retries: 5
            interval: 5s
    langgraph-api:
        image: ${IMAGE_NAME}
        ports:
            - "8123:8000"
        depends_on:
            langgraph-redis:
                condition: service_healthy
            langgraph-postgres:
                condition: service_healthy
        env_file:
            - .env
        environment:
            REDIS_URI: redis://langgraph-redis:6379
            LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
            DATABASE_URI: postgres://postgres:***@langgraph-postgres:5432/postgres?sslmode=disable

이 파일을 같은 폴더에 두고 docker compose up을 실행하세요.

MongoDB 체크포인팅과 함께 쓰기

체크포인트를 PostgreSQL 대신 MongoDB에 저장하려면 MongoDB 서비스를 추가하고 체크포인터 백엔드를 구성하세요. langgraph.json에서 백엔드를 "mongo"로 설정하거나 LS_DEFAULT_CHECKPOINTER_BACKEND 환경 변수를 사용합니다. 다른 모든 서버 데이터에는 여전히 PostgreSQL이 필요해요.

volumes:
    langgraph-data:
        driver: local
    langgraph-mongo-data:
        driver: local
services:
    langgraph-redis:
        image: redis:6
        healthcheck:
            test: redis-cli ping
            interval: 5s
            timeout: 1s
            retries: 5
    langgraph-postgres:
        image: postgres:16
        ports:
            - "5432:5432"
        environment:
            POSTGRES_DB: postgres
            POSTGRES_USER: postgres
            POSTGRES_PASSWORD: postgres
        volumes:
            - langgraph-data:/var/lib/postgresql/data
        healthcheck:
            test: pg_isready -U postgres
            start_period: 10s
            timeout: 1s
            retries: 5
            interval: 5s
    langgraph-mongo:
        image: mongo:7
        command: ["mongod", "--replSet", "rs0"]
        ports:
            - "27017:27017"
        volumes:
            - langgraph-mongo-data:/data/db
        healthcheck:
            test: mongosh --eval "try { rs.status().ok } catch(e) { rs.initiate({_id:'rs0',members:[{_id:0,host:'langgraph-mongo:27017'}]}).ok }" --quiet
            interval: 5s
            timeout: 10s
            retries: 10
            start_period: 10s
    langgraph-api:
        image: ${IMAGE_NAME}
        ports:
            - "8123:8000"
        depends_on:
            langgraph-redis:
                condition: service_healthy
            langgraph-postgres:
                condition: service_healthy
            langgraph-mongo:
                condition: service_healthy
        env_file:
            - .env
        environment:
            REDIS_URI: redis://langgraph-redis:6379
            LANGSMITH_API_KEY: ${LANGSMITH_API_KEY}
            DATABASE_URI: postgres://postgres:***@langgraph-postgres:5432/postgres?sslmode=disable
            LS_DEFAULT_CHECKPOINTER_BACKEND: mongo
            LS_MONGODB_URI: mongodb://langgraph-mongo:27017/langgraph?replicaSet=rs0

MongoDB 구성 옵션에 대한 자세한 내용은 Configure checkpointer backend를 참고하세요.

이렇게 하면 포트 8123에서 Agent Server가 실행돼요(포트 매핑이 필요하면 langgraph-api에서 바꾸세요). 애플리케이션이 정상인지 테스트합니다.

curl --request GET --url 0.0.0.0:8123/ok

모든 게 정상이면 이런 응답을 볼 수 있어요.

{"ok":true}

더 알아보기 (Learn more)

  • 제어 평면을 포함한 자체호스팅 배포는 Deploy with control plane을 확인하세요.
  • 에이전트가 자체 VPC에서 돌고 트레이스만 LangSmith로 보내는 하이브리드는 Hybrid를 참고하세요.