---
name: langsmith-fetch
description: "LangSmith API로 AI 에이전트 실행 트레이스를 조회·분석한다. 에러 패턴 감지, 성능 병목 식별, dispatch 에이전트 디버깅에 활용."
triggers:
  - "langsmith"
  - "langsmith-fetch"
  - "트레이스"
  - "trace"
  - "에이전트 디버깅"
  - "agent debug"
  - "에이전트 오류"
  - "도구 호출 추적"
  - "tool call"
  - "에이전트 실행 기록"
  - "LangSmith"
  - "실행 로그"
  - "agent trace"
  - "dispatch 디버깅"
  - "토큰 사용량"
usage: "/langsmith-fetch [--trace <trace-id>] [--errors] [--minutes <N>] [--export <경로>]"
---

# /langsmith-fetch — AI 에이전트 트레이스 분석

> 출처: OthmanAdi/langsmith-fetch-skill (MIT 라이선스, awesome-claude-skills 생태계)
> 우리 시스템에 맞게 커스텀 (한국어 출력, 보험/금융 도메인, dispatch.py 연계, 이모지 제거)

LangSmith API를 통해 AI 에이전트 실행 트레이스를 조회하고, 에러 패턴과 성능 병목을 분석한다. dispatch.py 기반 멀티에이전트 세션 디버깅에 특화되어 있으며, task-timer.py 기록과 교차 분석이 가능하다.

**토르(개발2팀 백엔드 전문가)** 가 이 스킬을 주도한다.

---

## User-invocable

사용자가 `/langsmith-fetch`를 입력하면 이 스킬을 실행한다.

---

## Arguments

- `/langsmith-fetch` — 최근 5분 트레이스 조회 (기본값)
- `/langsmith-fetch --trace <trace-id>` — 특정 트레이스 상세 조회
- `/langsmith-fetch --errors` — 에러/실패 트레이스만 필터링
- `/langsmith-fetch --minutes <N>` — 최근 N분 트레이스 조회 (기본: 5)
- `/langsmith-fetch --limit <N>` — 조회 건수 제한 (기본: 20)
- `/langsmith-fetch --export <경로>` — 트레이스 세션 파일로 내보내기
- `/langsmith-fetch --agent <이름>` — 특정 에이전트 트레이스만 필터링

---

## 절대 규칙

> **이 규칙은 어떤 상황에서도 예외 없이 적용된다.**

1. **환경 확인 우선**: langsmith-fetch CLI 설치 여부와 환경변수를 반드시 먼저 확인한다.
2. **API 키 출력 금지**: `LANGSMITH_API_KEY` 값을 절대 출력하지 않는다. 설정 여부만 확인한다.
3. **분석 결과는 한국어로 출력**: 트레이스 원문(JSON)은 영어이지만, 분석 보고서는 한국어로 작성한다.
4. **에러 원인은 추측 기반 제시 금지**: 트레이스 데이터에 근거한 분석만 제공하고, 데이터가 없으면 "확인 불가"로 표시한다.

---

## 워크플로우 개요

```
Step 1: 환경 확인 (CLI 설치, API 키, 프로젝트명)
    ↓
Step 2: 트레이스 조회 (최근 N분 / 특정 ID / 에러 필터)
    ↓
Step 3: 분석 (에러 패턴, 성능 병목, 도구 호출 순서)
    ↓
Step 4: 보고서 출력 (SCQA 연계 포함)
    ↓
Step 5: 조치 권고 (선택)
```

---

## Step 1: 환경 확인

스킬 실행 시 가장 먼저 환경을 점검한다.

### 1.1 CLI 설치 확인

```bash
which langsmith-fetch || pip show langsmith-fetch
```

설치되어 있지 않으면:

```
[langsmith-fetch] CLI가 설치되어 있지 않습니다.

설치 방법:
  pip install langsmith-fetch

설치 후 다시 실행해주세요.
```

### 1.2 환경변수 확인

```bash
# API 키 설정 여부만 확인 (값 출력 금지)
[ -n "$LANGSMITH_API_KEY" ] && echo "LANGSMITH_API_KEY: 설정됨" || echo "LANGSMITH_API_KEY: 미설정"
[ -n "$LANGSMITH_PROJECT" ] && echo "LANGSMITH_PROJECT: $LANGSMITH_PROJECT" || echo "LANGSMITH_PROJECT: 미설정"
```

환경변수 미설정 시:

```
[langsmith-fetch] 환경변수 설정이 필요합니다.

필요한 환경변수:
  export LANGSMITH_API_KEY="<LangSmith API 키>"
  export LANGSMITH_PROJECT="<프로젝트명>"

영구 설정:
  echo 'export LANGSMITH_API_KEY="<키>"' >> ~/.bashrc
  echo 'export LANGSMITH_PROJECT="<프로젝트명>"' >> ~/.bashrc
  source ~/.bashrc

LangSmith API 키 발급: https://smith.langchain.com/ > Settings > API Keys
```

### 1.3 환경 확인 성공 출력

```
[langsmith-fetch] 환경 확인 완료
  CLI: langsmith-fetch <버전>
  API 키: 설정됨
  프로젝트: <프로젝트명>

트레이스 조회를 시작합니다...
```

---

## Step 2: 트레이스 조회

### 2.1 최근 N분 트레이스 조회 (기본 모드)

```bash
langsmith-fetch traces --last-n-minutes 5 --limit 20 --format json
```

### 2.2 특정 트레이스 상세 조회 (`--trace <id>`)

```bash
langsmith-fetch trace <trace-id> --format json
```

### 2.3 에러 트레이스 필터링 (`--errors`)

```bash
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json | \
  python3 -c "import json,sys; traces=json.load(sys.stdin); \
  print(json.dumps([t for t in traces if t.get('error') or t.get('status')=='error'], indent=2))"
```

### 2.4 세션 내보내기 (`--export <경로>`)

```bash
SESSION_DIR="<지정 경로>/langsmith-session-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SESSION_DIR"

langsmith-fetch traces "$SESSION_DIR/traces" --last-n-minutes 30 --limit 50 --include-metadata
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20
```

### 2.5 특정 에이전트 필터링 (`--agent <이름>`)

```bash
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json | \
  python3 -c "import json,sys; traces=json.load(sys.stdin); \
  print(json.dumps([t for t in traces if '<에이전트명>' in str(t)], indent=2))"
```

---

## Step 3: 분석

### 3.1 에러 패턴 분류

조회된 트레이스에서 다음 에러 유형을 분류한다:

| 에러 유형 | 감지 패턴 | 권고 조치 |
|----------|-----------|----------|
| 연결 타임아웃 | `timeout`, `connection refused` | DB/외부 서비스 연결 상태 확인 |
| 도구 호출 실패 | `tool not found`, `tool error` | 도구 설정 및 권한 확인 |
| 토큰 한도 초과 | `token limit`, `context length` | 프롬프트 최적화 또는 청킹 전략 검토 |
| 인증 오류 | `unauthorized`, `401`, `403` | API 키 및 권한 확인 |
| 메모리 오류 | `memory error`, `store failed` | 벡터 DB 상태 확인 |
| 속도 제한 | `rate limit`, `429` | 재시도 로직 및 요청 간격 조정 |

### 3.2 성능 병목 식별

다음 기준으로 성능 병목을 판단한다:

- **느린 도구 호출**: 단일 도구 실행 시간 > 5초
- **높은 토큰 사용**: 단일 트레이스 토큰 > 8,000
- **반복 도구 호출**: 동일 도구 3회 이상 연속 호출
- **긴 전체 실행 시간**: 트레이스 전체 소요 > 30초

### 3.3 도구 호출 순서 분석

트레이스의 도구 호출 순서를 추출하여 비정상 패턴을 감지한다:

```python
# 도구 호출 순서 추출 예시
tool_sequence = [step['tool'] for step in trace['steps'] if step.get('tool')]
# 예: ['Read', 'Grep', 'Edit', 'Bash', 'Edit']

# 비정상 패턴 감지
if tool_sequence.count('Bash') > 5:
    warn("Bash 도구 과다 호출 감지 - 루프 또는 반복 실패 가능성")
```

---

## Step 4: 보고서 출력

### 4.1 기본 트레이스 요약 보고서

```
## LangSmith 트레이스 분석 (최근 <N>분)

조회 시각: <YYYY-MM-DD HH:MM:SS>
프로젝트: <프로젝트명>
총 트레이스: <N>건 | 성공: <N>건 | 실패: <N>건 | 실패율: <N>%

---

### 트레이스 요약

| # | 상태 | 에이전트 | 도구 호출 | 소요 시간 | 토큰 | 에러 |
|---|------|----------|-----------|----------|------|------|
| 1 | 성공 | 오딘 | Read, Grep, Edit | 2.3초 | 1,245 | — |
| 2 | 실패 | 토르 | Bash, pytest | 15.1초 | 892 | timeout |
| 3 | 성공 | 프레이야 | Read, Write | 1.8초 | 634 | — |

---

### 에러 분석

발견된 에러 패턴:

1. <에러 유형> (<N>건)
   - 영향 에이전트: <에이전트명>
   - 실패 도구: <도구명>
   - 발생 시각: <HH:MM> ~ <HH:MM>
   - 원인 (트레이스 기반): <분석 내용>
   - 권고 조치: <조치 내용>

---

### 성능 분석

- 평균 소요 시간: <N>초
- 최장 소요 트레이스: <trace-id> (<N>초) — <에이전트명>
- 평균 토큰 사용: <N>
- 최고 토큰 트레이스: <trace-id> (<N> 토큰)

병목 감지:
- <병목 항목>: <설명 및 권고>

---

### dispatch 시스템 연계 분석

dispatch.py 실행과의 대응:
- 세션 시작 시각: <HH:MM:SS>
- 활성 에이전트: <에이전트 목록>
- 완료/미완료 작업: <N>/<N>

task-timer.py 기록 교차 확인:
- 총 작업 시간: <N>분
- LangSmith 트레이스 소요 합계: <N>초
- 불일치 항목: <있으면 기술, 없으면 "일치">
```

### 4.2 특정 트레이스 상세 보고서 (`--trace` 모드)

```
## 트레이스 상세 분석 — <trace-id>

에이전트: <이름>
실행 목표: <트레이스에서 파악한 목표>
상태: <성공/실패>
소요 시간: <N>초
토큰 사용: <N> (입력: <N>, 출력: <N>)

---

### 도구 호출 흐름

1. [성공] <도구명> (<N>ms)
   입력: <요약>
   결과: <요약>

2. [실패] <도구명> (<N>ms)
   입력: <요약>
   에러: <에러 메시지>
   <-- 실패 지점

3. [미실행] 이후 단계 중단

---

### 원인 분석

트레이스 데이터 기반:
- <원인 1>
- <원인 2>

---

### 권고 조치

1. <조치 1>: <구체적 방법>
2. <조치 2>: <구체적 방법>
```

### 4.3 에러 전용 보고서 (`--errors` 모드)

```
## 에러 트레이스 분석 (최근 <N>분)

총 에러: <N>건

---

### 에러 유형별 분류

**<에러 유형 1>** (<N>건, <N>%)
  - trace-id: <id1>, <id2>
  - 영향 에이전트: <에이전트명>
  - 첫 발생: <HH:MM> / 최근 발생: <HH:MM>
  - 패턴: <반복 여부 및 특징>

**<에러 유형 2>** (<N>건, <N>%)
  ...

---

### 종합 권고

우선순위별 조치:
1. [긴급] <조치>
2. [높음] <조치>
3. [보통] <조치>
```

### 4.4 SCQA 보고서 연계

에러 분석 결과를 팀 공유용 SCQA 포맷으로 변환하는 방법:

```
SCQA 포맷 변환 예시:

[S - 상황] 최근 30분간 dispatch 세션에서 5건의 트레이스 실행
[C - 문제] 그 중 3건(60%)이 Neo4j 연결 타임아웃으로 실패
[Q - 질문] 현재 DB 연결 상태가 정상인가? 재시도 로직이 필요한가?
[A - 답변] 트레이스 패턴상 피크 타임 연결 풀 고갈 가능성 높음.
           DB 연결 풀 크기 증가 또는 재시도 로직 추가 권장.
```

---

## Step 5: 조치 권고

### 5.1 자주 발생하는 에러별 조치 가이드

#### Neo4j 연결 타임아웃

```bash
# 연결 상태 확인
cypher-shell -a bolt://localhost:7687 "RETURN 1"

# dispatch.py 재시작 시 환경변수 확인
echo $NEO4J_URI
echo $NEO4J_USERNAME
```

권고: `cypher` 에이전트의 도구에 재시도 로직(최대 3회, 지수 백오프) 추가

#### 토큰 한도 초과

권고: 컨텍스트 압축 전략 검토. 긴 파일 읽기 전 `Glob` + `Grep`으로 필요 부분만 선택

#### 도구 미설치 오류

```bash
# 필요 도구 재확인
pip list | grep <패키지명>
which <도구명>
```

### 5.2 세션 내보내기 저장 구조

```
/home/jay/workspace/memory/langsmith-debug/
  └── session-<YYYYMMDD-HHMMSS>/
      ├── traces/          # 트레이스 JSON 파일들
      ├── threads/         # 스레드 파일들
      └── analysis.md      # 분석 보고서 (선택)
```

---

## 우리 시스템 맥락

### dispatch.py 에이전트 구성

이 스킬은 dispatch.py로 실행되는 에이전트 세션 디버깅에 최적화되어 있다.

에이전트 역할별 트레이스 패턴:

| 에이전트 | 역할 | 자주 사용하는 도구 | 일반적 소요 시간 |
|----------|------|-------------------|----------------|
| 오딘/로키/프리그 | 팀장 (오케스트레이션) | dispatch, Read, Write | 5~30초 |
| 토르/프레이야 | 팀원 (구현) | Read, Grep, Edit, Bash | 3~15초 |

### task-timer.py 교차 분석

task-timer.py 기록과 LangSmith 트레이스를 교차 분석하는 방법:

```bash
# task-timer 기록 확인
cat /home/jay/workspace/memory/task-timers.json | python3 -m json.tool

# LangSmith 트레이스와 시간 대조
/langsmith-fetch --minutes 60
```

불일치 발생 시: task-timer 기록 시간과 LangSmith 트레이스 소요 시간 차이가 크면 에이전트가 응답 대기 중이거나 루프에 빠진 것일 수 있다.

---

## 트러블슈팅

### "트레이스를 찾을 수 없습니다"

```bash
# 1. 더 긴 시간 범위로 재조회
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. 환경변수 재확인
langsmith-fetch config show

# 3. 트레이싱 활성화 여부 확인 (코드 내)
# LANGCHAIN_TRACING_V2=true 설정 필요
```

### "프로젝트를 찾을 수 없습니다"

```bash
# 현재 설정된 프로젝트 확인
langsmith-fetch config show

# 프로젝트명 수정
export LANGSMITH_PROJECT="정확한-프로젝트명"
langsmith-fetch config set project "정확한-프로젝트명"
```

### 환경변수가 세션 간 유지되지 않음

```bash
# ~/.bashrc 또는 ~/.zshrc에 영구 등록
echo 'export LANGSMITH_API_KEY="<키>"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="<프로젝트명>"' >> ~/.bashrc
source ~/.bashrc
```

---

## 의존성

```bash
# 설치
pip install langsmith-fetch

# 필수 환경변수
LANGSMITH_API_KEY=<LangSmith API 키>
LANGSMITH_PROJECT=<프로젝트명>

# 선택 환경변수 (트레이싱 활성화)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=<동일 API 키>
```

---

## 빠른 참조

```bash
# 최근 5분 트레이스 조회
/langsmith-fetch

# 특정 트레이스 상세
/langsmith-fetch --trace <trace-id>

# 에러만 필터링
/langsmith-fetch --errors

# 최근 1시간 조회
/langsmith-fetch --minutes 60

# 세션 내보내기
/langsmith-fetch --export /home/jay/workspace/memory/langsmith-debug/

# 특정 에이전트 필터링
/langsmith-fetch --agent 토르
```

---

**스킬 버전**: v1.0
**작성일**: 2026-04-12
**작성자**: 토르 (개발2팀 백엔드 전문가)
**출처**: OthmanAdi/langsmith-fetch-skill (MIT 라이선스) 기반 커스텀
**원본 저장소**: https://github.com/OthmanAdi/langsmith-fetch-skill
**참조**: dispatch-rules SKILL.md, qc-rules SKILL.md, task-timer.py