LangSmith 옵저버빌리티

LangSmith 옵저버빌리티 (LangSmith Observability)

LangChain으로 에이전트를 만들고 실행하다 보면, 에이전트가 실제로 어떻게 행동하는지 눈으로 확인하고 싶어져요. 어떤 도구를 호출하는지, 어떤 프롬프트를 생성하는지, 어떻게 결정을 내리는지요. create_agent로 만든 LangChain 에이전트는 LangSmith를 통한 트레이싱(tracing)을 자동으로 지원해요. LangSmith는 LLM 애플리케이션의 동작을 캡처하고 디버깅·평가·모니터링하는 플랫폼이죠.

출처: LangChain 공식 문서 — LangSmith Observability

트레이스란 (Traces)

트레이스(Traces)는 최초 사용자 입력부터 최종 응답까지 에이전트 실행의 모든 단계를 기록해요. 모든 도구 호출, 모델 상호작용, 결정 지점이 포함됩니다. 이런 실행 데이터는 문제를 디버깅하고, 다양한 입력에 대한 성능을 평가하며, 운영(production)에서 사용 패턴을 모니터링하는 데 도움을 줘요.

이 가이드에서는 LangChain 에이전트에 트레이싱을 활성화하고 LangSmith로 실행을 분석하는 방법을 보여드릴게요.

사전 준비 (Prerequisites)

시작 전에 다음이 필요해요.

트레이싱 활성화 (Enable tracing)

모든 LangChain 에이전트는 LangSmith 트레이싱을 자동으로 지원해요. 활성화하려면 다음 환경 변수를 설정하면 됩니다.

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

퀵스타트 (Quickstart)

트레이스를 LangSmith에 기록하는 데 별도의 코드가 필요 없어요. 평소처럼 에이전트 코드를 실행하기만 하면 됩니다.

from langchain.agents import create_agent

def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""
    # ... email sending logic
    return f"Email sent to {to}"

def search_web(query: str):
    """Search the web for information."""
    # ... web search logic
    return f"Search results for: {query}"

agent = create_agent(
    model="gpt-5.5",
    tools=[send_email, search_web],
    system_prompt="You are a helpful assistant that can send emails and search the web."
)

# Run the agent - all steps will be traced automatically
response = agent.invoke({
    "messages": [{"role": "user", "content": "Search for the latest AI news and email a summary to [email protected]"}]
})

기본적으로 트레이스는 default라는 이름의 프로젝트에 기록돼요. 커스텀 프로젝트 이름을 설정하려면 Log to a project를 참고하세요.

선택적으로 트레이스하기 (Trace selectively)

LangSmith의 tracing_context 컨텍스트 매니저를 사용하면 특정 호출이나 애플리케이션 일부만 트레이스할 수 있어요.

import langsmith as ls

# This WILL be traced
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to [email protected]"}]})

# This will NOT be traced (if LANGSMITH_TRACING is not set)
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

프로젝트에 기록하기 (Log to a project)

정적으로 (Statically): 전체 애플리케이션에 대한 커스텀 프로젝트 이름을 LANGSMITH_PROJECT 환경 변수로 설정할 수 있어요.

export LANGSMITH_PROJECT=my-agent-project

동적으로 (Dynamically): 특정 작업에 대해 프로그래밍 방식으로 프로젝트 이름을 설정할 수도 있어요.

import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "Send a welcome email"}]
    })

트레이스에 메타데이터 추가하기 (Add metadata to traces)

트레이스에 커스텀 메타데이터와 태그를 붙여 주석을 달 수 있어요.

response = agent.invoke(
    {"messages": [{"role": "user", "content": "Send a welcome email"}]},
    config={
        "tags": ["production", "email-assistant", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)

tracing_context도 세밀한 제어를 위해 태그와 메타데이터를 받아요.

with ls.tracing_context(
    project_name="email-agent-test",
    enabled=True,
    tags=["production", "email-assistant", "v1.0"],
    metadata={"user_id": "user_123", "session_id": "session_456", "environment": "production"}):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "Send a welcome email"}]}
    )

이런 커스텀 메타데이터와 태그는 LangSmith의 트레이스에 붙습니다.

트레이스를 이용해 에이전트를 디버깅·평가·모니터링하는 방법을 더 알고 싶다면 LangSmith 문서를 참고하세요.

더 알아보기 (Learn more)