LangSmith CLI/SDK 자동화

1 도입: 왜 CLI/SDK 자동화가 필요한가

LLM 애플리케이션의 평가와 모니터링을 웹 대시보드에서 수동으로 수행하는 방식은 프로토타입 단계에서는 충분하지만, 프로덕션 환경에서는 한계가 분명하다.

• 확장성 부재: 매번 웹 UI에 접속하여 버튼을 클릭하는 방식으로는 수백 개의 테스트 케이스를 정기적으로 실행할 수 없다.
• CI/CD 통합 불가: GitHub Actions, Jenkins 등의 파이프라인에서 웹 브라우저를 조작하는 것은 현실적이지 않다.
• 재현성 부족: 수동 평가는 누가, 언제, 어떤 조건으로 실행했는지 추적하기 어렵다.
• 협업 병목: 팀원마다 대시보드에서 개별적으로 확인하는 것은 비효율적이다.

LangSmith는 이 문제를 해결하기 위해 CLI(Command Line Interface)와 Python/TypeScript SDK를 제공한다. 터미널에서 실시간 모니터링을 수행하고, 스크립트로 평가를 자동화하며, CI/CD 파이프라인에 통합하여 배포 전 품질 게이트를 구축할 수 있다. 이 글에서는 CLI와 SDK의 구체적 사용법, 에이전트 도구 생태계 트렌드, 그리고 이들을 조합한 실무 워크플로를 다룬다.

2 1. LangSmith CLI: 터미널 기반 모니터링 및 제어

LangChain 팀은 langsmith CLI를 통해 웹 UI 없이도 터미널에서 프로젝트 데이터를 관리하고 모니터링할 수 있는 환경을 제공한다. CLI는 pip install langsmith로 설치하며, 사용 전에 환경 변수를 설정해야 한다.

# 환경 변수 설정
export LANGCHAIN_API_KEY="ls-..."
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

2.1 1.1 watch: 실시간 모니터링

watch 서브커맨드는 터미널에서 실시간으로 Run 상태를 스트리밍하는 대시보드를 활성화한다. 프로덕션 환경에서 LLM 호출의 지연 시간, 성공/실패 여부, 토큰 사용량을 즉시 파악할 수 있다.

# 특정 프로젝트의 실행 상태를 실시간 모니터링
langsmith runs watch --project "my-chatbot-prod"

이 명령을 실행하면 터미널에 새로운 Run이 들어올 때마다 실시간으로 상태가 갱신되는 출력이 나타난다. 각 Run의 이름, 상태(success/error), 지연 시간(latency), 토큰 수 등이 표시된다. Ctrl+C로 종료할 수 있다.

힌트

watch 모드는 SSH로 접속한 원격 서버에서 특히 유용하다. 웹 브라우저를 열 수 없는 환경에서도 실시간 모니터링이 가능하기 때문이다.

2.2 1.2 list: 데이터 필터링 및 조회

list 서브커맨드로 프로젝트, Run, 데이터셋 등을 조회하고 필터링할 수 있다.

# 모든 프로젝트 목록 조회
langsmith project list

# 특정 프로젝트의 최근 Run 목록 조회
langsmith runs list --project "my-chatbot-prod" --limit 20

# 실패한 Run만 필터링
langsmith runs list --project "my-chatbot-prod" --filter "status=error" --limit 50

# 특정 기간의 Run 조회
langsmith runs list --project "my-chatbot-prod" \
  --start-time "2026-03-01" --end-time "2026-03-18"

2.3 1.3 export: 데이터 내보내기와 파이프라인 연결

CLI의 출력은 기본적으로 JSON 형식을 지원하므로, jq나 Python 스크립트와 파이프라인으로 연결하여 분석할 수 있다.

# Run 데이터를 JSON으로 내보내기
langsmith runs list --project "my-chatbot-prod" \
  --output-format json > runs.json

# jq로 실패한 Run의 에러 메시지만 추출
langsmith runs list --project "my-chatbot-prod" \
  --output-format json | jq '[.[] | select(.status == "error") | {name, error}]'

# 평균 지연 시간 계산
langsmith runs list --project "my-chatbot-prod" \
  --output-format json | jq '[.[].latency] | add / length'

Python에서 JSON 출력을 후처리하는 패턴도 자주 사용된다.

import subprocess
import json

# CLI 결과를 Python에서 처리
result = subprocess.run(
    ["langsmith", "runs", "list",
     "--project", "my-chatbot-prod",
     "--output-format", "json"],
    capture_output=True, text=True
)
runs = json.loads(result.stdout)

# 모델별 비용 통계 집계
cost_by_model = {}
for run in runs:
    model = run.get("extra", {}).get("model_name", "unknown")
    cost = run.get("total_cost", 0)
    cost_by_model[model] = cost_by_model.get(model, 0) + cost

for model, total in sorted(cost_by_model.items(), key=lambda x: -x[1]):
    print(f"{model}: ${total:.4f}")

노트

CLI는 빠른 확인과 일회성 분석에 적합하다. 반복적인 자동화 작업에는 다음 절에서 다루는 SDK가 더 적절하다.

3 2. SDK를 통한 자동화 (Python/TypeScript)

웹 UI에서 클릭하는 대부분의 작업은 langsmith.Client SDK를 통해 프로그래밍 방식으로 처리할 수 있다. SDK는 CLI보다 세밀한 제어가 가능하며, 평가 파이프라인의 핵심 구성 요소로 사용된다.

3.1 2.1 langsmith.Client 기본 사용법

from langsmith import Client

# 클라이언트 초기화 (LANGCHAIN_API_KEY 환경 변수 자동 참조)
client = Client()

# 프로젝트 목록 조회
for project in client.list_projects():
    print(f"{project.name}: {project.run_count} runs")

# 특정 프로젝트의 최근 실행 조회
runs = list(client.list_runs(
    project_name="my-chatbot-prod",
    filter='eq(status, "error")',
    limit=10
))
for run in runs:
    print(f"[{run.status}] {run.name} - latency: {run.latency}s")

3.2 2.2 데이터셋 관리와 자동 평가

수천 개의 테스트 케이스를 웹에 업로드할 필요 없이, 로컬의 .jsonl 파일을 스크립트 한 줄로 데이터셋화하여 벤치마킹할 수 있다.

from langsmith import Client
from langsmith.evaluation import evaluate

client = Client()

# 로컬 데이터로 데이터셋 생성
dataset = client.create_dataset("qa-benchmark-v2")
examples = [
    {"input": {"question": "대한민국의 수도는?"}, "output": {"answer": "서울"}},
    {"input": {"question": "Python의 창시자는?"}, "output": {"answer": "귀도 반 로섬"}},
    # ... 수천 개의 테스트 케이스
]
client.create_examples(
    inputs=[e["input"] for e in examples],
    outputs=[e["output"] for e in examples],
    dataset_id=dataset.id,
)

# 평가 대상 함수 정의
def my_chatbot(inputs: dict) -> dict:
    # 실제 LLM 호출 로직
    from langchain_openai import ChatOpenAI
    llm = ChatOpenAI(model="gpt-4o-mini")
    response = llm.invoke(inputs["question"])
    return {"answer": response.content}

# 정확도 평가기 정의
def exact_match(run, example) -> dict:
    pred = run.outputs.get("answer", "").strip()
    expected = example.outputs.get("answer", "").strip()
    return {"key": "exact_match", "score": int(pred == expected)}

# 자동 평가 실행
results = evaluate(
    my_chatbot,
    data="qa-benchmark-v2",
    evaluators=[exact_match],
    experiment_prefix="gpt-4o-mini-baseline",
)
print(f"평균 정확도: {results.aggregate_metrics['exact_match']:.2%}")

3.3 2.3 CI/CD 통합: GitHub Actions 예시

SDK의 진정한 가치는 CI/CD 파이프라인에 통합하여 배포 전 품질 게이트를 자동화하는 데 있다. 다음은 GitHub Actions에서 LangSmith 평가를 실행하는 워크플로 예시이다.

# .github/workflows/llm-eval.yml
name: LLM Evaluation Gate

on:
  pull_request:
    paths:
      - "src/prompts/**"
      - "src/chains/**"

jobs:
  evaluate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install langsmith langchain-openai

      - name: Run LangSmith evaluation
        env:
          LANGCHAIN_API_KEY: ${{ secrets.LANGCHAIN_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          python scripts/run_evaluation.py \
            --dataset "qa-benchmark-v2" \
            --threshold 0.85

      - name: Check evaluation results
        run: |
          # 평가 점수가 임계값 미만이면 PR 머지를 차단
          python scripts/check_threshold.py --min-score 0.85

이 구성에서 scripts/run_evaluation.py는 앞서 작성한 SDK 코드를 포함하며, 평가 점수가 임계값(예: 85%) 미만이면 CI가 실패하여 프롬프트 변경이 자동으로 차단된다.

중요

CI/CD에서 LLM 평가를 실행할 때는 비용 관리에 주의해야 한다. 전체 데이터셋 대신 샘플링된 서브셋으로 평가하거나, PR 라벨(needs-eval)이 붙은 경우에만 실행하는 등의 조건부 트리거를 활용하는 것이 좋다.

4 3. 에이전트 도구 트렌드

Retriever와 Vector DB가 정보를 찾는 법에 집중했다면, 현재 가장 주목받는 도구들은 어떻게 도구를 지능적으로 사용할 것인가에 집중한다. 아래 표는 각 도구의 핵심 가치와 포지셔닝을 정리한 것이다.

분류	도구	핵심 가치
워크플로우 제어	LangGraph	에이전트의 사고를 순환 그래프(Cyclic Graph)로 제어하여 무한 루프 방지 및 상태 유지
연동 표준화	MCP (Model Context Protocol)	모든 DB/API를 개별 개발할 필요 없이, 표준 규격 하나로 에이전트와 연결
프롬프트 최적화	DSPy	수작업 프롬프트 튜닝 대신, 알고리즘 기반으로 최적의 프롬프트를 자동 생성/컴파일
실행 환경	E2B / Piston	에이전트가 코드를 실행할 수 있는 안전한 샌드박스(Sandbox) 환경 제공

4.1 3.1 각 도구의 포지셔닝과 선택 기준

LangGraph는 단순한 Chain 호출을 넘어 에이전트가 조건 분기, 반복, 병렬 실행 등 복잡한 워크플로를 수행해야 할 때 선택한다. 상태 머신(State Machine) 기반으로 설계되어 있어, 에이전트가 “생각 -> 도구 호출 -> 결과 검증 -> 재시도” 같은 순환 로직을 안전하게 수행할 수 있다. 단순 QA 체인에는 과도하지만, 멀티스텝 추론이 필요한 에이전트에는 필수적이다.

MCP (Model Context Protocol)는 에이전트가 외부 도구와 상호작용하는 인터페이스를 표준화한다. 기존에는 각 API마다 별도의 Tool 클래스를 작성해야 했지만, MCP를 지원하는 서버를 구축하면 에이전트가 표준 프로토콜로 어떤 도구든 동일한 방식으로 호출할 수 있다. 도구 연동이 5개 이상으로 늘어나는 시점에서 도입을 고려하면 된다.

DSPy는 프롬프트 엔지니어링을 자동화한다. 수동으로 프롬프트를 작성하고 튜닝하는 대신, 입출력 시그니처를 선언하면 DSPy가 학습 데이터를 기반으로 최적의 프롬프트(또는 few-shot 예시)를 자동으로 생성한다. 프롬프트 변경 시마다 성능이 들쑥날쑥한 문제를 겪고 있다면 도입 효과가 크다.

E2B / Piston은 에이전트가 생성한 코드를 실행할 때의 보안 문제를 해결한다. LLM이 생성한 Python 코드를 호스트 서버에서 직접 실행하면 파일 시스템 접근, 네트워크 공격 등의 보안 위험이 있다. E2B와 Piston은 격리된 샌드박스 환경을 제공하여, 에이전트가 생성한 코드를 안전하게 실행하고 결과만 반환받을 수 있게 한다.

• E2B: 클라우드 기반 마이크로 VM을 제공한다. API 호출 한 번으로 격리된 실행 환경이 생성되며, 파일 시스템과 네트워크가 완전히 분리된다. 데이터 분석 에이전트, 코드 인터프리터 에이전트에 적합하다.
• Piston: 오픈소스 코드 실행 엔진으로, 자체 서버에 배포하여 사용한다. 50개 이상의 프로그래밍 언어를 지원하며, 실행 시간과 메모리를 제한할 수 있다.

힌트

선택 가이드: 단순 체인이면 LangChain만으로 충분하다. 멀티스텝 에이전트가 필요하면 LangGraph를 추가한다. 프롬프트 성능이 불안정하면 DSPy를 도입한다. 코드 실행이 필요하면 E2B/Piston으로 샌드박스를 구성한다. 외부 도구가 많아지면 MCP로 표준화한다.

5 4. 실무 워크플로: CLI + SDK + DSPy 통합

앞서 소개한 도구들을 개별적으로 사용하는 것보다, 하나의 파이프라인으로 조합할 때 진정한 효과가 나타난다. 아래는 프롬프트 최적화부터 평가, 배포까지 이어지는 실무 워크플로이다.

5.1 Step 1: DSPy로 프롬프트 최적화

import dspy

# LLM과 데이터 설정
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)

# 시그니처 정의: 입력 -> 출력 관계 선언
class QA(dspy.Signature):
    """질문에 대해 정확하고 간결하게 답변한다."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()

# 학습 데이터 준비
trainset = [
    dspy.Example(question="Python GIL이란?",
                 answer="Global Interpreter Lock. CPython에서 한 번에 하나의 스레드만 바이트코드를 실행하도록 제한하는 뮤텍스이다."),
    # ... 더 많은 예시
]

# 최적화 실행: 자동으로 최적의 프롬프트/few-shot 구성을 탐색
optimizer = dspy.MIPROv2(metric=dspy.evaluate.answer_exact_match, auto="light")
optimized_qa = optimizer.compile(dspy.ChainOfThought(QA), trainset=trainset)

5.2 Step 2: LangSmith SDK로 최적화된 프롬프트 평가

from langsmith import Client
from langsmith.evaluation import evaluate

client = Client()

# DSPy로 최적화된 모듈을 평가 대상 함수로 래핑
def optimized_chatbot(inputs: dict) -> dict:
    result = optimized_qa(question=inputs["question"])
    return {"answer": result.answer}

# LangSmith 데이터셋으로 체계적 평가
results = evaluate(
    optimized_chatbot,
    data="qa-benchmark-v2",
    evaluators=[exact_match],
    experiment_prefix="dspy-optimized-v1",
)

5.3 Step 3: CLI로 결과 모니터링

# 최적화 전후 실험 결과 비교
langsmith runs list --project "qa-benchmark-v2" \
  --output-format json | \
  jq 'group_by(.experiment) | .[] |
    {experiment: .[0].experiment, avg_score: ([.[].score] | add / length)}'

# 프로덕션 배포 후 실시간 모니터링
langsmith runs watch --project "my-chatbot-prod"

5.4 전체 파이프라인 요약

[DSPy 최적화]           [LangSmith SDK 평가]         [LangSmith CLI 모니터링]
프롬프트 자동 탐색  -->  데이터셋 기반 정량 평가  -->  프로덕션 실시간 관찰
      |                       |                            |
      v                       v                            v
최적 프롬프트 확정       CI/CD 품질 게이트 통과       이상 징후 조기 탐지

이 워크플로에서 각 도구의 역할은 다음과 같다.

• DSPy: 프롬프트를 수동으로 작성하는 대신, 알고리즘이 최적의 구성을 탐색한다.
• LangSmith SDK: 최적화된 프롬프트의 성능을 정량적으로 검증하고, CI/CD에서 품질 게이트 역할을 한다.
• LangSmith CLI: 배포 후 프로덕션 트래픽을 실시간으로 관찰하여 성능 저하나 에러를 조기에 탐지한다.

6 5. 정리

LangSmith의 웹 UI는 시각적 분석과 탐색적 디버깅에 유용하지만, 프로덕션 운영 환경에서는 CLI와 SDK를 통한 자동화가 필수이다. 핵심 요점을 정리하면 다음과 같다.

• CLI는 터미널에서의 실시간 모니터링(watch), 데이터 조회(list), JSON 추출(export)을 담당한다. jq나 Python과 파이프라인으로 연결하여 빠른 분석이 가능하다.
• SDK는 langsmith.Client를 통해 데이터셋 관리, 자동 평가, CI/CD 통합을 프로그래밍 방식으로 처리한다. 배포 전 품질 게이트를 자동화하는 것이 가장 중요한 활용 사례이다.
• 에이전트 도구 생태계는 워크플로 제어(LangGraph), 연동 표준화(MCP), 프롬프트 최적화(DSPy), 안전한 코드 실행(E2B/Piston)으로 분화되고 있다. 프로젝트의 복잡도에 따라 필요한 도구를 단계적으로 도입하는 것이 바람직하다.
• 실무 워크플로는 DSPy로 프롬프트를 최적화하고, LangSmith SDK로 정량 평가한 뒤, CLI로 프로덕션을 모니터링하는 순서로 구성한다.