LangSmith Studio

로컬에서 LangChain 에이전트를 만들다 보면 에이전트 안에서 무슨 일이 벌어지는지 보고, 실시간으로 상호작용하며, 문제가 생기면 그때그때 디버깅하고 싶어질 거예요. LangSmith Studio는 로컬 머신에서 LangChain 에이전트를 개발·테스트하기 위한 무료 시각 인터페이스예요.

Studio는 로컬에서 실행 중인 에이전트에 연결해 에이전트가 내딛는 각 단계를 보여줘요. 모델로 보내는 프롬프트, 도구 호출과 그 결과, 그리고 최종 출력까지 말이죠. 추가 코드나 배포 없이도 서로 다른 입력을 테스트하고, 중간 상태를 살펴보고, 에이전트의 동작을 반복해서 개선할 수 있어요.

이 페이지에서는 로컬 LangChain 에이전트에 Studio를 연결하는 방법을 설명해요.

출처: 문서

본문

사전 준비 (Prerequisites)

시작 전에 준비할 게 있어요.

LangSmith 계정: smith.langchain.com에서 (무료로) 가입하거나 로그인해요.
LangSmith API 키: API 키 만들기 가이드를 따라 만들어요.
데이터가 트레이스로 LangSmith에 기록되지 않길 원한다면, 애플리케이션의 .env 파일에 LANGSMITH_TRACING=false를 설정해요. 트레이싱을 끄면 어떤 데이터도 로컬 서버 밖으로 나가지 않아요.

로컬 Agent 서버 설정 (Set up local Agent server)

1. LangGraph CLI 설치

LangGraph CLI는 에이전트를 Studio에 연결해 주는 로컬 개발 서버(즉 Agent Server)를 제공해요.

# Python >= 3.11 is required.
pip install --upgrade "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를 쓴다면:

uv add langchain langchain-openai

6. Studio에서 에이전트 보기

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

langgraph dev

Safari는 localhost 연결을 Studio로 차단해요. 이 문제를 피하려면 위 명령을 --tunnel로 실행해 보안 터널을 통해 Studio에 접근하면 돼요. Studio UI에서 Connect to a local server를 눌러 터널 URL을 허용된 origin에 직접 추가해야 할 수 있어요. 자세한 절차는 트러블슈팅 가이드를 참고해요.

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

Studio가 로컬 에이전트에 연결되면 에이전트의 동작을 빠르게 반복 개선할 수 있어요. 테스트 입력을 실행하고, 프롬프트·도구 인자·반환값·토큰/지연 시간 지표를 포함한 전체 실행 트레이스를 LangSmith에서 살펴보세요. 뭔가 잘못되면 Studio가 주변 상태와 함께 예외를 캡처해 상황 파악을 도와줘요.

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

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

LangSmith Studio