Agent Server

Agent Server

LangSmith Deployment의 Agent Server는 에이전트 기반 애플리케이션을 만들고 관리하기 위한 API를 제공해요. 특정 작업을 위해 구성된 에이전트인 어시스턴트 개념 위에 구축되어 있으며, 내장된 영속성과 작업 큐를 포함해요. 이 다재다능한 API는 백그라운드 처리부터 실시간 상호작용까지 다양한 에이전트 애플리케이션 사용 사례를 지원해요.

Agent Server를 사용해 다음을 만들고 관리하세요:

  • Assistants -
  • Threads -
  • Runs -
  • Cron jobs -

API 참조
API 엔드포인트와 데이터 모델에 대한 자세한 정보는 Agent Server API 참조를 참고하세요.

출처: 문서

본문

애플리케이션 구조

Agent Server 애플리케이션을 배포하려면 배포할 그래프와 의존성, 환경 변수 같은 관련 구성 설정을 지정해야 해요.

배포를 위해 LangGraph 애플리케이션을 어떻게 구성하는지 알아보려면 애플리케이션 구조 가이드를 읽어보세요.

LangSmith 클라우드가 데이터베이스를 관리해줘요. 자체 인프라에 배포한다면 직접 설정해야 해요.

배포의 구성 요소

Agent Server를 배포하면 하나 이상의 그래프, 영속성을 위한 데이터베이스, 작업 큐를 배포하게 돼요.

그래프

Agent Server로 그래프를 배포하면 어시스턴트의 "청사진(blueprint)"을 배포하는 것이에요.

그래프는 대부분 에이전트를 구현하지만, 반드시 그럴 필요는 없어요. 예를 들어, 그래프는 애플리케이션 제어 흐름에 영향을 줄 수 없는 단순한 주고받기 대화만 지원하는 간단한 챗봇을 구현할 수도 있어요. 실제로 애플리케이션이 복잡해질수록 그래프는 여러 에이전트가 함께 작업하는 더 복잡한 흐름을 구현하는 경우가 많아요.

그래프는 반드시 LangGraph로 작성할 필요는 없어요. Strands, Claude Agent SDK 등 또는 Google ADK 같은 다른 프레임워크로 구축된 에이전트도 LangGraph Functional API 또는 deployments-wrap-sdk 패키지를 사용해서 배포할 수 있어요.

그래프 로딩 및 컴파일

그래프가 언제, 어떻게 컴파일되는지는 애플리케이션 구조에서 어떻게 등록하는지에 따라 달라져요:

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

런별 커스터마이즈가 특별히 필요하지 않다면 컴파일된 그래프를 사용하세요. 팩토리 함수는 호출마다 오버헤드를 추가하지만 컴파일된 그래프는 그렇지 않아요.

두 경우 모두 서버는 해당 배포를 위해 구성된 체크포인터와 메모리 스토어를 런타임에 자동으로 주입해요. 서버가 다른 작업을 위해 이를 관리해야 하므로 그래프 코드에 구성하지 마세요.

영속성

Agent Server는 세 가지 유형의 데이터를 영구 저장하며, 기본적으로 모두 PostgreSQL이 지원해요:

  • 핵심 리소스 데이터: 어시스턴트, 스레드, 런 및 크론 작업. 항상 PostgreSQL에 저장돼요.
  • 체크포인트 (단기 메모리): 각 단계에서 기록되는 그래프 실행 상태의 스냅샷. 이로 인해 런이 내구성을 갖게 돼요. 워커가 중단되면 처음부터가 아니라 마지막 체크포인트부터 런을 재개할 수 있어요. 내구성 모드는 체크포인트 빈도를 제어해요—async(기본값)는 각 단계 후에 기록하고, exit는 최종 상태만 저장해요. LangSmith는 기본적으로 이를 PostgreSQL에 저장하지만, MongoDB나 커스텀 구현으로 전환할 수 있어요. 자세한 내용은 체크포인터 백엔드 구성을 참고하세요.
  • 스토어 (장기 메모리): 스레드 간에 유지되는 메모리로, 에이전트가 별도의 대화 간에 정보를 보관할 수 있게 해줘요. 기본적으로 PostgreSQL에 저장되지만 커스텀 구현으로 교체할 수 있어요. 자세한 내용은 커스텀 스토어 추가를 참고하세요.

작업 큐

클라이언트가 런을 만들면 API 서버가 이를 큐에 넣고 큐 워커가 실행을 위해 가져와요. 워커는 진행 중인 런을 취소하라는 신호를 받을 수도 있고, 열린 /stream 연결이 클라이언트에게 실시간으로 전달하는 출력 이벤트를 게시할 수도 있어요.

Redis는 API 서버와 큐 워커 간의 시그널링, 취소, 스트리밍 pub/sub을 처리해요. 일시적인 데이터만 저장하며 Redis에는 사용자 또는 런 데이터가 유지되지 않아요. 런 데이터 자체는 항상 PostgreSQL에서 읽고 씁니다.

이러한 구성 요소를 설정하고 관리하는 방법에 대한 자세한 내용은 호스팅 옵션 가이드를 검토하세요.

런타임 아키텍처

배포 모드

Agent Server는 세 가지 런타임 구성을 지원해요:

  • 단일 호스트: API 서버가 별도의 큐 워커 없이 작업 큐를 직접 관리해요. 이것은 셀프 호스팅 배포의 기본값이며 개발 및 낮은 트래픽 사용 사례에 적합해요.
  • API와 큐 분리: 전용 큐 워커가 API 서버와 별도의 호스트에서 런 실행을 처리해요. 셀프 호스팅 배포에서는 구성에서 queue.enabled: true를 설정해서 활성화해요. 각 계층은 독립적으로 확장돼요—API 서버는 요청 볼륨에 따라, 큐 워커는 대기 중인 런 수에 따라 확장돼요.
  • 분산 런타임: API와 큐 프로세스를 다시 분리해 실행하지만, 그래프의 오케스트레이션과 실행을 모두 처리하는 단일 큐 프로세스 대신, 분산 런타임은 오케스트레이션용 프로세스 하나와 실행용 프로세스 하나를 사용해요. 높은 동시성 요구 사항이 있는 대규모 배포에 사용하세요.

아래에서 설명하는 컨테이너 아키텍처와 런 수명 주기는 단일 호스트 및 API와 큐 분리 구성에 적용돼요.

컨테이너 아키텍처

일반적인 배포는 동일한 Docker 이미지(프로젝트 코드가 위에 설치된 베이스 이미지)에서 빌드된 두 종류의 장기 실행 컨테이너로 구성돼요:

  • API 서버는 클라이언트 요청을 처리해요 (런 생성, 스레드 상태 읽기, 결과 스트리밍) 그러나 에이전트 코드를 직접 실행하지는 않아요.
  • 큐 워커는 실행 엔진이에요. 내구성 있는 작업 큐를 수신하고 그래프 코드를 실행하며 체크포인트를 기록해요.

컨테이너는 **상태 비저장(stateless)**이지만 영구적이에요. 어떤 순간에도 최소 1개의 큐 워커가 작업 큐를 수신해야 런이 고아가 되지 않아요. 컨테이너는 수명 동안 많은 런을 서비스할 수 있어요.

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

    style User fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
    style API fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
    style DB fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    style Redis fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
    style WorkerContainer fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    style QueueLoop fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    style W1 fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
    style W2 fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
    style Wn fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68

런 실행 수명 주기

런을 호출하면 요청은 여러 구성 요소를 거쳐 흐르게 돼요:

  1. 클라이언트가 API 서버에 요청을 보내면, 서버는 내구성 있는 작업 큐에 대기 중인 런을 만들어요.
  2. 큐 워커가 런을 가져와서 임대(lease)를 획득하고 적절한 그래프를 로드한 뒤 실행을 시작해요. 큐는 주어진 스레드에 대해 한 번에 최대 1개의 런만 실행될 수 있도록 강제해요.
  3. 그래프가 실행되면서 워커는 영속성 계층에 체크포인트를 기록하고(빈도는 내구성 모드에 따라 달라짐), 구성된 pubsub 프로바이더를 통해 스트리밍 이벤트를 브로드캐스트해요.
  4. 클라이언트가 /stream 연결을 열었다면 API 서버는 pubsub 채널을 구독하고 서버 전송 이벤트를 통해 실시간으로 이벤트를 클라이언트에 전달해요.
  5. 실행이 완료되면 워커는 런 상태를 업데이트하고 다음 런을 위해 슬롯을 해제해요.

각 워커는 최대 N_JOBS_PER_WORKER(기본값: 10)개의 런을 동시에 실행하므로, 단일 워커 컨테이너가 많은 런을 병렬로 서비스해요. 이는 동시 런 실행을 제한할 뿐, 배포가 처리할 수 있는 API 요청 수를 제한하지는 않아요. API 서버는 요청을 독립적으로 처리하고 별도로 확장되므로 요청 서빙 용량은 N_JOBS_PER_WORKER로 제한되지 않아요. 튜닝 지침은 확장을 위한 Agent Server 구성을 참고하세요.

더 알아보기 (Learn more)

  • 애플리케이션 구조 가이드는 배포를 위해 애플리케이션을 구성하는 방법을 설명해요.
  • API 참조는 API 엔드포인트와 데이터 모델에 대한 자세한 정보를 제공해요.