2025년 12월 10일
디버깅은 오류를 찾아내고 수정하는 과정입니다. 이는 소프트웨어 엔지니어링에서 중요한 단계이며, 에이전트 엔지니어링에서는 더욱 중요합니다. LangSmith의 핵심 기능 중 하나는 LLM 애플리케이션을 디버깅하는 도구입니다.
오늘 우리는 현재 개발되고 있는 새로운 물결의 “딥 에이전트” 문제 해결에 전력을 기울이고 있습니다.
이 블로그에서는 다음을 다룹니다:
- 딥 에이전트 디버깅이 단순한 LLM 애플리케이션 디버깅과 다른 이유 설명
- 딥 에이전트 디버깅을 위한 LangSmith의 AI 어시스턴트인 Polly 소개
- Claude Code 또는 DeepAgents CLI와 같은 코딩 에이전트에 디버깅 기능을 장착하기 위한 CLI인 langsmith-fetch 출시
딥 에이전트가 단순한 LLM 애플리케이션과 다른 점
단순한 LLM 호출이나 짧은 워크플로우와 달리, 딥 에이전트는 수 분 동안 실행되며, 수십 개 또는 수백 개의 단계에 걸쳐 있고, 종종 사용자와의 여러 차례 상호작용을 포함합니다.
그 결과, 단일 딥 에이전트 실행으로 생성된 트레이스는 엄청난 양의 정보를 담고 있으며, 이는 사람이 쉽게 훑어보거나 파악하기에는 너무 방대합니다. 무언가 잘못되었을 때, 현재 보고 있는 동작을 유발한 결정, 프롬프트 지시사항 또는 도구 호출이 무엇인지 명확하지 않을 수 있습니다.
바로 이 지점에서 LangSmith를 사용한 트레이싱과 AI를 활용한 트레이스 분석이 중요해집니다. 그렇다면 구체적으로 딥 에이전트가 더 복잡한 이유는 무엇일까요?
- 더 긴 프롬프트: 딥 에이전트의 프롬프트는 종종 수백 줄에서 수천 줄에 걸쳐 있습니다. 일반적으로 전반적인 페르소나, 도구 호출 지시사항, 중요한 가이드라인, 그리고 퓨샷 예제를 포함합니다. 동작이 저하될 때, 프롬프트의 어느 부분이 원인인지 파악하기 어렵습니다.
- 더 긴 트레이스: 딥 에이전트는 수십 개에서 수백 개의 단계로 실행될 수 있으며(완료까지 수 분 소요), 이렇게 큰 트레이스가 제시되면 사람이 의미 있는 섹션을 찾기 위해 파싱해야 할 내용이 훨씬 더 많아집니다.
- 다중 턴: 딥 에이전트는 기본적으로 human-in-the-loop 워크플로우를 가능하게 합니다. 딥 에이전트와의 의미 있는 대화 예시는 여러 차례 주고받는 상호작용을 포함하는 경우가 많습니다. 에이전트가 무엇을 했는지 이해하고 전체 궤적을 보려면 여러 상호작용을 살펴봐야 합니다.
에이전트를 디버깅하려면 내부에서 무슨 일이 일어나고 있는지에 대한 가시성이 필요합니다. 바로 여기서 트레이싱이 등장합니다.
우리는 에이전트 실행 데이터를 LangSmith에 로깅하는 것을 트레이싱이라는 포괄적인 용어로 설명합니다. 데이터 형식은 런(runs), 트레이스(traces), 그리고 스레드(threads) 로 구성됩니다.
- 런(Runs): 에이전트가 수행하는 단계입니다. LLM 모델 호출과 도구 호출이 예시에 해당합니다. 런은 트리 구조로 중첩됩니다.
- 트레이스(Traces): 에이전트의 단일 실행입니다. 트레이스는 런의 트리로 구성됩니다.
- 스레드(Threads): 트레이스의 모음입니다. 스레드는 사용자와 애플리케이션 간의 전체 대화입니다.
트레이싱은 설정이 매우 쉽습니다. 이 가이드를 따라 몇 분 안에 설정할 수 있습니다.
애플리케이션 데이터가 LangSmith에 들어오면 AI를 활용하여 전체 에이전트 궤적을 분석하고 무슨 일이 일어나고 있는지 파악한 다음, 프롬프트에 대한 업데이트를 제안할 수 있습니다. 이를 수행하는 두 가지 주요 방법이 있습니다.
Polly - 에이전트 엔지니어링을 위한 AI 어시스턴트
Polly는 스레드와 트레이스 데이터를 분석하기 위해 에이전트와 대화할 수 있는 새로운 인앱 기능입니다. 비디오 개요는 여기에서 확인하세요.
Polly와 대화하는 몇 가지 방법을 소개합니다!
트레이스 뷰에서
Polly를 사용하여 트레이스에서 발생한 일을 디버깅하고, 분석하고, 이해할 수 있습니다. 수십 개 또는 수백 개의 단계를 수동으로 스캔하는 대신, 다음과 같은 질문을 Polly에게 할 수 있습니다:
- “에이전트가 더 효율적으로 수행할 수 있었던 작업이 있나요?”
- “에이전트가 실수한 부분이 있나요?”
이는 특히 더 긴 트레이스를 가지며 실패 모드가 많은 단계에 분산될 수 있는 딥 에이전트에 유용합니다.
스레드 뷰에서
이는 단일 트레이스와 유사하지만, 여기서는 Polly가 전체 스레드의 정보에 접근할 수 있습니다. 스레드는 여러 대화 턴에 걸쳐 있으며, 때로는 몇 시간 또는 며칠에 걸쳐 있을 수도 있습니다. 사람이 이 모든 맥락을 인지하고 있기는 어렵습니다.
프롬프트 플레이그라운드에서
딥 에이전트의 가장 중요한 부분 중 하나는 시스템 프롬프트입니다. Polly는 뛰어난 프롬프트 엔지니어가 되도록 튜닝되었습니다! 원하는 동작을 자연어로 설명하기만 하면 Polly가 프롬프트를 그에 맞게 업데이트합니다. Polly는 또한 모델 호출에서 구조화된 출력을 정의하거나 목(mock) 도구를 정의하는 데 도움을 줄 수 있습니다.
LangSmith Fetch CLI - 코딩 에이전트를 전문 에이전트 엔지니어로 만드는 도구
IDE나 코드 에이전트(예: DeepAgents, Claude Code 등)에서 작업하는 것을 선호한다면, LangSmith 트레이스나 스레드에 쉽게 연결할 수 있는 CLI LangSmith Fetch가 있습니다. 에이전트를 디버깅하거나, 대화 흐름을 분석하거나, 프로덕션 트레이스에서 데이터셋을 구축하는 경우, 이 CLI는 LangSmith 트레이스와 스레드에 빠르고 유연한 접근을 제공합니다.
이는 LangSmith UI와 로컬 워크플로우 사이의 간극을 메워주며, 정확히 원하는 것을 알고 있을 때는 ID로 트레이스나 스레드를 가져올 수 있고, 방금 발생한 것을 잡아야 할 때는 시간으로 가져올 수 있습니다. 여러 출력 형식(사람이 읽기 쉬운 패널, 예쁜 JSON, 또는 압축된 raw JSON)을 지원하므로, 터미널에서 데이터를 검사하거나, jq로 파이핑하거나, 분석을 위해 LLM에 결과를 공급하는 등 사용 사례에 맞게 도구를 조정할 수 있습니다.
이는 두 가지 주요 워크플로우를 가능하게 합니다. 첫째, 최근 스레드를 가져오는 “방금 무언가를 실행했어요” 워크플로우입니다: 에이전트를 실행한 다음, 즉시 langsmith-fetch threads ./my_data를 실행하여 UI에서 ID를 찾을 필요 없이 프로젝트의 가장 최근 트레이스를 가져옵니다. --last-n-minutes 30과 같은 시간 필터를 추가하여 검색 범위를 좁히거나, --project-uuid를 사용하여 특정 프로젝트를 타겟팅할 수 있습니다.
# 방금 에이전트를 실행했나요? 가장 최근 트레이스를 즉시 가져오세요
langsmith-fetch traces --project-uuid <your-uuid> --format json
# 또는 마지막 5개의 트레이스를 가져오세요
langsmith-fetch traces --project-uuid <your-uuid> --limit 5둘째, 대량 내보내기 워크플로우입니다: 평가나 분석을 위한 데이터셋이 필요할 때, langsmith-fetch threads ./my-data --limit 50과 같은 명령은 여러 스레드를 가져와 각각을 별도의 JSON 파일로 저장하며, 배치 처리나 테스트 세트 구축에 완벽합니다.
# 또는 특정 프로젝트에서 마지막 5개의 트레이스를 가져오세요
langsmith-fetch traces --project-uuid <your-uuid> --limit 5물론 원하는 스레드 또는 트레이스 ID를 직접 제공할 수도 있습니다. 출력 형식은 필요에 따라 조정됩니다: Rich 패널로 터미널에서 보려면 --format pretty, 읽기 쉬운 구조화된 데이터를 위해서는 --format json, 또는 다른 도구로 파이핑하려면 --format raw를 사용하세요.
LangSmith를 사용하면 딥 에이전트를 쉽게 디버깅하고 개선할 수 있습니다
딥 에이전트는 강력하지만 단순한 LLM 워크플로우보다 실행 시간이 길고 더 복잡합니다. 이를 이해하고 개선하려면 딥 에이전트가 실제로 무엇을 하고 있는지에 대한 가시성이 필요합니다.
LangSmith를 사용하면 딥 에이전트를 트레이싱하고 무슨 일이 일어나고 있는지 확인할 수 있습니다. 그런 다음 Polly와 대화하여 딥 에이전트의 동작을 분석하고 AI를 활용하여 프롬프트를 개선할 수 있습니다. Claude Code 또는 다른 코딩 에이전트로 분석하는 것을 선호한다면 LangSmith Fetch를 사용하여 코딩 에이전트에 필요한 모든 디버깅 도구를 장착할 수 있습니다.
단 몇 분 안에 트레이싱을 설정하고, LangSmith에서 Polly와 대화를 시도하여 딥 에이전트를 디버깅하고 개선해보세요!