Debugging Deep Agents with LangSmith

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

LangSmith는 긴 실행과 다중 대화로 복잡해진 딥 에이전트의 디버깅을 실행 추적, Polly의 분석·프롬프트 수정, LangSmith Fetch CLI의 데이터 조회로 지원한다.

📌 핵심 요약

• 딥 에이전트는 수백~수천 줄의 프롬프트, 수십~수백 단계의 실행, 여러 차례의 사용자 대화를 포함해 오류 원인을 파악하기 어렵다.
• LangSmith는 개별 실행 단계인 런, 단일 실행을 나타내는 트레이스, 전체 대화를 묶는 스레드로 에이전트 실행 데이터를 기록한다.
• Polly는 LangSmith 안에서 트레이스와 스레드를 분석하며, 비효율이나 실수를 살펴보고 여러 대화에 걸친 맥락을 확인하도록 돕는다.
• Polly는 프롬프트 플레이그라운드에서 자연어로 설명한 동작에 맞춰 프롬프트를 수정하고 구조화된 출력과 모의 도구 정의를 지원한다.
• LangSmith Fetch CLI는 식별자·시간·프로젝트 기준의 트레이스와 스레드 조회, 여러 출력 형식, 일괄 내보내기를 제공해 Claude Code 같은 코딩 에이전트의 분석과 평가용 데이터 확보를 지원한다.

🧩 주요 포인트

1. 긴 실행과 다중 대화 → 개별 단계부터 전체 대화까지 연결해 오류 원인을 살펴볼 필요가 있다.
2. Polly의 실행 분석과 프롬프트 수정 지원 → 동작을 이해하고 지침을 개선하는 작업을 LangSmith 안에서 진행할 수 있다.
3. LangSmith Fetch CLI의 조회·내보내기 → LangSmith 실행 데이터를 로컬 코딩 에이전트와 평가·분석 작업에 활용할 수 있다.

🧠 상세 정리

1. 딥 에이전트에서 디버깅이 어려워지는 이유

글은 딥 에이전트의 디버깅이 단순한 모델 호출이나 짧은 작업 흐름과 어떻게 다른지 설명하며 시작한다. 딥 에이전트는 수분 동안 실행되고 수십~수백 단계를 거치며 사용자와 여러 차례 대화를 주고받을 수 있다. 프롬프트도 수백~수천 줄에 이르며 역할, 도구 호출 지침, 주요 규칙과 예시를 함께 담는다. 따라서 동작에 문제가 생겨도 어떤 지침이나 판단, 도구 호출이 원인이었는지 바로 드러나지 않는다. 한 번의 실행만으로도 사람이 쉽게 훑거나 이해하기 어려운 정보가 쌓이므로, LangSmith의 실행 추적과 이를 분석하는 인공지능의 필요성을 제시한다.

2. 런·트레이스·스레드로 실행 맥락 기록

LangSmith에서 실행 추적은 에이전트의 실행 데이터를 기록하는 것을 뜻하며, 내부에서 무슨 일이 일어났는지 확인하는 기반이다. 데이터는 런, 트레이스, 스레드라는 세 단위로 구성된다. 런은 모델 호출이나 도구 호출 같은 개별 단계이고, 서로 중첩된 트리 구조를 이룬다. 트레이스는 이러한 런의 트리로 구성된 에이전트의 단일 실행이며, 스레드는 여러 트레이스를 묶어 사용자와 애플리케이션의 전체 대화를 나타낸다. 글은 안내에 따라 몇 분 안에 추적을 설정할 수 있다고 설명한다. 데이터를 기록한 뒤에는 인공지능으로 에이전트의 전체 진행 경로를 분석하고 프롬프트 변경 제안을 받을 수 있다.

3. Polly로 단일 실행과 전체 대화 분석

Polly는 LangSmith 안에서 대화를 통해 트레이스와 스레드 데이터를 분석하는 에이전트 엔지니어링 보조 기능이다. 트레이스 화면에서는 수십~수백 단계를 직접 살펴보는 대신 에이전트의 동작 중 더 효율적으로 바꿀 부분이나 실수가 있었는지 질문할 수 있다. 이는 실패 양상이 여러 단계에 걸쳐 나타날 수 있는 딥 에이전트를 이해하는 데 도움이 된다. 스레드 화면에서는 하나의 실행을 넘어 전체 대화에 포함된 정보에 접근한다. 스레드는 여러 대화 차례뿐 아니라 수시간 또는 수일에 걸친 맥락을 포함할 수 있으므로, Polly는 사람이 계속 기억하기 어려운 대화 흐름을 분석하도록 지원한다.

4. 프롬프트 플레이그라운드에서 동작 개선

글은 시스템 프롬프트를 딥 에이전트의 중요한 구성 요소로 다루고, 프롬프트 플레이그라운드에서 Polly를 활용하는 방법을 소개한다. 사용자가 원하는 동작을 자연어로 설명하면 Polly가 그에 맞춰 프롬프트를 수정한다. 이는 앞서 제시한 실행 분석과 함께 에이전트의 동작을 이해하고 지침을 개선하는 데 활용되는 기능이다. Polly는 프롬프트 문구를 바꾸는 것 외에도 모델 호출의 구조화된 출력이나 모의 도구를 정의하는 작업을 도울 수 있다. 원문은 이 기능을 에이전트 엔지니어링 지원의 일부로 설명하며, 분석 기능과 프롬프트 편집 기능을 각각의 사용 화면에 연결해 제시한다.

5. LangSmith Fetch CLI로 로컬 작업 연결

LangSmith Fetch CLI는 개발 환경이나 Claude Code, DeepAgents 같은 코딩 에이전트에서 작업하려는 사용자를 위한 도구다. LangSmith의 트레이스와 스레드에 접근할 수 있게 해 웹 화면과 로컬 작업 흐름을 연결한다. 원하는 실행을 알고 있다면 식별자로 조회하고, 방금 발생한 실행을 찾을 때는 시간을 기준으로 가져올 수 있다. 출력은 터미널에서 보기 좋은 패널, 읽기 쉽게 정리한 JSON, 간결한 원시 JSON으로 제공된다. 이 데이터는 터미널에서 직접 확인하거나 jq 같은 도구로 전달하거나 언어 모델에 입력해 분석할 수 있다. 글은 이를 에이전트 디버깅, 대화 흐름 분석, 운영 환경의 실행 데이터로 데이터셋을 만드는 작업에 활용할 수 있다고 설명한다.

6. 최근 실행 조회와 일괄 내보내기

CLI의 첫 번째 주요 사용 방식은 에이전트를 실행한 직후 최근 트레이스나 스레드를 가져오는 것이다. 화면에서 식별자를 찾는 과정을 줄일 수 있으며, 최근 30분 같은 시간 필터나 프로젝트 식별자로 조회 범위를 좁힐 수 있다. 예시에서는 특정 프로젝트의 최근 트레이스 또는 최근 5개 트레이스를 가져오는 명령을 제시한다. 두 번째 방식은 평가나 분석에 필요한 여러 스레드를 한꺼번에 내보내는 것으로, 50개 스레드를 가져와 각각 별도 JSON 파일로 저장하는 예시를 든다. 글은 이러한 일괄 내보내기가 배치 처리나 테스트 데이터 구성에 적합하다고 설명한다. 마지막으로 LangSmith에서 실행을 추적한 뒤 Polly로 분석하거나 CLI로 데이터를 코딩 에이전트에 전달하는 두 경로를 정리한다.

🧾 핵심 주장 / 시사점

• 딥 에이전트의 오류 분석에서는 개별 호출의 내용뿐 아니라 여러 실행과 대화가 이어지는 맥락이 중요하다.
• Polly는 실행 데이터를 이해하는 작업과 원하는 동작을 프롬프트에 반영하는 작업을 함께 지원한다.
• LangSmith Fetch CLI는 기록된 실행 데이터를 로컬 디버깅과 평가·분석에 다시 활용할 수 있게 한다.

✅ 액션 아이템

• LangSmith의 런·트레이스·스레드로 긴 실행과 다중 대화의 맥락을 확인.
• Polly로 비효율과 실수를 분석하고 원하는 동작에 맞춰 프롬프트 수정.
• LangSmith Fetch CLI로 필요한 실행 데이터를 조회·내보내기하여 코딩 에이전트 분석과 평가에 활용.

❓ 열린 질문

• 긴 실행과 다중 대화에서 오류 원인을 이해하려면 단일 트레이스와 전체 스레드 중 어느 범위까지 확인해야 하는가?
• Polly가 분석한 비효율이나 실수를 바탕으로 프롬프트의 어떤 지침을 수정해야 하는가?
• LangSmith Fetch CLI로 평가·분석 데이터를 확보할 때 식별자·시간·프로젝트 중 어떤 조회 기준이 필요한가?