LangSmith Engine 이슈 범주

LangSmith Engine 이슈 범주

LangSmith Engine이 감지된 이슈에 할당하는 이슈 범주에 대한 설명과 예시가 포함된 참조예요.

LangSmith Engine이 트레이스에서 반복되는 이슈를 감지하면 이슈에 범주를 태그로 지정해요. 이 페이지는 Engine이 할당하는 모든 범주를 설명과 구체적인 예시와 함께 나열해요. Engine은 트레이스를 자동으로 스캔하고 각 감지된 이슈에 가장 잘 맞는 범주를 할당해요.

이 페이지의 16개 범주는 Engine이 관찰한 가장 흔한 에이전트 실패 패턴을 다뤄요. Engine이 할당한 범주가 실제 문제와 일치하지 않는다면 이유를 함께 이슈를 무시(ignored)로 표시할 수 있어요. Engine은 이 피드백을 사용해 향후 분석을 개선해요. 자세한 내용은 이슈 닫기 또는 다시 열기를 참고하세요.

이슈 분류 체계가 변경될 때 LangSmith는 알림을 보내지 않아요. 기능 업데이트를 확인하려면 LangSmith Cloud 변경 로그를 보거나 LangSmith 지원팀에 문의하세요.

출처: 문서

본문

에이전트 반복 (Agent looping)

에이전트가 사용자 목표를 향해 진전하지 않은 채 단일 트레이스 내에서 동일한 작업을 여러 번 반복해요.

예시: 에이전트가 동일한 검색 도구를 동일한 쿼리로 8번 연속 호출하고, 각 호출이 동일한 결과를 반환하며, 그 결과를 사용해 대화를 진전시키지 않아요.

컨텍스트 폭발 (Context explosion)

트레이스가 (루프가 아닌) 무한 컨텍스트 누적으로 인해 극도로 많은 수의 토큰을 소비했어요.

예시: 다중 턴 대화가 각 LLM 호출에 이전 메시지의 전체 기록을 재생하여, 에이전트가 작업을 반복하지 않는데도 매 턴마다 토큰 수가 커져요.

실패 복구 실패 (Failed error recovery)

도구가 명시적 오류를 반환했고, 에이전트가 접근 방식을 적응시키는 대신 동일하거나 거의 동일한 인수로 동일한 호출을 반복적으로 재시도했어요.

예시: API 호출이 500 오류로 실패하고, 에이전트가 파라미터를 바꾸거나 다른 도구를 시도하지 않고 정확히 동일한 호출을 5번 연속 재시도해요.

기능 격차 (Feature gap)

사용자가 아직 존재하지 않는 정당한 범위 내 기능을 요청해요. 이것은 에이전트 실행 실수가 아니라 충족되지 않은 제품 요구예요.

예시: 사용자가 보고서를 PDF로 내보내기를 반복적으로 요청하지만 애플리케이션에 내보내기 기능이 없어요. 에이전트는 제한 사항을 정확히 설명하지만, 반복되는 요청이 팀이 평가해야 할 충족되지 않은 제품 요구를 드러내요.

결함 있는 계획 (Flawed plan)

에이전트의 접근 방식이 작업에 대한 근본적인 오해를 보여줘요. 답변이 요청된 것과 다른 질문을 다루거나, 첫 도구 호출부터 계획이 잘못됐어요.

예시: 사용자가 월 평균 계산을 요청하지만, 에이전트는 모든 값을 더해 총계를 보고하며 요청된 것과 다른 문제를 해결해요.

가드레일 우회 (Guardrail bypass)

사용자가 다중 턴 조종이나 프롬프트 주입을 통해 의도된 범위 밖의 콘텐츠를 생성하도록 에이전트를 조작했어요.

예시: 사용자가 금융 봇을 정당한 계좌 질문에서 봇이 내도록 승인되지 않은 특정 투자 추천을 생성하도록 점진적으로 유도해요.

환각 (Hallucination)

에이전트의 응답에 어떤 도구 출력에도 존재하지 않는 특정 사실, 숫자 또는 이름이 포함돼요.

예시: 어떤 도구도 해당 숫자를 반환하지 않았는데 에이전트가 "계좌 잔액은 \$4,200입니다"라고 보고해, 에이전트가 그 수치를 지어냈어요.

잘못된 도구 인수 (Incorrect tool args)

에이전트가 올바른 도구를 선택했지만 사용자의 의도나 도구의 스키마와 일치하지 않는 인수로 호출했어요.

예시: 사용자가 주문 #12345를 요청하지만, 에이전트는 잘린 ID "1234"나 임의의 ID로 get-order 도구를 호출해 잘못된 레코드나 빈 결과를 반환해요.

기능 인식 부족 (Missing capability awareness)

에이전트가 가지지 않은 도구를 사용하려 하거나, 처리할 수 있었던 작업을 거부하거나, 프롬프트가 대비하지 못한 사례를 만났어요.

예시: 에이전트의 도구 세트에 검색 도구가 있는데도 에이전트가 사용자에게 "지식 베이스를 검색할 수 없습니다"라고 말해요.

PII 유출 (PII leak)

에이전트의 응답에 주민등록번호, 생년월일, 집 주소, 전화번호, 이메일 주소 또는 API 키 같은 민감한 데이터가 포함돼요. Engine은 민감한 데이터의 출처에 따라 PII 유출을 추가로 분류하는데, 이것은 올바른 수정이 각각 다르기 때문이에요: 에이전트 도입(에이전트가 스스로 민감한 데이터를 생성), 도구 반환 에코(도구 응답에 개발자가 소스에서 필터링할 수 있는 민감한 필드 포함), 또는 사용자 제공 에코(민감한 데이터가 이미 사용자 입력에 있음).

예시: 고객 조회 도구가 SSN과 집 주소를 포함한 전체 사용자 프로필을 반환하고, 에이전트가 사용자에 대한 응답에 그 필드를 모두 포함해요.

응답 잘림 (Response truncation)

에이전트의 응답이 문장 중간이나 코드 블록 중간에서 잘렸어요.

예시: 에이전트의 답변이 "To fix this, you need to update the config fil"로 갑자기 끝나고, 사용자가 에이전트에게 계속하라고 요청해야 해요.

조용한 도구 오류 (Silent tool error)

도구가 예외를 발생시키는 대신 콘텐츠로 오류 메시지를 반환해서, 에이전트가 오류를 유효한 응답으로 취급했어요.

예시: 검색 도구가 결과 콘텐츠로 "404 Not Found"를 반환하고, 에이전트가 그 오류 텍스트를 실제 답변인 것처럼 사용자 응답에 포함해요.

시스템 프롬프트 드리프트 (System prompt drift)

에이전트가 애플리케이션의 목적 외부의 주제를 벗어난 질문에 거절하는 대신 답했어요.

예시: 이커머스 상점의 고객 지원 봇이 "고양이에 관한 시를 써줘"라는 요청에 사용자를 적절한 채널로 안내하는 대신 Python 스크립트를 작성해요.

작업 회피 (Task evasion)

에이전트가 작업이 완료되기 전에 성공을 선언하거나, 어려운 부분을 피하기 위해 작업을 단순화하거나, 대안 접근을 시도하지 않고 단일 실패 후 포기했어요.

예시: 사용자가 세 가지 데이터 소스에 대한 상세 분석을 요청하지만, 에이전트는 단 하나의 소스에서만 한 문장 요약을 만들고 작업이 완료됐다고 선언해요.

추적 품질 (Tracing quality)

프로젝트의 트레이스에 LangSmith 기능을 잠금 해제하는 메타데이터, 태그 또는 구조적 표시가 없어요. 이것은 에이전트의 동작 문제가 아니라 인스트루멘테이션 격차예요.

예시: 트레이스에 메타데이터의 thread_id가 없어 Threads 보기가 대화 턴을 그룹화할 수 없고, LLM 런에 모델 프로바이더 메타데이터가 없어 비용 추적이 null 값을 보여줘요.

잘못된 도구 (Wrong tool)

더 잘 맞는 도구가 존재했지만 에이전트가 사용자 요청에 대해 잘못된 도구를 선택했어요.

예시: 사용자가 ID로 단일 주문을 조회하려 하지만, 에이전트는 "get order by ID" 도구 대신 "list all orders" 도구를 호출해 질문에 직접 답하지 않는 결과 페이지를 반환해요.

더 알아보기

더 알아보기 (Learn more)