LangGraph와 LangSmith 연결하기: AI 에이전트 실행 추적과 디버깅
LangGraph로 AI 에이전트를 만들면 단순한 함수 호출보다 복잡한 흐름을 구성할 수 있습니다. 상태(state)를 여러 노드가 읽고 수정하고, 조건에 따라 다른 노드로 이동하거나 사람의 검토를 기다릴 수도 있습니다. 문제는 실행 결과만 봐서는 어느 노드에서 잘못된 판단이 시작됐는지 찾기 어렵다는 점입니다.
이때 LangSmith를 연결하면 에이전트 실행을 단계별 trace로 확인할 수 있습니다. 각 노드의 입력과 출력, 실행 시간, 오류를 한 화면에서 비교할 수 있어 프롬프트와 워크플로를 개선하기가 쉬워집니다.
LangGraph와 LangSmith의 역할
섹션 제목: “LangGraph와 LangSmith의 역할”두 도구는 서로 대체 관계가 아닙니다.
| 도구 | 담당 영역 |
|---|---|
| LangGraph | 상태, 노드, 엣지, 조건 분기, 재개 가능한 실행 흐름 |
| LangSmith | 실행 trace, 프롬프트·응답 확인, 평가, 모니터링 |
LangGraph가 에이전트의 실행 구조라면 LangSmith는 그 실행을 관찰하는 기록 장치입니다. 특히 여러 번의 LLM 호출이나 도구 호출이 이어지는 에이전트에서는 최종 답변보다 중간 단계의 기록이 더 중요합니다.
설치와 환경 변수 설정
섹션 제목: “설치와 환경 변수 설정”Python 환경에서 다음 패키지를 설치합니다.
pip install -U langgraph langsmithLangSmith 프로젝트에서 발급한 API 키는 소스 코드에 직접 넣지 않고 환경 변수로 관리합니다.
export LANGSMITH_TRACING=trueexport LANGSMITH_API_KEY="lsv2_..."export LANGSMITH_PROJECT="quantylab-agent-dev"LANGSMITH_PROJECT를 지정하면 실행 결과를 애플리케이션별 프로젝트로 분리할 수 있습니다. 개발·스테이징·운영 환경마다 프로젝트 이름을 나누면 실험 trace와 실제 사용자 요청을 섞지 않을 수 있습니다.
가장 작은 LangGraph 예제
섹션 제목: “가장 작은 LangGraph 예제”다음 그래프는 입력된 질문을 받아 답변을 만드는 간단한 예제입니다.
from typing import TypedDict
from langgraph.graph import END, START, StateGraph
class State(TypedDict): question: str answer: str
def answer_question(state: State) -> dict: # 실제 애플리케이션에서는 이곳에서 LLM을 호출합니다. return {"answer": f"질문을 처리했습니다: {state['question']}"}
builder = StateGraph(State)builder.add_node("answer_question", answer_question)builder.add_edge(START, "answer_question")builder.add_edge("answer_question", END)graph = builder.compile()
result = graph.invoke({"question": "LangGraph란 무엇인가?", "answer": ""})print(result["answer"])LangSmith 추적을 활성화한 상태에서 graph.invoke()를 실행하면 그래프 실행이 프로젝트에 기록됩니다. LangGraph와 LangChain 통합을 사용하는 경우에는 노드 안의 모델 호출도 부모 실행의 하위 trace로 나타납니다.
사용자 함수까지 추적하기
섹션 제목: “사용자 함수까지 추적하기”LangGraph 노드가 직접 호출하는 데이터 조회, 문서 검색, 후처리 함수는 @traceable로 감싸면 별도의 실행 단위로 기록할 수 있습니다.
from langsmith import traceable
@traceable(name="load-market-context", run_type="tool")def load_market_context(symbol: str) -> dict: # 데이터베이스나 외부 API 조회 return {"symbol": symbol, "context": "시장 데이터"}
def research_node(state: dict) -> dict: context = load_market_context(state["symbol"]) return {"context": context}이렇게 하면 research_node 안에서 실행된 데이터 조회를 따로 확인할 수 있습니다. 응답이 이상할 때 모델 프롬프트만 의심하지 않고, 검색 결과와 데이터 변환 결과까지 역추적할 수 있습니다.
운영에서 지켜야 할 것
섹션 제목: “운영에서 지켜야 할 것”첫째, API 키와 비밀번호를 graph state에 넣지 않습니다. state는 체크포인터나 디버깅 출력에 저장될 수 있으므로 인증 정보 대신 식별자와 상태만 전달해야 합니다.
둘째, 개인정보와 원문 데이터의 전송 범위를 확인합니다. LangSmith에 기록되는 입력·출력에는 사용자 질문과 검색 문서가 포함될 수 있으므로 필요한 경우 민감한 필드를 마스킹하거나 선택적 tracing을 사용합니다.
셋째, 프로젝트와 태그를 일관되게 사용합니다. 예를 들어 quantylab-agent-dev, quantylab-agent-prod를 분리하고 모델 버전, 데이터 기준일, 실험 이름을 metadata나 tag로 남기면 실행 결과 비교가 쉬워집니다.
마무리
섹션 제목: “마무리”LangGraph는 복잡한 AI 에이전트의 실행 흐름을 명시적으로 만들고, LangSmith는 그 흐름을 관찰하고 개선하게 해줍니다. 먼저 LANGSMITH_TRACING과 프로젝트를 설정한 뒤 그래프 전체를 확인하고, 원인 분석이 필요한 함수에 @traceable을 추가하는 순서가 가장 실용적입니다.
공식 문서도 함께 참고하면 좋습니다.
