LangSmith Studio로 에이전트 시각화하기

LangSmith Studio로 에이전트 시각화하기 (Studio)

로컬에서 LangChain 에이전트를 만들다 보면, 에이전트 내부에서 어떤 일이 벌어지는지 한눈에 보고 싶어질 때가 있어요. LangSmith Studio가 바로 그 역할을 해주는 무료 비주얼 인터페이스예요. 로컬 머신에서 실행 중인 에이전트에 연결해서, 모델로 보내는 프롬프트, 도구 호출과 그 결과, 최종 출력까지 에이전트가 밟는 각 단계를 하나씩 보여줍니다. 입력을 바꿔 테스트하고, 중간 상태를 살펴보고, 추가 코드나 배포 없이 에이전트의 동작을 반복 개선할 수 있어요. 이 페이지에서는 Studio를 로컬 LangChain 에이전트와 연결하는 방법을 설명합니다.

출처: LangChain 공식 문서 — Studio

시작하기 전 준비물 (Prerequisites)

시작하기 전에 다음을 준비해야 해요.

LangSmith 계정: smith.langchain.com에서 무료로 가입하거나 로그인합니다.
LangSmith API 키: API 키 만들기 가이드를 따라 만들면 됩니다.
데이터를 LangSmith에 추적(trace)하고 싶지 않다면, 애플리케이션의 .env 파일에 LANGSMITH_TRACING=false를 설정하세요. 추적을 끄면 어떤 데이터도 로컬 서버 밖으로 나가지 않아요.

로컬 에이전트 서버 준비하기 (Set up local Agent server)

1. LangGraph CLI 설치하기

LangGraph CLI는 에이전트를 Studio와 연결해 주는 로컬 개발 서버(일명 Agent Server)를 제공합니다.

# Python >= 3.11 이 필요합니다.
pip install -U "langgraph-cli[inmem]"

# Python >= 3.11 이 필요합니다.
uv add "langgraph-cli[inmem]"

2. 에이전트 준비하기

이미 LangChain 에이전트가 있다면 그대로 쓰면 돼요. 이 예시는 간단한 이메일 에이전트를 사용합니다.

from langchain.agents import create_agent

def send_email(to: str, subject: str, body: str):
    """Send an email"""
    email = {
        "to": to,
        "subject": subject,
        "body": body
    }
    # ... email sending logic

    return f"Email sent to {to}"

agent = create_agent(
    "gpt-5.5",
    tools=[send_email],
    system_prompt="You are an email assistant. Always use the send_email tool.",
)

3. 환경 변수 설정하기

Studio는 로컬 에이전트에 연결하기 위해 LangSmith API 키가 필요해요. 프로젝트 루트에 .env 파일을 만들고 LangSmith에서 받은 API 키를 추가하세요. .env 파일이 Git 같은 버전 관리에 커밋되지 않도록 꼭 주의하세요.

LANGSMITH_API_KEY=lsv2...

4. LangGraph 설정 파일 만들기

LangGraph CLI는 설정 파일을 참고해서 에이전트를 찾고 의존성을 관리합니다. 앱 디렉터리에 langgraph.json 파일을 만드세요.

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.py:agent"
  },
  "env": ".env"
}

create_agent 함수는 자동으로 컴파일된 LangGraph 그래프를 반환하는데, 설정 파일의 graphs 키가 바로 이걸 기대합니다. JSON 객체의 각 키에 대한 자세한 설명은 LangGraph 설정 파일 문서를 참고하세요.

이 시점에서 프로젝트 구조는 이렇게 생겼어요.

my-app/
├── src
│   └── agent.py
├── .env
└── langgraph.json

5. 의존성 설치하기

루트 디렉터리에서 프로젝트 의존성을 설치합니다.

pip install langchain langchain-openai

uv add langchain langchain-openai

6. Studio에서 에이전트 보기

개발 서버를 시작해서 에이전트를 Studio와 연결합니다.

langgraph dev

Safari는 Studio로의 localhost 연결을 차단하니, 이를 우회하려면 위 명령을 --tunnel 옵션과 함께 실행해서 보안 터널을 통해 Studio에 접근하세요.

서버가 실행되면 에이전트는 http://127.0.0.1:2024의 API와 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024의 Studio UI 양쪽에서 사용할 수 있어요.

Studio UI에서의 에이전트 보기

Studio가 로컬 에이전트에 연결되면 에이전트 동작을 빠르게 반복 개선할 수 있어요. 테스트 입력을 실행하고, 프롬프트·도구 인자·반환 값·토큰/지연 시간 메트릭을 포함한 전체 실행 추적을 살펴보죠. 문제가 생기면 Studio가 주변 상태와 함께 예외를 포착해서 무슨 일이 있었는지 이해하는 데 도움을 줍니다. 이 개발 서버는 핫-리로딩(hot-reloading)을 지원해서, 코드에서 프롬프트나 도구 시그니처를 바꾸면 Studio에 즉시 반영돼요. 어느 단계에서든 대화 스레드를 다시 실행해 변경 사항을 처음부터 다시 시작하지 않고 테스트할 수 있고, 이 워크플로는 단순한 단일 도구 에이전트부터 복잡한 다중 노드 그래프까지 확장됩니다.

Studio를 실행하는 방법에 대한 자세한 내용은 LangSmith 문서의 다음 가이드를 참고하세요.

비디오 가이드

LangSmith Studio v2: The Ultimate Agent Development Environment – YouTube에서 시청하세요.

LangSmith Studio v2: The Ultimate Agent Development Environment (LangChain 공식 채널)

배포된 에이전트에 대한 자세한 내용은 Deployment 문서를 참고하세요.

LangSmith Studio로 에이전트 시각화하기