LangSmith로 에이전트 실행 추적 읽기

최종 답만으로 원인을 찾기 어려운 이유

일반 프로그램은 같은 입력에 같은 결과를 내는 함수와 명시적인 오류 로그로 문제를 좁히는 경우가 많습니다. LLM 애플리케이션은 모델 응답이 달라질 수 있고, 프롬프트·검색 결과·도구 반환값이 다음 단계를 계속 바꿉니다. 사용자가 본 마지막 문장만 저장하면 그 답이 만들어진 경로를 재현하기 어렵습니다.

에이전트는 모델, 검색기와 도구를 여러 번 호출하므로 최종 답이 틀렸다는 사실만으로는 검색 결과가 나빴는지, 모델이 도구를 잘못 골랐는지, 도구가 실패했는지 알 수 없습니다. 트레이스(Trace)는 한 요청의 전체 실행 경로를 나타내는 실행 트리이고, 그 안의 프롬프트·모델·검색·도구 같은 개별 단계를 런(Run)이라고 부릅니다. 최상위 런 아래에 자식 런이 부모·자식 관계로 연결되며, 각 런의 입력, 출력, 오류와 걸린 시간을 따라가면 결과가 아니라 과정부터 조사할 수 있습니다.

그림: 실행 트리는 단계별 입력·출력·지연 시간과 오류를 연결합니다.

LangChain 애플리케이션에서는 환경 변수로 추적을 켤 수 있습니다. 실제 값은 소스 코드에 저장하지 않습니다.

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="발급받은_키"
export LANGSMITH_PROJECT="agent-beginner"

설정을 적용한 뒤 기존 체인이나 에이전트를 실행하면 지원되는 호출이 프로젝트의 트레이스로 전송됩니다. API 키와 네트워크가 필요한 외부 서비스이므로 이 문서 환경에서는 실제 전송을 실행하지 않았습니다.

환경 변수는 관측 기능을 켜는 설정일 뿐, 애플리케이션의 실행 흐름을 바꾸는 코드는 아닙니다. 프로젝트 이름을 개발·검증·운영 환경별로 구분하고, 배포 버전이나 사용자 요청 식별자를 메타데이터로 남기면 같은 증상을 비교하기 쉽습니다. 반대로 원문 전체를 무조건 기록하면 검색 편의보다 개인정보 노출 위험이 커질 수 있습니다.

트레이스에서 확인할 순서

먼저 사용자 요청과 시간대를 기준으로 실패한 전체 실행을 찾습니다. 그다음 오류가 난 자식 실행과 예상보다 오래 걸린 구간을 열고, 바로 앞 단계의 출력이 다음 단계에 어떤 입력으로 전달됐는지 거슬러 올라갑니다. 모델 입력에 검색 문맥이 실제로 들어갔는지, 도구 인자가 예상 스키마와 맞는지, 재시도가 몇 번 발생했는지를 확인합니다. 관측성은 오류를 자동으로 고치는 기능이 아니라 원인을 재현할 근거를 남기는 기능입니다.

조사 결과는 세 종류로 나누면 다음 행동이 분명해집니다. 검색 결과가 잘못되었다면 색인이나 검색 설정을 고치고, 올바른 문맥을 모델이 무시했다면 프롬프트와 출력 검증을 살핍니다. 도구가 실패했다면 타임아웃, 입력 스키마와 재시도 정책을 확인합니다. 지연 시간과 토큰 사용량도 단계별로 봐야 가장 비싼 구간을 최적화할 수 있습니다.

트레이스에는 사용자 입력과 검색 문서, 도구 결과가 포함될 수 있습니다. 개인정보와 비밀값을 보내도 되는지 확인하고 필요한 마스킹·보존 기간·접근 권한을 정합니다. 운영 트레이스는 개별 실패를 설명하는 자료이고, 여러 대표 입력에 대한 품질 변화를 판단하려면 별도의 평가 데이터셋과 점수가 필요합니다. 관측과 평가는 서로 보완하지만 같은 작업은 아닙니다.

실행 추적으로 단계별 호출과 병목을 파악했다면, 다음 단계에서는 모델이 도구를 선택하고 결과를 관찰하는 ReAct와 도구 호출을 살펴봅니다.

참고 문서

• LangSmith 공식 문서 — Observability
• LangSmith 공식 문서 — Trace with LangChain