디버깅은 오류를 찾고 수정하는 과정입니다. 이는 소프트웨어 엔지니어링에서 중요한 단계이며, 특히 에이전트 엔지니어링에서는 더욱 중요합니다. LangSmith의 핵심 기능 중 하나는 LLM 애플리케이션을 디버깅할 수 있는 도구입니다.

오늘 저희는 새롭게 개발되고 있는 '복잡 에이전트(deep agents)'를 위한 이 문제를 해결하는 데 집중하고자 합니다.

본 블로그에서는 다음 내용을 다룹니다:

• 복잡 에이전트를 디버깅하는 것이 단순한 LLM 애플리케이션을 디버깅하는 것과 어떻게 다른지 설명합니다.
• 복잡 에이전트 디버깅을 돕기 위해 LangSmith에 AI 비서인 Polly를 소개합니다.
• 코딩 에이전트(예: Claude Code 또는 DeepAgents CLI)에 디버깅 기능을 갖추게 해주는 CLI 도구 langsmith-fetch를 출시합니다.

복잡 에이전트가 단순한 LLM 애플리케이션과 다른 점

단순한 LLM 호출이나 짧은 워크플로우와 달리, 복잡 에이전트는 몇 분 동안 실행되며 수십 또는 수백 단계에 걸쳐 진행되고, 종종 사용자와의 여러 왕복 상호작용을 포함합니다.

결과적으로, 단일 복잡 에이전트 실행으로 생성되는 트레이스(traces)는 인간이 쉽게 스캔하거나 추론할 수 있는 것보다 훨씬 많은 양의 정보를 담고 있을 수 있습니다. 무언가 잘못되었을 때, 어떤 결정, 프롬프트 지침 또는 도구 호출이 현재 보고 있는 동작을 유발했는지 명확하지 않을 수 있습니다.

이것이 바로 LangSmith를 사용한 트레이싱 — 그리고 AI를 사용하여 해당 트레이스를 분석하는 것 — 이 중요해지는 부분입니다. 그렇다면 구체적으로 무엇이 복잡 에이전트를 더 복잡하게 만들까요?

더 긴 프롬프트(Longer prompts): 심층 에이전트(deep agents)의 프롬프트는 종종 수백, 심지어 수천 줄에 달하며, 일반적으로 일반적인 페르소나, 도구 호출 지침, 중요한 가이드라인 및 몇 가지 예시(few-shot examples)를 포함합니다. 행동이 저하될 때, 어떤 부분이 책임자인지 알기 어렵습니다.더 긴 트레이스(Longer traces): 심층 에이전트는 수십 또는 수백 단계 동안 실행될 수 있습니다(완료하는 데 몇 분 소요). 이렇게 큰 트레이스로 제시되면, 사람이 의미 있는 섹션을 찾으려면 파싱해야 할 내용이 단순히 더 많습니다.여러 턴(Multiple turns): 심층 에이전트는 기본적으로 인간 참여형 루프 워크플로우(human-in-the-loop workflows)를 가능하게 합니다. 심층 에이전트와의 의미 있는 대화 예시는 종종 여러 번의 주고받는 상호작용을 포함합니다. 에이전트가 무엇을 했는지 이해하고 전체 궤적(full trajectory)을 보려면 여러 상호작용에 걸쳐 살펴봐야 합니다.

트레이싱은 관련 정보를 포착합니다

에이전트를 디버깅하려면 내부에서 무슨 일이 일어나고 있는지 가시성이 필요합니다. 바로 여기에 트레이싱(tracing)이 사용됩니다.

저희는 에이전트 실행 데이터를 LangSmith에 로깅하는 것을 설명하기 위해 우산 용어인 트레이싱을 사용합니다. 데이터 형식은 **런(runs), 트레이스(traces), 그리고 스레드(threads)**로 구성됩니다.

런(Runs): 에이전트가 취하는 한 단계입니다. 예시로는 LLM 모델 호출 및 도구 호출이 있습니다. 런은 트리 구조로 중첩됩니다.트레이스(Traces): 에이전트의 단일 실행입니다. 트레이스는 런의 트리로 구성됩니다.스레드(Threads): 트레이스들의 모음입니다. 스레드는 사용자와 애플리케이션 간의 전체 대화입니다.

트레이싱은 설정하기가 매우 쉽습니다. 이 가이드를 따라 몇 분 만에 설정할 수 있습니다.

애플리케이션 데이터가 LangSmith에 들어가면, AI를 활용하여 전체 에이전트 궤적을 분석하고 무슨 일이 일어나고 있는지 파악한 다음, 프롬프트 업데이트를 제안할 수 있습니다. 이를 수행하는 두 가지 주요 방법이 있습니다.

Polly - 에이전트 엔지니어링을 위한 AI 비서

Polly는 사용자가 에이전트와 채팅하여 스레드 및 트레이스 데이터를 분석할 수 있도록 하는 새로운 인앱(in-app) 기능입니다. 여기에서 저희의 영상 개요를 확인하세요.

Polly와 채팅하는 몇 가지 방법은 다음과 같습니다!

Trace 보기에서

Polly를 사용하여 Trace에서 무슨 일이 일어났는지 디버깅하고 분석하며 이해할 수 있습니다. 수십 또는 수백 개의 단계를 수동으로 스캔하는 대신, 다음과 같은 질문을 Polly에게 할 수 있습니다:

• “에이전트가 더 효율적으로 수행할 수 있는 작업이 있었나요?”
• “에이전트가 실수를 했나요?”

이는 실패 모드가 여러 단계에 걸쳐 분산될 수 있는, 트레이스가 긴 딥 에이전트(deep agents)의 경우 특히 유용합니다.

Thread 보기에서

이것은 단일 Trace와 유사하지만, 여기서는 Polly가 전체 Thread의 정보에 접근할 수 있습니다. Thread는 여러 대화 턴을 아우르며, 때로는 몇 시간 또는 며칠에 걸쳐 지속될 수도 있습니다. 이러한 모든 컨텍스트를 사람이 인지하고 유지하기는 어렵습니다.

Prompt Playground에서

딥 에이전트(Deep Agent)의 가장 중요한 부분 중 하나는 시스템 프롬프트입니다. Polly는 훌륭한 프롬프트 엔지니어 역할을 하도록 조정되었습니다! 원하는 동작을 자연어로 설명하기만 하면, Polly가 그에 맞춰 프롬프트를 업데이트할 것입니다. 또한 Polly는 모델 호출에서 구조화된 출력(structured output)을 정의하거나 목업 도구(mock tools)를 설정하는 데 도움을 줄 수도 있습니다.

LangSmith Fetch CLI - 코딩 에이전트를 전문가 에이전트 엔지니어로 만드는 도구

IDE에서 작업하거나 코드 에이전트(예: DeepAgents, Claude Code 등)를 사용하는 것을 선호한다면, LangSmith 트레이스나 스레드에 쉽게 연결할 수 있는 CLI인 LangSmith Fetch가 있습니다.

에이전트를 디버깅하든, 대화 흐름을 분석하든, 프로덕션 트레이스로부터 데이터셋을 구축하든, 이 CLI는 LangSmith 트레이스와 스레드에 빠르고 유연하게 접근할 수 있도록 제공합니다.

이는 LangSmith UI와 로컬 워크플로우 사이의 격차를 해소하여, 정확히 원하는 것이 있다면 ID로, 방금 일어난 것을 가져와야 한다면 시간으로 트레이스나 스레드를 가져올 수 있게 합니다. 여러 출력 형식(사람이 읽기 쉬운 패널, 예쁜 JSON, 또는 간결한 원시 JSON)을 지원하는 이 도구는 터미널에서 데이터를 검사하거나, jq로 파이프하거나, 분석을 위해 LLM에 결과를 공급하든 사용 사례에 맞게 조정됩니다.

이 도구는 두 가지 주요 워크플로우를 가능하게 합니다. 첫째, '방금 무언가를 실행함(I just ran something)' 워크플로우로 최근 스레드를 가져옵니다. 에이전트를 실행한 후, UI에서 ID를 찾느라 헤맬 필요 없이 langsmith-fetch threads ./my_data를 즉시 실행하여 가장 최근의 트레이스를 가져올 수 있습니다. --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

둘째, 일괄 내보내기(bulk export) 워크플로우입니다. 평가나 분석을 위한 데이터셋이 필요할 때, langsmith-fetch threads ./my-data --limit 50 같은 명령어를 사용하여 여러 스레드를 가져오고 각각을 별도의 JSON 파일로 저장할 수 있습니다. 이는 배치 처리나 테스트 세트 구축에 완벽합니다.

# 또는 특정 프로젝트의 마지막 5개 트레이스 가져오기

langsmith-fetch traces --project-uuid <your-uuid> --limit 5

물론, 원하는 스레드 ID나 트레이스 ID를 직접 지정할 수도 있습니다. 출력 형식은 필요에 따라 조정됩니다: Rich 패널을 사용한 터미널 보기용 --format pretty, 가독성 높은 구조화된 데이터용 --format json, 또는 다른 도구로 파이프하기 위한 --format raw가 있습니다.

LangSmith를 사용하면 깊은 에이전트(deep agents) 디버깅 및 개선이 쉬워집니다

깊은 에이전트는 강력하지만 단순한 LLM 워크플로우보다 실행 시간이 길고 복잡합니다. 이를 이해하고 개선하려면, 깊은 에이전트가 실제로 무엇을 하고 있는지에 대한 가시성이 필요합니다.

LangSmith를 사용하면 깊은 에이전트를 추적(trace)하여 무슨 일이 일어나고 있는지 볼 수 있으며, 이후 Polly와 채팅하여 깊은 에이전트의 동작을 분석하고 AI를 사용하여 프롬프트를 개선하는 데 도움을 받을 수 있습니다. 만약 Claude Code나 다른 코딩 에이전트로 분석하기를 원한다면, LangSmith Fetch를 사용하여 코딩 에이전트에 필요한 모든 디버깅 도구를 장착할 수 있습니다.

단 몇 분 만에 트레이싱을 설정하고, 오늘 바로 LangSmith에서 Polly와 채팅하며 깊은 에이전트를 디버깅하고 개선해 보세요!