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

​

개요

• 자동화된 테스트: 단위, 통합, 엔드 투 엔드 테스트
• 오프라인 평가: AgentEvals, OpenEvals, LangSmith를 활용한 성능 평가
• 프리뷰 및 프로덕션 배포: Control Plane API를 통한 자동화된 스테이징 및 품질 게이트 프로덕션 릴리즈
• 모니터링: 지속적인 평가 및 알림

​

파이프라인 아키텍처

​

트리거 소스

• 코드 변경: LangGraph 아키텍처 수정, 모델 변경, 에이전트 로직 업데이트, 기타 코드 개선을 위한 main/development 브랜치 푸시
• PromptHub 업데이트: LangSmith PromptHub에 저장된 프롬프트 템플릿 변경—새 프롬프트 커밋 시 웹훅을 통해 파이프라인 실행
• 온라인 평가 알림: 라이브 배포에서 성능 저하 알림
• LangSmith 트레이스 웹훅: 트레이스 분석 및 성능 지표 기반 자동 트리거
• 수동 트리거: 테스트 또는 긴급 배포를 위한 수동 파이프라인 실행

​

테스트 레이어

1. 단위 테스트: 개별 노드 및 유틸리티 함수 테스트
2. 통합 테스트: 컴포넌트 상호작용 테스트
3. 엔드 투 엔드 테스트: 전체 그래프 실행 테스트
4. 오프라인 평가: 실제 시나리오 기반 성능 평가(엔드 투 엔드 평가, 단일 단계 평가, 에이전트 경로 분석, 다중 턴 시뮬레이션 포함)
5. LangGraph 개발 서버 테스트: langgraph-cli 도구를 사용하여(GitHub Action 내에서) LangGraph 에이전트를 실행하는 로컬 서버를 구동합니다. /ok 서버 API 엔드포인트를 30초간 폴링하며, 이후 오류를 발생시킵니다.

​

GitHub Actions 워크플로우

• 새 에이전트 배포: 새 PR이 열리고 테스트가 통과하면, Control Plane API를 통해 LangSmith Deployments에 프리뷰 배포가 생성됩니다. 이를 통해 프로덕션으로 승격하기 전에 스테이징 환경에서 에이전트를 테스트할 수 있습니다.
• 에이전트 배포 리비전: 동일한 ID의 기존 배포가 발견되거나 PR이 main에 병합될 때 리비전이 발생합니다. main에 병합되는 경우 프리뷰 배포가 삭제되고 프로덕션 배포가 생성됩니다. 이를 통해 에이전트의 모든 업데이트가 프로덕션 인프라에 올바르게 배포 및 통합됩니다.
• 테스트 및 평가 워크플로우: 기존 테스트 단계(단위 테스트, 통합 테스트, 엔드 투 엔드 테스트 등) 외에도, 파이프라인에는 오프라인 평가와 LangGraph 개발 서버 테스트가 포함되어 에이전트 품질을 검증합니다. 이러한 평가는 실제 시나리오와 데이터를 활용하여 에이전트 성능을 종합적으로 평가합니다.
  최종 응답 평가

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

  단일 단계 평가

  LangGraph 워크플로우 내 개별 단계 또는 노드를 테스트합니다. 이를 통해 에이전트 로직의 특정 컴포넌트를 개별적으로 검증하여 전체 파이프라인 테스트 전에 각 단계가 올바르게 동작하는지 확인할 수 있습니다.

  에이전트 경로 평가

  그래프 내에서 에이전트가 거치는 전체 경로(중간 단계 및 결정 지점 포함)를 분석합니다. 이를 통해 병목, 불필요한 단계, 비효율적인 라우팅을 식별할 수 있습니다. 또한 에이전트가 적절한 도구를 올바른 순서와 시점에 호출했는지 평가합니다.

  다중 턴 평가

  에이전트가 여러 상호작용에서 컨텍스트를 유지하는 대화 흐름을 테스트합니다. 이는 후속 질문, 추가 설명, 장기간 사용자 대화 등을 처리하는 에이전트에 매우 중요합니다.
  구체적인 테스트 방법은 LangGraph 테스트 문서와 오프라인 평가에 대한 종합적인 개요는 평가 접근 방식 가이드를 참고하세요.

​

사전 준비 사항

• AI 에이전트 애플리케이션(LangGraph 기반)
• LangSmith 계정
• 에이전트 배포 및 실험 결과 조회에 필요한 LangSmith API 키
• 저장소 시크릿에 프로젝트별 환경 변수 설정(예: LLM 모델 API 키, 벡터 스토어 자격 증명, 데이터베이스 연결 정보 등)

​

배포 옵션

• 클라우드 LangSmith: GitHub 직접 연동 또는 Docker 이미지 배포
• 셀프 호스팅/하이브리드: 컨테이너 레지스트리 기반 배포

​

수동 배포 사전 준비 사항

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

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

​

로컬 개발 및 테스트

# Start local development server with LangGraph Studio
langgraph dev

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

​

방법 1: LangSmith 배포 UI

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

• 클라우드 LangSmith: 드롭다운 메뉴를 통한 GitHub 직접 연동
• 셀프 호스팅/하이브리드 LangSmith: Image Path 필드에 이미지 URI 지정(예: docker.io/username/my-agent:latest)

​

방법 2: Control Plane API

• Control Plane API를 사용하여 GitHub 저장소를 지정해 배포 생성
• 클라우드 배포는 Docker 이미지 빌드 불필요

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

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

• 클라우드 LangSmith: Control Plane API로 GitHub 저장소에서 배포 생성
• 셀프 호스팅/하이브리드 LangSmith: Control Plane API로 컨테이너 레지스트리에서 배포 생성

​

배포된 에이전트 연결

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

​

환경 구성

​

데이터베이스 & 캐시 구성

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

​

문제 해결

​

잘못된 API 엔드포인트

​

LangSmith API(트레이스, 인제스션 등)

​

LangSmith Deployments API(배포)