LangSmith Studio

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

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

이 페이지는 로컬 LangChain 에이전트와 Studio를 설정하는 방법을 설명합니다.

출처: 공식문서

사전 준비

시작하기 전에 다음이 준비되어 있어야 해요.

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

로컬 에이전트 서버 설정

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

pip install langchain langchain-openai

uv add langchain langchain-openai

6. Studio에서 에이전트 보기

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

langgraph dev

⚠️ 경고 — Safari는 Studio에 대한 localhost 연결을 차단해요. 이 문제를 우회하려면 위 명령을 --tunnel과 함께 실행해 보안 터널을 통해 Studio에 접근하세요. Studio UI에서 Connect to a local server를 클릭해 터널 URL을 허용된 오리진에 수동으로 추가해야 합니다. 절차는 트러블슈팅 가이드를 참고하세요.

서버가 실행되면 에이전트는 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 문서의 다음 가이드를 참고하세요.

LangSmith Studio