LangSmith Deployment와 Evaluation을 사용한 CI/CD 파이프라인 구현

이 가이드는 LangSmith Deployment에 배포된 AI 에이전트 애플리케이션을 위한 포괄적인 CI/CD 파이프라인을 구현하는 방법을 보여줍니다. 예시에서는 에이전트 오케스트레이션/구축에 LangGraph 오픈 소스 프레임워크를, 관측성과 평가에 LangSmith를 사용합니다. 이 파이프라인은 cicd-pipeline-example 저장소를 기반으로 합니다.

출처: 문서

본문

이 가이드는 LangSmith Deployment에 배포된 AI 에이전트 애플리케이션을 위한 포괄적인 CI/CD 파이프라인을 구현하는 방법을 보여줍니다. 이 예시에서는 LangGraph 오픈 소스 프레임워크를 에이전트 오케스트레이션/구축에, LangSmith를 관측성과 평가에 사용합니다. 이 파이프라인은 cicd-pipeline-example 저장소를 기반으로 합니다.

개요

CI/CD 파이프라인은 다음을 제공합니다:

자동화된 테스트: 단위, 통합, 엔드투엔드 테스트.
오프라인 평가: AgentEvals, OpenEvals 및 LangSmith를 사용한 성능 평가.
미리보기 및 프로덕션 배포: Control Plane API를 사용한 자동 스테이징 및 품질 검증된 프로덕션 릴리스.
모니터링: 지속 평가 및 경고.

파이프라인 아키텍처

CI/CD 파이프라인은 코드 품질과 안정적인 배포를 보장하기 위해 함께 작동하는 여러 핵심 구성 요소로 구성됩니다:

graph TD
    A1[Code or Graph Change] --> B1[Trigger CI Pipeline]
    A2[Prompt Commit in PromptHub] --> B1
    A3[Online Evaluation Alert] --> B1
    A4[PR Opened] --> B1

    subgraph "Testing"
        B1 --> C1[Run Unit Tests]
        B1 --> C2[Run Integration Tests]
        B1 --> C3[Run End to End Tests]
        B1 --> C4[Run Offline Evaluations]

        C4 --> D1[Evaluate with OpenEvals or AgentEvals]
        C4 --> D2[Assertions: Hard and Soft]

        C1 --> E1[Run LangGraph Dev Server Test]
        C2 --> E1
        C3 --> E1
        D1 --> E1
        D2 --> E1
    end

    E1 --> F1[Push to Staging Deployment - Deploy to LangSmith as Development Type]

    F1 --> G1[Run Online Evaluations on Live Data]
    G1 --> H1[Attach Scores to Traces]

    H1 --> I1[If Quality Below Threshold]
    I1 --> J1[Send to Annotation Queue]
    I1 --> J2[Trigger Alert via Webhook]
    I1 --> J3[Push Trace to Golden Dataset]

    F1 --> K1[Promote to Production if All Pass - Deploy to LangSmith Production]

    J2 --> L1[Slack or PagerDuty Notification]

    subgraph Manual Review
        J1 --> M1[Human Labeling]
        M1 --> J3
    end

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
    classDef alert fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
    classDef neutral fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68

    class A1,A2,A3,A4 trigger
    class B1,C1,C2,C3,C4,D1,D2,E1 process
    class H1,I1 decision
    class F1,G1,K1 output
    class J2,L1 alert
    class J1,J3,M1 neutral

트리거 소스

이 파이프라인을 트리거하는 방법은 여러 가지가 있으며, 개발 중이거나 애플리케이션이 이미 라이브인 경우 모두 가능합니다. 파이프라인은 다음에 의해 트리거될 수 있습니다:

코드 변경: LangGraph 아키텍처를 수정하거나, 다른 모델을 시도하거나, 에이전트 로직을 업데이트하거나, 코드 개선을 할 수 있는 main/개발 브랜치로의 푸시.
PromptHub 업데이트: LangSmith PromptHub에 저장된 프롬프트 템플릿 변경 — 새 프롬프트 커밋이 있을 때마다 시스템이 웹훅을 트리거해 파이프라인을 실행합니다.
온라인 평가 경고: 라이브 배포의 성능 저하 알림.
LangSmith 트레이스 웹훅: 트레이스 분석 및 성능 메트릭 기반 자동 트리거.
수동 트리거: 테스트 또는 긴급 배포를 위한 파이프라인의 수동 시작.

테스트 계층

기존 소프트웨어와 달리 AI 에이전트 애플리케이션 테스트는 응답 품질 평가도 요구하므로, 워크플로우의 각 부분을 테스트하는 것이 중요합니다. 파이프라인은 여러 테스트 계층을 구현합니다:

단위 테스트: 개별 노드 및 유틸리티 함수 테스트.
통합 테스트: 컴포넌트 상호작용 테스트.
엔드투엔드 테스트: 전체 그래프 실행 테스트.
오프라인 평가: 엔드투엔드 평가, 단일 단계 평가, 에이전트 궤적 분석, 다회차 시뮬레이션을 포함한 실제 시나리오로 성능 평가.
LangGraph dev 서버 테스트: langgraph-cli 도구를 사용해(GitHub Action 안에서) LangGraph 에이전트를 실행할 로컬 서버를 띄웁니다. 이는 /ok 서버 API 엔드포인트가 사용 가능할 때까지 폴링하며 30초 후에는 오류를 던집니다.

GitHub Actions 워크플로우

CI/CD 파이프라인은 Control Plane API와 LangSmith API와 함께 GitHub Actions를 사용해 배포를 자동화합니다. 헬퍼 스크립트가 API 상호작용과 배포를 관리합니다: https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph_api.py.

워크플로우는 다음을 포함합니다:

새 에이전트 배포: 새 PR이 열리고 테스트가 통과하면, Control Plane API를 사용해 LangSmith Deployment에 새 미리보기 배포가 생성됩니다. 이를 통해 프로덕션으로 승격하기 전에 스테이징 환경에서 에이전트를 테스트할 수 있습니다.
에이전트 배포 리비전: 리비전은 같은 ID를 가진 기존 배포가 발견되거나, PR이 main에 머지될 때 발생합니다. main에 머지하는 경우 미리보기 배포가 삭제되고 프로덕션 배포가 생성됩니다. 이렇게 해서 에이전트에 대한 모든 업데이트가 올바르게 배포되고 프로덕션 인프라에 통합됩니다.
테스트 및 평가 워크플로우: 보다 전통적인 테스트 단계(단위 테스트, 통합 테스트, 엔드투엔드 테스트 등) 외에도, 파이프라인은 에이전트의 품질을 테스트하려 하므로 오프라인 평가와 Agent dev 서버 테스트를 포함합니다. 이 평가들은 실제 시나리오와 데이터를 사용해 에이전트 성능에 대한 포괄적인 평가를 제공합니다.

최종 응답 평가: 에이전트의 최종 출력을 기대 결과와 평가합니다. 에이전트의 최종 응답이 품질 기준을 충족하고 사용자의 질문에 올바르게 답하는지 확인하는 가장 일반적인 평가 유형입니다.

단일 단계 평가: LangGraph 워크플로우 내 개별 단계나 노드를 테스트합니다. 전체 파이프라인을 테스트하기 전에 각 단계가 올바르게 기능하는지 확인하면서, 에이전트 로직의 특정 컴포넌트를 격리해 검증할 수 있게 합니다.

에이전트 궤적 평가: 중간 단계와 결정 지점을 포함해 에이전트가 그래프를 통과하는 전체 경로를 분석합니다. 에이전트 워크플로우의 병목, 불필요한 단계, 비최적 라우팅을 식별하는 데 도움이 됩니다. 또한 에이전트가 올바른 도구를 올바른 순서나 시기에 호출했는지 평가합니다.

다회차 평가: 에이전트가 여러 상호작용에서 컨텍스트를 유지하는 대화 흐름을 테스트합니다. 사용자의 후속 질문, 명확화, 대화 확장을 처리하는 에이전트에 중요합니다.

자세한 테스트 접근 방식은 LangGraph 테스트 문서를, 오프라인 평가의 포괄적 개요는 평가 접근 가이드를 참고하세요.

사전 준비 사항

CI/CD 파이프라인을 설정하기 전에 다음이 있는지 확인하세요:

LangGraph로 구축된 AI 에이전트 애플리케이션
LangSmith 계정
에이전트 배포 및 실험 결과 검색에 필요한 LangSmith API 키
저장소 시크릿에 구성된 프로젝트별 환경 변수(예: LLM 모델 API 키, 벡터 저장소 자격 증명, 데이터베이스 연결)

참고: 이 예시는 GitHub를 사용하지만, CI/CD 파이프라인은 GitLab, Bitbucket 등 다른 Git 호스팅 플랫폼에서도 작동합니다.

배포 옵션

LangSmith는 LangSmith 인스턴스가 호스팅되는 방식에 따라 여러 배포 방법을 지원합니다:

Cloud LangSmith: 직접 GitHub 통합.
자체 호스팅/하이브리드: 컨테이너 레지스트리 기반 배포.

배포 흐름은 에이전트 구현을 수정하는 것으로 시작합니다. 최소한 프로젝트에 langgraph.json과 의존성 파일(requirements.txt 또는 pyproject.toml)이 있어야 합니다. langgraph dev CLI 도구를 사용해 오류를 확인하세요 — 오류를 수정하세요. 그렇지 않으면 LangSmith Deployment에 배포할 때 배포가 성공할 것입니다.

graph TD
    A[Agent Implementation] --> B[langgraph.json + dependencies]
    B --> C[Test Locally with langgraph dev]
    C --> D{Errors?}
    D -->|Yes| E[Fix Issues]
    E --> C
    D -->|No| F[Choose LangSmith Instance]

    F --> G[Cloud LangSmith]
    F --> H[Self-Hosted/Hybrid LangSmith]

    subgraph "Cloud LangSmith"
        G --> I[Method 1: Connect GitHub Repo in UI]
        G --> J[Method 2: Control Plane API with GitHub Repo]
        I --> K[Deploy via LangSmith UI]
        J --> L[Deploy via Control Plane API]
    end

    subgraph "Self-Hosted/Hybrid LangSmith"
        H --> S[Build Docker Image langgraph build]
        S --> T[Push to Container Registry]
        T --> U{Deploy via?}
        U -->|UI| V[Specify Image URI in UI]
        U -->|API| W[Use Control Plane API]
        V --> X[Deploy via LangSmith UI]
        W --> Y[Deploy via Control Plane API]
    end

    K --> AA[Agent Ready for Use]
    L --> AA
    X --> AA
    Y --> AA

    AA --> BB{Connect via?}
    BB -->|LangGraph SDK| CC[Use LangGraph SDK]
    BB -->|RemoteGraph| DD[Use RemoteGraph]
    BB -->|REST API| EE[Use REST API]
    BB -->|LangGraph Studio UI| FF[Use LangGraph Studio UI]

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class A trigger
    class B,C process
    class D,U,BB decision
    class E process
    class F decision
    class G,H process
    class I,J,S,T process
    class K,L,V,W process
    class X,Y,AA output
    class CC,DD,EE,FF output

수동 배포 사전 준비

에이전트를 배포하기 전에 다음이 있는지 확인하세요:

LangGraph 그래프: 에이전트 구현 (예: ./agents/simple_text2sql.py:agent).
의존성: 필수 패키지가 있는 requirements.txt 또는 pyproject.toml.
구성: 다음을 지정하는 langgraph.json 파일:
- 에이전트 그래프 경로
- 의존성 위치
- 환경 변수
- Python 버전

예시 langgraph.json:

{
    "graphs": {
        "simple_text2sql": "./agents/simple_text2sql.py:agent"
    },
    "env": ".env",
    "python_version": "3.11",
    "dependencies": ["."],
    "image_distro": "wolfi"
}

로컬 개발 및 테스트

먼저 Studio로 에이전트를 로컬에서 테스트합니다:

# Start local development server with Studio
langgraph dev

이렇게 하면:

Studio로 로컬 서버를 띄웁니다.
그래프를 시각화하고 상호작용할 수 있게 합니다.
배포 전에 에이전트가 올바르게 작동하는지 검증합니다.

참고: 에이전트가 로컬에서 오류 없이 실행되면 LangSmith 배포도 성공할 가능성이 높습니다. 이 로컬 테스트는 배포를 시도하기 전에 구성 문제, 의존성 문제, 에이전트 로직 오류를 잡는 데 도움이 됩니다.

자세한 내용은 LangGraph CLI 문서를 참고하세요.

방법 1: LangSmith Deployment UI

LangSmith 배포 인터페이스를 사용해 에이전트를 배포합니다:

LangSmith 대시보드로 이동합니다.
Deployments 섹션으로 이동합니다.
오른쪽 상단의 + New Deployment 버튼을 클릭합니다.
드롭다운 메뉴에서 LangGraph 에이전트가 포함된 GitHub 저장소를 선택합니다.

지원되는 배포:

Cloud LangSmith: 드롭다운 메뉴로 직접 GitHub 통합
자체 호스팅/하이브리드 LangSmith: Image Path 필드에 이미지 URI를 지정 (예: docker.io/username/my-agent:latest)

참고: 이점:

간단한 UI 기반 배포

GitHub 저장소와의 직접 통합 (cloud)

수동 Docker 이미지 관리 불필요 (cloud)

방법 2: Control Plane API

각 배포 유형에 대해 다른 접근 방식으로 Control Plane API를 사용해 배포합니다:

Cloud LangSmith의 경우:

Control Plane API를 사용해 GitHub 저장소를 가리켜 배포를 생성합니다.
클라우드 배포에는 Docker 이미지 빌드가 필요하지 않습니다.

자체 호스팅/하이브리드 LangSmith의 경우:

# Build Docker image
langgraph build -t my-agent:latest

# Push to your container registry
docker push my-agent:latest

배포 환경이 접근할 수 있는 아무 컨테이너 레지스트리(Docker Hub, AWS ECR, Azure ACR, Google GCR 등)로 푸시할 수 있습니다.

지원되는 배포:

Cloud LangSmith: Control Plane API를 사용해 GitHub 저장소에서 배포 생성
자체 호스팅/하이브리드 LangSmith: Control Plane API를 사용해 컨테이너 레지스트리에서 배포 생성

자세한 내용은 LangGraph CLI build 문서를 참고하세요.

배포된 에이전트에 연결

LangGraph SDK: 프로그래매틱 통합에 LangGraph SDK 사용.
RemoteGraph: 원격 그래프 연결에 RemoteGraph 사용(다른 그래프에서 그래프 사용).
REST API: 배포된 에이전트와 HTTP 기반 상호작용 사용.
Studio: 테스트와 디버깅을 위한 시각적 인터페이스 접근.

환경 구성

데이터베이스 및 캐시 구성

기본적으로 LangSmith Deployment가 PostgreSQL과 Redis 인스턴스를 생성합니다. 외부 서비스를 사용하려면 새 배포나 리비전에서 다음 환경 변수를 설정하세요:

# Set environment variables for external services
export POSTGRES_URI_CUSTOM="postgresql://user:password@host:5432/db"
export REDIS_URI_CUSTOM="redis://host:6379/0"

자세한 내용은 환경 변수 문서를 참고하세요.

문제 해결

잘못된 API 엔드포인트

연결 문제가 발생하면 LangSmith 인스턴스에 올바른 엔드포인트 형식을 사용하는지 확인하세요. 서로 다른 두 개의 API가 있습니다.

LangSmith API (트레이스, 수집 등)

LangSmith API 작업(트레이스, 평가, 데이터셋)용:

지역	URL
GCP US	`https://api.smith.langchain.com`
GCP EU	`https://eu.api.smith.langchain.com`
GCP APAC	`https://apac.api.smith.langchain.com`
AWS US	`https://aws.api.smith.langchain.com`

자체 호스팅 LangSmith 인스턴스의 경우 http(s)://<langsmith-url>/api를 사용하세요. 여기서 <langsmith-url>은 자체 호스팅 인스턴스 URL입니다.

참고: LANGSMITH_ENDPOINT 환경 변수에 엔드포인트를 설정한다면, 후행 슬래시 없는 전체 API URL을 사용하세요 (예: https://api.smith.langchain.com 또는 자체 호스팅이면 http(s)://<langsmith-url>/api). 후행 슬래시는 일부 엔드포인트에서 인증 오류를 일으킬 수 있습니다.

LangSmith Deployment API (배포)

LangSmith Deployment 작업(배포, 리비전)용:

지역	URL
GCP US	`https://api.smith.langchain.com/api-host`
GCP EU	`https://eu.api.smith.langchain.com/api-host`
GCP APAC	`https://apac.api.smith.langchain.com/api-host`
AWS US	`https://aws.api.smith.langchain.com/api-host`

자체 호스팅 LangSmith 인스턴스의 경우 http(s)://<langsmith-url>/api-host를 사용하세요. 여기서 <langsmith-url>은 자체 호스팅 인스턴스 URL입니다.

더 알아보기

Control Plane API 레퍼런스는 Control plane API reference 문서를 참고하세요.
배포 옵션은 Deployment 문서를 확인해 보세요.