Agent Server 런타임: 그래프·지속성·태스크 큐가 얽히는 구조

Agent Server 런타임: 그래프·지속성·태스크 큐가 얽히는 구조

LangSmith Deployment의 Agent Server는 에이전트 기반 애플리케이션을 만들고 관리하는 API를 제공합니다. 그 기반은 특정 작업에 맞게 설정된 에이전트인 assistants 개념이고, **지속성(persistence)**과 **태스크 큐(task queue)**가 내장되어 있습니다. 이 다재다능한 API는 백그라운드 처리부터 실시간 상호작용까지 광범위한 에이전트 사용 사례를 지원합니다.

Agent Server로 만들고 관리하는 것들: Assistants, Threads, Runs, Cron jobs.

출처: Agent Server 공식 문서

애플리케이션 구조

Agent Server 애플리케이션을 배포하려면 배포할 그래프와 함께 의존성·환경변수 같은 설정을 지정해야 합니다. 자세한 구조는 application structure 가이드를 참고하세요.

LangSmith Cloud는 데이터베이스를 대신 관리합니다. 자체 인프라에 배포한다면 PostgreSQL을 직접 구성해야 합니다.

배포의 구성요소

Agent Server를 배포한다는 것은 곧 하나 이상의 그래프, 지속성용 데이터베이스, 태스크 큐를 함께 배포한다는 뜻입니다.

그래프

Agent Server로 그래프를 배포하면, 그것은 하나의 Assistant를 위한 "청사진(blueprint)"이 됩니다. 그래프는 대부분 에이전트를 구현하지만 꼭 그럴 필요는 없습니다. 예를 들어 어플리케이션 제어 흐름에 영향을 주지 않는 단순한 대화형 챗봇일 수도 있습니다. 실제로는 복잡해질수록 여러 에이전트가 협력하는 흐름을 구현하는 경우가 많습니다.

또한 그래프를 반드시 LangGraph로 작성할 필요는 없습니다. LangGraph Functional API나 deployments-wrap-sdk 패키지를 쓰면 Strands, Claude Agent SDK, Google ADK 등 다른 프레임워크로 만든 에이전트를 배포할 수 있습니다.

그래프 로딩과 컴파일

그래프가 언제, 어떻게 컴파일되는지는 application structure에서 어떻게 등록했느냐에 달립니다.

  1. 컴파일된 그래프(권장) — 이미 컴파일된 CompiledGraph 인스턴스를 내보냅니다. 서버는 컨테이너 시작 시 한 번 로드해서 모든 run에 재사용하므로 요청마다 컴파일 오버헤드가 없습니다.
  2. 팩토리 함수 — 에이전트 팩토리 함수를 내보내면 서버가 그래프가 필요할 때마다 호출합니다. 어시스턴트 설정에 따라 모델이나 도구를 다르게 고르는, run별 그래프 커스터마이즈가 필요할 때만 쓰세요. 팩토리 함수는 호출될 때마다 실행되므로 가볍게 유지하세요.

두 경우 모두 서버가 해당 배포에 설정된 checkpointer와 memory store를 런타임에 자동 주입합니다. 그래프 코드에 직접 설정하지 마세요 — 다른 작업을 관리하기 위해 서버가 이것들을 관리해야 합니다.

지속성 (Persistence)

Agent Server는 세 종류의 데이터를 영속화하며 기본적으로 모두 PostgreSQL에 저장합니다.

  • 핵심 리소스 데이터 — assistants, threads, runs, cron jobs. 항상 PostgreSQL에 저장.
  • 체크포인트(단기 메모리) — 각 단계에서 쓰는 그래프 실행 상태 스냅샷. run을 내구성 있게 만듭니다. 워커가 중단돼도 마지막 체크포인트부터 재개할 수 있죠. 내구성 모드가 체크포인트 빈도를 조절합니다. async(기본)는 각 단계 후 쓰고, exit는 최종 상태만 저장합니다. 기본은 PostgreSQL이지만 MongoDB나 커스텀 구현으로 바꿀 수 있습니다(configure checkpointer backend 참고).
  • Store(장기 메모리) — 스레드를 넘어 지속되는 메모리로, 에이전트가 별개 대화 사이 정보를 유지하게 합니다. 기본은 PostgreSQL이되 커스텀 구현으로 교체 가능합니다(add custom store 참고).

태스크 큐

클라이언트가 run을 만들면 API 서버가 큐에 넣고, 큐 워커가 이를 집어 실행합니다. 워커는 진행 중인 run 취소 신호를 받을 수도 있고, /stream 연결로 실시간 전달되는 출력 이벤트를 발행할 수도 있습니다.

Redis가 API 서버와 큐 워커 사이의 신호·취소·스트리밍 pub/sub을 담당합니다. Redis에는 임시 데이터만 저장되고, 사용자나 run 데이터는 항상 PostgreSQL에 읽고 씁니다.

런타임 아키텍처

배포 모드

Agent Server는 세 가지 런타임 구성을 지원합니다.

  • 단일 호스트(Single host) — API 서버가 별도 큐 워커 없이 태스크 큐를 직접 관리. 셀프호스트의 기본값이며 개발·저트래픽에 적합.
  • API와 큐 분리(Split API and queue) — 전용 큐 워커가 API 서버와 다른 호스트에서 run을 실행. 셀프호스트에선 queue.enabled: true로 활성화. 각 계층이 독립 확장됩니다(API는 요청량, 큐 워커는 대기 run 수 기준).
  • 분산 런타임(Distributed runtime) — API와 큐 프로세스를 다시 분리하되, 큐 프로세스 하나가 오케스트레이션과 실행을 모두 맡는 대신 오케스트레이션용 프로세스와 실행용 프로세스를 각각 둡니다. 고동시성 대규모 배포에 사용.

컨테이너 아키텍처

전형적인 배포는 같은 Docker 이미지(기본 이미지 위에 프로젝트 코드가 얹힌)에서 빌드된 두 종류의 장기 실행 컨테이너로 구성됩니다.

  • API 서버 — 클라이언트 요청(run 생성, 스레드 상태 읽기, 결과 스트리밍)을 처리하지만 에이전트 코드를 직접 실행하지는 않습니다.
  • 큐 워커 — 실행 엔진. 내구성 있는 태스크 큐를 듣고, 그래프 코드를 실행하고, 체크포인트를 씁니다.

컨테이너는 무상태(stateless)지만 지속적입니다. 어떤 순간에도 최소 1개의 큐 워커가 태스크 큐를 듣고 있어야 run이 고아가 되지 않습니다. 컨테이너는 수명 동안 많은 run을 서빙할 수 있습니다. API 서버와 큐 워커는 별도 컨테이너 풀이며 독립 확장됩니다.

flowchart TB
    User["User"]
    API["API Servers"]
    subgraph WorkerContainer["Worker Containers"]
        QueueLoop["Queue Loop"]
        W1["Worker"]
        W2["Worker"]
        Wn["..."]
        QueueLoop -->|dispatch| W1
        QueueLoop -->|dispatch| W2
    end
    DB[(Postgres)]
    Redis[(Redis)]
    User -->|request| API
    API -->|create run| DB
    API -->|notify| Redis
    Redis -->|wake| QueueLoop
    QueueLoop -->|claim next run| DB
    WorkerContainer -->|save checkpoints / update status| DB
    WorkerContainer -->|publish events| Redis
    Redis -->|stream events| API
    API -->|SSE response| User

Run 실행 라이프사이클

run을 호출하면 요청이 여러 컴포넌트를 거칩니다.

  1. 클라이언트가 API 서버에 요청을 보내면, 서버가 내구성 있는 태스크 큐에 pending run을 만듭니다.
  2. 큐 워커가 run을 집어 처음 겹침(lease)을 획득하고, 해당 그래프를 로드해 실행을 시작합니다. 큐는 한 스레드에 대해 동시에 최대 1개 run만 실행되게 보장합니다.
  3. 그래프가 실행되며 워커는 지속성 계층에 체크포인트를 쓰고(빈도는 내구성 모드에 따라 다름), 설정된 pubsub 프로바이더로 스트리밍 이벤트를 브로드캐스트합니다.
  4. 클라이언트가 /stream 연결을 열었다면 API 서버가 pubsub 채널을 구독해 server-sent events로 실시간 전달합니다.
  5. 실행이 끝나면 워커가 run 상태를 갱신하고 다음 run을 위해 슬롯을 놓아줍니다.

각 워커는 최대 N_JOBS_PER_WORKER(기본 10)개 run을 동시 실행하므로, 한 워커 컨테이너가 많은 run을 병렬 서빙합니다. 이 값은 동시 run 실행을 제한할 뿐 배포가 서빙하는 API 요청 수를 제한하지는 않습니다. API 서버는 요청을 독립 처리하고 따로 확장되니까요.

더 알아보기 (Learn more)

  • 애플리케이션을 배포용으로 구조화하는 법은 application structure 가이드.
  • API 엔드포인트·데이터 모델 상세는 API Reference.
  • 로컬에서 같은 런타임을 흉내 내려면 같은 허브의 로컬 개발/테스트 가이드(langgraph dev vs up).