LangSmith Studio

LangSmith Studio (Studio)

LangChain 에이전트를 로컬에서 개발할 때 에이전트 내부에서 벌어지는 일을 시각화하고, 실시간으로 상호작용하며, 문제가 생길 때 바로 디버깅할 수 있으면 정말 편리하죠. LangSmith Studio는 로컬 머신에서 LangChain 에이전트를 개발·테스트할 수 있는 무료 시각 인터페이스예요. Studio는 로컬에서 실행 중인 에이전트에 연결해 에이전트가 밟는 각 단계를 보여줘요 — 모델에 보낸 프롬프트, 도구 호출과 그 결과, 최종 출력까지요. 이 문서는 로컬 LangChain 에이전트에 Studio를 설정하는 방법을 설명할게요.

출처: 공식문서

사전 요구사항 (Prerequisites)

시작 전에 다음이 준비돼 있어야 해요.

  • LangSmith 계정: smith.langchain.com에서 무료로 가입하거나 로그인해요.
  • LangSmith API 키: Create an API key 가이드를 따라요.
  • 데이터를 LangSmith로 추적하고 싶지 않다면 애플리케이션의 .env 파일에 LANGSMITH_TRACING=false를 설정해요. 추적을 끄면 데이터가 로컬 서버 밖으로 나가지 않아요.

로컬 에이전트 서버 설정 (Set up local Agent server)

1. LangGraph CLI 설치

LangGraph CLI는 에이전트를 Studio에 연결하는 로컬 개발 서버(Agent Server라고도 함)를 제공해요.

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

2. 에이전트 준비

이미 LangChain 에이전트가 있다면 그대로 사용하면 돼요. 이 예제는 간단한 이메일 에이전트를 사용해요 (agent.py).

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 configuration file reference를 참고해요.

이 시점에 프로젝트 구조는 다음과 같아요.

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

5. 의존성 설치

루트 디렉터리에서 프로젝트 의존성을 설치해요.

pip install langchain langchain-openai

uv를 쓴다면:

uv add langchain langchain-openai

6. Studio에서 에이전트 보기

개발 서버를 시작해 에이전트를 Studio에 연결해요.

langgraph dev

Safari는 Studio에 대한 localhost 연결을 차단해요. 이 문제를 우회하려면 위 명령을 --tunnel로 실행해 보안 터널을 통해 Studio에 접근해요. Studio UI에서 Connect to a local server를 클릭해 터널 URL을 허용 오리진에 수동으로 추가해야 해요. 단계는 troubleshooting guide를 참고해요.

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

Studio가 로컬 에이전트에 연결되면 에이전트 동작을 빠르게 반복 개선할 수 있어요. 테스트 입력을 실행하고, 프롬프트·도구 인자·반환 값·토큰/지연 메트릭을 포함한 전체 실행 트레이스를 LangSmith에서 검사해요. 문제가 생기면 Studio가 주변 상태와 함께 예외를 캡처해 무엇이 일어났는지 이해를 도와줘요.

개발 서버는 핫 리로딩을 지원해요 — 코드의 프롬프트나 도구 시그니처를 바꾸면 Studio에 즉시 반영돼요. 어떤 단계에서든 대화 스레드를 다시 실행해 처음부터 시작하지 않고 변경 사항을 테스트할 수 있어요. 이 워크플로우는 단순한 단일 도구 에이전트부터 복잡한 멀티노드 그래프까지 확장돼요.

Studio 실행 방법에 대한 더 자세한 내용은 LangSmith 문서의 다음 가이드를 참고해요: Run application, Manage assistants, Manage threads, Iterate on prompts, Debug LangSmith traces, Add node to dataset.

더 알아보기 (Learn more)