LangSmith Fetch - 에이전트 디버깅 스킬

LangSmith Fetch - 에이전트 디버깅 스킬은(는) 무엇을 하나요?

LangChain 및 LangGraph 에이전트의 실행 추적을 LangSmith Studio에서 직접 가져와 터미널에서 디버깅합니다.

이 스킬을 사용해야 할 때

사용자가 다음과 같이 언급하면 자동으로 활성화됩니다:

• 🐛 "내 에이전트 디버깅해줘" 또는 "뭐가 잘못됐지?"
• 🔍 "최근 추적 보여줘" 또는 "무슨 일이 일어났어?"
• ❌ "오류 확인해줘" 또는 "왜 실패했어?"
• 💾 "메모리 작업 분석해줘" 또는 "LTM 확인해줘"
• 📊 "에이전트 성능 검토해줘" 또는 "토큰 사용량 확인해줘"
• 🔧 "어떤 도구가 호출됐어?" 또는 "실행 흐름 보여줘"

전제 조건

1. langsmith-fetch 설치

pip install langsmith-fetch

2. 환경 변수 설정

export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"

설정 확인:

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

핵심 워크플로우

워크플로우 1: 최근 활동 빠른 디버깅

사용자가 묻는 경우: "방금 무슨 일이 있었어?" 또는 "내 에이전트 디버깅해줘"

실행:

langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

분석 후 보고:

1. ✅ 찾은 추적 개수
2. ⚠️ 오류 또는 실패 여부
3. 🛠️ 호출된 도구
4. ⏱️ 실행 시간
5. 💰 토큰 사용량

응답 형식 예시:

최근 5분 동안 3개의 추적을 찾았습니다:

추적 1: ✅ 성공
- 에이전트: memento
- 도구: recall_memories, create_entities
- 지속 시간: 2.3초
- 토큰: 1,245

추적 2: ❌ 오류
- 에이전트: cypher
- 오류: "Neo4j 연결 시간 초과"
- 지속 시간: 15.1초
- 실패 위치: search_nodes 도구

추적 3: ✅ 성공
- 에이전트: memento
- 도구: store_memory
- 지속 시간: 1.8초
- 토큰: 892

💡 발견된 문제: 추적 2가 Neo4j 시간 초과로 실패했습니다. 데이터베이스 연결을 확인하는 것이 좋습니다.

---

워크플로우 2: 특정 추적 심층 분석

사용자가 제공하는 경우: 추적 ID 또는 "그 오류 조사해줘"라고 말하는 경우

실행:

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

JSON 분석 후 보고:

1. 🎯 에이전트가 수행하려던 작업
2. 🛠️ 호출된 도구 목록(순서대로)
3. ✅ 도구 결과(성공/실패)
4. ❌ 오류 메시지(있는 경우)
5. 💡 근본 원인 분석
6. 🔧 제안된 수정 사항

응답 형식 예시:

심층 분석 - 추적 abc123

목표: 사용자가 "Neo4j에서 모든 프로젝트 찾기" 요청

실행 흐름:
1. ✅ search_nodes(query: "projects")
   → 24개 노드 발견

2. ❌ get_node_details(node_id: "proj_123")
   → 오류: "노드를 찾을 수 없음"
   → 실패 지점

3. ⏹️ 실행 중단

근본 원인:
search_nodes 도구가 데이터베이스에 더 이상 존재하지 않는 노드 ID를 반환했습니다. 최근 삭제로 인한 것으로 추정됩니다.

제안된 수정 사항:
1. get_node_details 도구에 오류 처리 추가
2. 검색 결과에서 삭제된 노드 필터링
3. 캐시 무효화 전략 업데이트

토큰 사용량: 1,842 토큰 ($0.0276)
실행 시간: 8.7초

---

워크플로우 3: 디버깅 세션 내보내기

사용자가 말하는 경우: "이 세션 저장해줘" 또는 "추적 내보내기"

실행:

# 타임스탬프로 세션 폴더 생성
SESSION_DIR="langsmith-debug/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

보고:

✅ 세션을 성공적으로 내보냈습니다!

위치: langsmith-debug/session-20251224-143022/
- 추적: 42개 파일
- 스레드: 8개 파일

이제 다음을 할 수 있습니다:
1. 개별 추적 파일 검토
2. 팀과 폴더 공유
3. 외부 도구로 분석
4. 향후 참조를 위해 보관

세션 크기: 2.3MB

---

워크플로우 4: 오류 탐지

사용자가 묻는 경우: "오류 보여줘" 또는 "뭐가 실패하고 있어?"

실행:

# 최근 추적 가져오기
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json

# 오류 검색
grep -i "error\|failed\|exception" recent-traces.json

분석 후 보고:

1. 📊 발견된 총 오류 수
2. ❌ 오류 유형 및 빈도
3. 🕐 오류 발생 시간
4. 🎯 실패한 에이전트/도구
5. 💡 공통 패턴

응답 형식 예시:

오류 분석 - 최근 30분

총 추적: 50개
실패한 추적: 7개 (14% 실패율)

오류 분류:
1. Neo4j 연결 시간 초과 (4회 발생)
   - 에이전트: cypher
   - 도구: search_nodes
   - 최초 발생: 14:32
   - 최종 발생: 14:45
   - 패턴: 피크 부하 시간에 발생

2. 메모리 저장 실패 (2회 발생)
   - 에이전트: memento
   - 도구: store_memory
   - 오류: "Pinecone 속도 제한 초과"
   - 발생 시간: 14:38, 14:41

3. 도구를 찾을 수 없음 (1회 발생)
   - 에이전트: sqlcrm
   - 시도한 도구: "export_report" (존재하지 않음)
   - 발생 시간: 14:35

💡 권장 사항:
1. Neo4j 시간 초과에 대한 재시도 로직 추가
2. Pinecone에 대한 속도 제한 구현
3. sqlcrm 도구 구성 수정

---

일반적인 사용 사례

사용 사례 1: "에이전트가 응답하지 않음"

사용자가 말하는 경우: "내 에이전트가 아무것도 안 해요"

단계:

1. 추적이 있는지 확인:

   langsmith-fetch traces --last-n-minutes 5 --limit 5
   

2. 추적이 없는 경우:

   • 추적이 비활성화되었을 수 있음
   • 환경 변수 LANGCHAIN_TRACING_V2=true 확인
   • LANGCHAIN_API_KEY가 설정되었는지 확인
   • 에이전트가 실제로 실행되었는지 확인

3. 추적이 있는 경우:

   • 오류 검토
   • 실행 시간 확인(멈춤?)
   • 도구 호출이 완료되었는지 확인

---

사용 사례 2: "잘못된 도구 호출됨"

사용자가 말하는 경우: "왜 잘못된 도구를 사용했어요?"

단계:

1. 해당 추적 가져오기
2. 실행 시점에 사용 가능한 도구 검토
3. 도구 선택에 대한 에이전트의 추론 확인
4. 도구 설명/지침 검토
5. 프롬프트 또는 도구 구성 개선 제안

---

사용 사례 3: "메모리가 작동하지 않음"

사용자가 말하는 경우: "에이전트가 기억을 못 해요"

단계:

1. 메모리 작업 검색:

   langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory\|recall\|store"
   

2. 확인:

   • 메모리 도구가 호출되었는가?
   • recall이 결과를 반환했는가?
   • 메모리가 실제로 저장되었는가?
   • 검색된 메모리가 사용되고 있는가?

---

사용 사례 4: "성능 문제"

사용자가 말하는 경우: "에이전트가 너무 느려요"

단계:

1. 메타데이터와 함께 내보내기:

   langsmith-fetch traces ./perf-analysis --last-n-minutes 30 --limit 50 --include-metadata
   

2. 분석:

   • 추적별 실행 시간
   • 도구 호출 지연 시간
   • 토큰 사용량(컨텍스트 크기)
   • 반복 횟수
   • 가장 느린 작업

3. 병목 지점 식별 및 최적화 제안

---

출력 형식 가이드

Pretty 형식(기본값)

langsmith-fetch traces --limit 5 --format pretty

사용처: 빠른 시각적 검사, 사용자에게 보여주기

JSON 형식

langsmith-fetch traces --limit 5 --format json

사용처: 상세 분석, 구문 강조 검토

Raw 형식

langsmith-fetch traces --limit 5 --format raw

사용처: 다른 명령어로 파이핑, 자동화

---

고급 기능

시간 기반 필터링

# 특정 타임스탬프 이후
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# 최근 N분(가장 일반적)
langsmith-fetch traces --last-n-minutes 60 --limit 100

메타데이터 포함

# 추가 컨텍스트 가져오기
langsmith-fetch traces --limit 10 --include-metadata

# 메타데이터에는 다음이 포함됩니다: 에이전트 유형, 모델, 태그, 환경

동시 가져오기(더 빠름)

# 대규모 내보내기 속도 향상
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

문제 해결

"조건에 맞는 추적을 찾을 수 없음"

가능한 원인:

1. 해당 시간 범위에 에이전트 활동이 없음
2. 추적이 비활성화됨
3. 잘못된 프로젝트 이름
4. API 키 문제

해결 방법:

# 1. 더 긴 시간 범위 시도
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. 환경 확인
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. 대신 스레드 가져오기 시도
langsmith-fetch threads --limit 10

# 4. 코드에서 추적이 활성화되었는지 확인
# 확인: LANGCHAIN_TRACING_V2=true

"프로젝트를 찾을 수 없음"

해결 방법:

# 현재 구성 보기
langsmith-fetch config show

# 올바른 프로젝트 설정
export LANGSMITH_PROJECT="correct-project-name"

# 또는 영구적으로 구성
langsmith-fetch config set project "your-project-name"

환경 변수가 유지되지 않음

해결 방법:

# 셸 구성 파일에 추가 (~/.bashrc 또는 ~/.zshrc)
echo 'export LANGSMITH_API_KEY="your_key"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="your_project"' >> ~/.bashrc

# 셸 구성 다시 로드
source ~/.bashrc

---

모범 사례

1. 정기적인 상태 확인

# 변경 후 빠른 확인
langsmith-fetch traces --last-n-minutes 5 --limit 5

2. 체계적인 저장소

langsmith-debug/
├── sessions/
│   ├── 2025-12-24/
│   └── 2025-12-25/
├── error-cases/
└── performance-tests/

3. 발견 사항 문서화

버그를 발견하면:

1. 문제가 있는 추적 내보내기
2. error-cases/ 폴더에 저장
3. README에 무엇이 잘못되었는지 기록
4. 팀과 추적 ID 공유

4. 개발과의 통합

# 코드 커밋 전
langsmith-fetch traces --last-n-minutes 10 --limit 5

# 오류가 발견되면
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---

빠른 참조

# 가장 일반적인 명령어

# 빠른 디버깅
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# 특정 추적
langsmith-fetch trace <trace-id> --format pretty

# 세션 내보내기
langsmith-fetch traces ./debug-session --last-n-minutes 30 --limit 50

# 오류 찾기
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format raw | grep -i error

# 메타데이터 포함
langsmith-fetch traces --limit 10 --include-metadata

---

리소스

• LangSmith Fetch CLI: https://github.com/langchain-ai/langsmith-fetch
• LangSmith Studio: https://smith.langchain.com/
• LangChain 문서: https://docs.langchain.com/
• 이 스킬 저장소: https://github.com/OthmanAdi/langsmith-fetch-skill

---

Claude를 위한 참고 사항

• 명령어를 실행하기 전에 항상 langsmith-fetch가 설치되었는지 확인하세요.
• 환경 변수가 설정되었는지 확인하세요.
• 사람이 읽기 쉬운 출력에는 --format pretty를 사용하세요.
• 데이터를 구문 분석하고 분석해야 할 때는 --format json을 사용하세요.
• 세션을 내보낼 때는 체계적인 폴더 구조를 만드세요.
• 항상 명확한 분석과 실행 가능한 통찰력을 제공하세요.
• 명령어가 실패하면 구성 문제 해결을 도와주세요.

---

버전: 0.1.0 작성자: Ahmad Othman Ammar Adi 라이선스: MIT 저장소: https://github.com/OthmanAdi/langsmith-fetch-skill