원문 보기
GitHub - langchain-ai/langsmith-claude-code-plugins: LangSmith plugins for Claude Code
Service

GitHub - langchain-ai/langsmith-claude-code-plugins: LangSmith plugins for Claude Code

langchain-ai
2026.04.04
·GitHub·by 이호민/AI
#Claude Code#LangSmith#LLM#Plugin#Tracing

핵심 포인트

  • 1이 LangSmith Tracing Plugin for Claude Code는 Claude Code 내의 LLM 대화, 도구 호출, 서브에이전트 실행을 LangSmith로 추적하여 가시성을 제공합니다.
  • 2이 플러그인은 각 LLM 실행의 입력, 출력, 메타데이터, 토큰 사용량뿐만 아니라 도구의 이름, 입력 및 출력을 포함한 상세한 데이터를 LangSmith에 기록합니다.
  • 3또한, 환경 변수를 통해 쉽게 구성할 수 있으며, 기존 LangSmith Run 아래에 Claude Code의 모든 트레이스를 중첩하여 더 큰 워크플로의 일부로 추적할 수 있습니다.

이 문서는 LangChain AI에서 개발한 LangSmith Tracing Plugin for Claude Code에 대한 설명을 담고 있습니다. 이 플러그인의 주요 목적은 Claude Code 환경 내에서 발생하는 대화, 툴 호출, 서브에이전트(subagent) 실행, 그리고 컨텍스트 압축(context compaction) 과정을 LangSmith 플랫폼으로 추적하여 시각화하고 분석할 수 있도록 하는 것입니다.

핵심 방법론 및 기능:

이 플러그인은 Claude Code와 LangSmith 간의 통합을 통해 개발자가 AI 에이전트의 동작을 상세히 이해하고 디버깅할 수 있도록 지원합니다.

  1. 추적 대상 상세화:
    • LLM 실행(LLM Run): 각 LLM 호출에 대해 다음 정보가 LangSmith에 기록됩니다.
      • 입력(Inputs): 누적된 대화 메시지들.
      • 출력(Outputs): 어시스턴트의 응답 내용.
      • 메타데이터(Metadata): ls_provider (예: "anthropic"), ls_model_name, ls_invocation_params (모델명, 중단 이유 등), 그리고 토큰 사용량(token usage)이 포함됩니다.
    • 툴 실행(Tool Run): 사용된 툴의 이름, 입력 인자, 그리고 출력 내용이 기록되어 툴 사용의 흐름을 파악할 수 있습니다.
    • 중단된 턴(Interrupted Turns): 사용자가 응답 도중에 대화를 중단한 경우, 해당 턴은 LangSmith에서 "interrupted" 상태로 표시됩니다.
  1. 설치 및 환경 설정:
    • Claude Code 플러그인 설치: Claude Code 내에서 /plugin marketplace add langchain-ai/langsmith-claude-code-plugins, /plugin install langsmith-tracing@langsmith-claude-code-plugins, 그리고 /reload-plugins 명령어를 통해 쉽게 설치할 수 있습니다.
    • 환경 변수 설정: 플러그인은 LangSmith에 데이터를 전송하기 위해 필요한 환경 변수들을 지원합니다.
      • TRACE_TO_LANGSMITH: 추적 활성화를 위해 반드시 "true"로 설정해야 합니다.
      • CC_LANGSMITH_API_KEY: LangSmith API 키를 지정합니다 (기본적으로 LANGSMITH_API_KEY 환경 변수 값을 사용하기도 함).
      • CC_LANGSMITH_PROJECT: LangSmith 프로젝트 이름을 설정합니다 (기본값 "claude-code").
      • LANGSMITH_ENDPOINT: LangSmith API의 기본 URL을 지정합니다 (기본값 https://api.smith.langchain.com).
      • CC_LANGSMITH_DEBUG: 디버그 로깅을 활성화합니다.
    • 이러한 변수들은 ~/.claude/settings.json 파일에 추가하거나, 쉘(shell) 환경 변수로 export 하여 설정할 수 있습니다.
  1. 기존 실행에 추적 중첩(Nesting Traces under an Existing Run):
    • 이 기능은 Claude Code가 더 큰 규모의 추적되는 워크플로(workflow)의 일부로 프로그래밍 방식으로 호출될 때 유용합니다.
    • CC_LANGSMITH_PARENT_DOTTED_ORDER 환경 변수에 부모 실행(parent run)의 dotted_order를 설정함으로써 Claude Code 내의 모든 추적(trace)을 해당 부모 실행의 자식으로 중첩시킬 수 있습니다.
    • 이는 Python 및 TypeScript 예시 코드에서 langsmith.traceable 데코레이터와 get_current_run_tree() 함수를 사용하여 현재 실행 트리의 정보를 가져와 subprocess.run 또는 execSync 호출 시 환경 변수로 전달하는 방식으로 구현됩니다.
    • 결과적으로 LangSmith에서는 Yourouterrun(chain)−>ClaudeCodeTurn(chain)−>[Claude(llm),Read(tool),Claude(llm)]Your outer run (chain) -> Claude Code Turn (chain) -> [Claude (llm), Read (tool), Claude (llm)]과 같은 계층적 추적 구조를 시각화할 수 있습니다.

제한 사항:

현재 이 플러그인은 서브에이전트가 완료된 후에만 추적합니다. 즉, 서브에이전트 실행 중에 대화 턴을 중단하면 해당 서브에이전트 실행은 LangSmith에 추적되지 않을 수 있습니다.