LangSmith Deployment 배포 완벽 가이드

LangGraph로 만든 AI 에이전트를 LangSmith를 통해 클라우드에 배포하는 방법을 알아봅니다. GitHub 연결부터 API 엔드포인트 획득, SDK 클라이언트 활용까지 실무에서 바로 적용할 수 있는 내용을 다룹니다.

---

목차

1. GitHub_저장소_연결
2. LangSmith_Deployments_설정
3. 배포_완료_및_Studio_테스트
4. API_URL_획득
5. langgraph_sdk_클라이언트
6. 상태_유지_에이전트_호스팅

---

1. GitHub 저장소 연결

김개발 씨는 드디어 LangGraph로 멋진 AI 에이전트를 완성했습니다. 로컬에서 테스트해보니 완벽하게 동작합니다.

그런데 문득 고민이 생겼습니다. "이걸 어떻게 다른 사람들도 사용할 수 있게 만들지?"

LangSmith Deployment는 LangGraph 애플리케이션을 클라우드에 배포하는 서비스입니다. 마치 카페에서 직접 만든 레시피를 프랜차이즈로 확장하는 것과 같습니다.

로컬에서 잘 동작하던 코드를 전 세계 어디서나 접근 가능한 API로 만들어주는 것이죠. 이를 위해 가장 먼저 해야 할 일은 코드를 GitHub에 올리는 것입니다.

다음 코드를 살펴봅시다.

# 프로젝트 구조 예시
my-agent/
├── src/
│   └── agent/
│       ├── __init__.py
│       ├── graph.py      # LangGraph 에이전트 정의
│       └── utils.py      # 유틸리티 함수
├── langgraph.json        # 배포 설정 파일 (필수)
├── pyproject.toml        # 의존성 정의
└── .env.example          # 환경변수 템플릿

# langgraph.json 예시
{
    "graphs": {
        "agent": "./src/agent/graph.py:graph"
    },
    "env": ".env"
}

김개발 씨는 입사 6개월 차 AI 개발자입니다. 최근 몇 주간 밤낮으로 작업한 결과, 드디어 고객 문의에 자동으로 응답하는 AI 에이전트를 완성했습니다.

로컬 환경에서 테스트해보니 정말 잘 동작합니다. 이제 이것을 실제 서비스에 연결해야 하는데, 막막하기만 합니다.

옆자리 박시니어 씨가 화면을 힐끗 보더니 말을 건넵니다. "LangSmith Deployment 써봤어?

GitHub 연결하면 알아서 배포해주던데." 그렇다면 GitHub 저장소 연결이란 정확히 무엇일까요? 쉽게 비유하자면, GitHub 저장소는 마치 요리사의 레시피 노트와 같습니다.

여러분이 개발한 AI 에이전트의 모든 코드와 설정이 이 노트에 담겨 있습니다. LangSmith는 이 레시피 노트를 읽어서 실제로 요리를 만들어주는 주방 시스템인 셈입니다.

노트가 없으면 주방에서 무엇을 만들어야 할지 알 수 없겠죠. GitHub 연결이 없던 시절에는 어땠을까요?

개발자들은 서버를 직접 구축하고, Docker 이미지를 만들고, 쿠버네티스를 설정하는 등 복잡한 작업을 거쳐야 했습니다. 인프라 전문가가 아니면 엄두도 내기 어려운 일이었습니다.

더 큰 문제는 코드가 바뀔 때마다 이 모든 과정을 반복해야 한다는 것이었습니다. 바로 이런 문제를 해결하기 위해 LangSmith의 GitHub 연동 기능이 등장했습니다.

저장소를 연결하면 코드 변경사항이 자동으로 감지됩니다. 새로운 커밋이 푸시되면 LangSmith가 알아서 재배포를 진행합니다.

마치 Google Docs처럼 저장하면 바로 반영되는 것과 비슷합니다. 위의 코드에서 프로젝트 구조를 살펴보겠습니다.

가장 중요한 파일은 langgraph.json입니다. 이 파일이 없으면 LangSmith는 여러분의 프로젝트를 인식하지 못합니다.

graphs 항목에는 배포할 에이전트의 경로를 지정합니다. ./src/agent/graph.py:graph라고 적으면 해당 파일의 graph라는 이름의 객체를 찾아 배포합니다.

실제 현업에서는 어떻게 활용할까요? 대부분의 팀은 이미 GitHub를 사용하고 있습니다.

기존 개발 워크플로우에 자연스럽게 녹아들기 때문에 별도의 학습 비용이 거의 없습니다. main 브랜치에 머지되면 자동 배포, develop 브랜치는 스테이징 환경에 배포하는 식으로 구성할 수 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 langgraph.json 파일을 빠뜨리는 것입니다.

이 파일이 없으면 LangSmith가 프로젝트를 인식하지 못해 배포가 실패합니다. 또한 .env 파일에 담긴 API 키를 그대로 커밋하는 실수도 조심해야 합니다.

반드시 .env.example만 올리고, 실제 키는 LangSmith 콘솔에서 설정해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

박시니어 씨의 조언대로 GitHub 저장소를 만들고 코드를 푸시했습니다. langgraph.json 파일도 꼼꼼히 작성했습니다.

이제 다음 단계인 LangSmith 설정으로 넘어갈 준비가 되었습니다.

실전 팁

💡 - langgraph.json 파일은 저장소 루트에 반드시 위치해야 합니다

• 민감한 정보는 절대 GitHub에 올리지 말고 LangSmith 환경변수로 설정하세요
• pyproject.toml에 모든 의존성을 명시해야 배포 시 오류가 없습니다

---

2. LangSmith Deployments 설정

GitHub 저장소 준비를 마친 김개발 씨는 이제 LangSmith 웹사이트에 접속했습니다. 화면 왼쪽에 보이는 "Deployments" 메뉴가 눈에 들어옵니다.

"여기서 뭘 어떻게 하면 되는 거지?"

고객 문의 자동 응답 에이전트 # 2. GitHub 저장소 연결 Repository: github.com/mycompany/my-agent Branch: main # 3.

환경변수 설정 (Secrets) OPENAI_API_KEY: sk-xxxx... LANGCHAIN_API_KEY: lsv2_xxxx...

4. 리소스 설정 Instance Type: Standard (권장) Auto-scaling: Enabled Min Instances: 1 Max Instances: 5

다음 코드를 살펴봅시다.

# LangSmith 콘솔에서 설정할 항목들

# 1. New Deployment 클릭 후 설정
Name: my-customer-agent

김개발 씨는 LangSmith 웹사이트에 로그인했습니다. 왼쪽 메뉴에서 Deployments를 클릭하니 깔끔한 대시보드가 나타납니다.

오른쪽 상단의 파란색 "New Deployment" 버튼이 보입니다. 박시니어 씨가 옆에서 지켜보며 말합니다.

"어렵지 않아. 그냥 순서대로 따라가면 돼." 그렇다면 Deployments 설정이란 정확히 무엇일까요?

쉽게 비유하자면, 이것은 마치 새 아파트에 입주하는 과정과 같습니다. GitHub 저장소가 이사할 짐이라면, Deployments 설정은 전기, 수도, 가스를 연결하고 가구를 배치하는 작업입니다.

집은 있지만 이런 설정 없이는 살 수가 없겠죠. Deployments 설정의 첫 단계는 기본 정보 입력입니다.

Name 필드에는 배포의 이름을 적습니다. 이 이름은 나중에 API URL의 일부가 되므로 의미 있는 이름을 사용하는 것이 좋습니다.

my-customer-agent처럼 프로젝트의 성격을 나타내는 이름이 적합합니다. 다음은 GitHub 저장소 연결입니다.

Repository 드롭다운에서 앞서 준비한 저장소를 선택합니다. Branch는 어떤 브랜치의 코드를 배포할지 결정합니다.

보통 main 브랜치를 프로덕션용으로, develop 브랜치를 개발 테스트용으로 설정합니다. 가장 중요한 부분은 환경변수 설정입니다.

Secrets 섹션에서 API 키들을 등록합니다. OpenAI API 키, LangChain API 키 등 여러분의 에이전트가 필요로 하는 모든 민감한 정보를 여기에 입력합니다.

이 값들은 암호화되어 저장되므로 안전합니다. GitHub에 직접 올리는 것보다 훨씬 보안에 좋습니다.

마지막으로 리소스 설정을 확인합니다. Instance Type은 배포할 서버의 성능을 결정합니다.

Standard로 시작해서 트래픽에 따라 조정하면 됩니다. Auto-scaling을 활성화하면 사용량에 따라 자동으로 서버 수가 조절됩니다.

갑자기 트래픽이 몰려도 걱정할 필요가 없습니다. 실제 현업에서는 어떻게 활용할까요?

스타트업에서는 보통 Min Instances를 1로 설정하여 비용을 절약합니다. 대기업이나 트래픽이 많은 서비스에서는 Min Instances를 높게 설정하여 응답 속도를 보장합니다.

상황에 맞게 유연하게 조절하면 됩니다. 하지만 주의할 점도 있습니다.

환경변수를 빠뜨리면 배포는 성공해도 에이전트가 제대로 동작하지 않습니다. 로컬에서 사용하던 모든 환경변수를 빠짐없이 등록했는지 확인하세요.

또한 API 키가 만료되었거나 잘못된 경우에도 에러가 발생하므로 유효한 키인지 미리 확인하는 것이 좋습니다. 김개발 씨는 모든 설정을 마치고 "Deploy" 버튼을 클릭했습니다.

화면에 진행 상태가 표시되기 시작합니다. 빌드, 테스트, 배포 단계가 차례로 진행됩니다.

몇 분 후, 초록색 체크 표시와 함께 "Deployment successful" 메시지가 나타났습니다.

실전 팁

💡 - 환경변수 이름은 로컬 .env 파일과 정확히 일치해야 합니다

• 처음에는 Auto-scaling을 비활성화하고 테스트한 후 활성화하세요
• 배포 실패 시 Logs 탭에서 원인을 확인할 수 있습니다

---

3. 배포 완료 및 Studio 테스트

드디어 배포가 완료되었습니다. 김개발 씨의 얼굴에 환한 미소가 번집니다.

그런데 박시니어 씨가 한마디 덧붙입니다. "배포 끝났다고 바로 연동하면 안 돼.

Studio에서 먼저 테스트해봐야지."

LangGraph Studio는 배포된 에이전트를 시각적으로 테스트할 수 있는 인터페이스입니다. 마치 자동차를 출고하기 전에 테스트 드라이브를 하는 것과 같습니다.

실제 API를 연동하기 전에 에이전트가 의도한 대로 동작하는지 확인할 수 있어서, 버그를 미리 잡을 수 있습니다.

다음 코드를 살펴봅시다.

# Studio에서 테스트할 때 입력하는 메시지 예시

# 테스트 케이스 1: 기본 인사
{
    "messages": [
        {"role": "user", "content": "안녕하세요"}
    ]
}

# 테스트 케이스 2: 실제 문의 시뮬레이션
{
    "messages": [
        {"role": "user", "content": "주문한 상품이 아직 안 왔어요"}
    ]
}

# 테스트 케이스 3: 멀티턴 대화
{
    "messages": [
        {"role": "user", "content": "반품하고 싶어요"},
        {"role": "assistant", "content": "어떤 상품을 반품하시겠어요?"},
        {"role": "user", "content": "지난주에 산 티셔츠요"}
    ]
}

김개발 씨는 배포 완료 화면을 보며 뿌듯해하고 있었습니다. 그런데 박시니어 씨의 말에 정신이 번쩍 들었습니다.

맞습니다. 배포가 성공했다고 해서 에이전트가 제대로 동작한다는 보장은 없습니다.

박시니어 씨가 화면을 가리킵니다. "저기 Studio 버튼 보이지?

눌러봐." 그렇다면 LangGraph Studio란 정확히 무엇일까요? 쉽게 비유하자면, Studio는 마치 비행 시뮬레이터와 같습니다.

실제 비행기를 조종하기 전에 시뮬레이터에서 연습하듯이, 실제 사용자에게 서비스하기 전에 에이전트의 동작을 미리 확인하는 것입니다. 문제가 생겨도 시뮬레이터에서는 아무도 다치지 않겠죠.

Studio 화면에는 여러 가지 유용한 기능이 있습니다. 왼쪽에는 그래프 시각화가 표시됩니다.

에이전트의 노드와 엣지가 다이어그램으로 보여서 현재 어떤 상태에 있는지 한눈에 파악할 수 있습니다. 오른쪽에는 채팅 인터페이스가 있어서 실제 사용자처럼 메시지를 입력하고 응답을 받아볼 수 있습니다.

가장 강력한 기능은 실행 추적입니다. 메시지를 보내면 에이전트가 어떤 단계를 거쳐 응답을 생성했는지 상세하게 볼 수 있습니다.

어떤 도구를 호출했는지, LLM에 어떤 프롬프트가 전달되었는지, 각 단계에서 얼마나 시간이 걸렸는지 모두 확인 가능합니다. 버그가 발생했을 때 원인을 찾기가 훨씬 수월해집니다.

테스트할 때는 다양한 시나리오를 준비해야 합니다. 위의 코드처럼 기본적인 인사부터 시작해서, 실제 사용자가 할 법한 질문들을 테스트합니다.

특히 멀티턴 대화는 반드시 테스트해야 합니다. 한 번의 질문에는 잘 답하더라도, 대화가 이어지면 문맥을 잃어버리는 경우가 종종 있기 때문입니다.

실제 현업에서는 어떻게 활용할까요? QA 담당자가 Studio를 통해 테스트 케이스를 실행하고 결과를 문서화합니다.

개발자는 버그 리포트를 받으면 Studio에서 해당 상황을 재현하여 디버깅합니다. 또한 새로운 기능을 추가할 때마다 회귀 테스트를 수행하여 기존 기능이 깨지지 않았는지 확인합니다.

하지만 주의할 점도 있습니다. Studio 테스트만으로는 부족합니다.

실제 트래픽 환경에서의 성능, 동시 접속자가 많을 때의 동작 등은 별도로 테스트해야 합니다. 또한 Studio에서는 잘 동작하더라도 클라이언트 코드와 연동할 때 문제가 생길 수 있으므로 통합 테스트도 필수입니다.

김개발 씨는 Studio에서 여러 테스트 케이스를 실행해봤습니다. 다행히 모든 시나리오에서 에이전트가 잘 동작합니다.

특히 그래프 시각화를 보니 에이전트의 동작 흐름이 한눈에 들어와서 이해하기가 훨씬 쉬웠습니다. 이제 API를 연동할 준비가 되었습니다.

실전 팁

💡 - 엣지 케이스(빈 입력, 매우 긴 입력, 특수문자 등)를 반드시 테스트하세요

• 실행 추적에서 각 단계의 소요 시간을 확인하여 병목 구간을 파악하세요
• 테스트 결과를 스크린샷으로 저장해두면 나중에 비교할 때 유용합니다

---

4. API URL 획득

Studio 테스트를 마친 김개발 씨는 이제 실제 서비스에 에이전트를 연결하려고 합니다. 박시니어 씨가 물었습니다.

"API URL은 어디서 찾았어?" 김개발 씨는 잠시 멈칫했습니다. "API URL이요?"

API URL은 배포된 에이전트에 접근하기 위한 고유한 웹 주소입니다. 마치 전화번호처럼, 이 URL을 알아야 다른 서비스에서 에이전트를 호출할 수 있습니다.

LangSmith는 배포가 완료되면 자동으로 URL을 생성해주며, 이를 통해 어디서든 에이전트와 통신할 수 있습니다.

다음 코드를 살펴봅시다.

# API URL 형식
https://api.smith.langchain.com/v1/deployments/{deployment_id}

# 실제 예시
DEPLOYMENT_URL = "https://api.smith.langchain.com/v1/deployments/abc123xyz"

# API 키와 함께 사용
import os

# 환경변수 설정
os.environ["LANGSMITH_API_KEY"] = "lsv2_pt_xxxx..."
os.environ["DEPLOYMENT_URL"] = "https://api.smith.langchain.com/v1/deployments/abc123xyz"

# curl로 테스트
# curl -X POST {DEPLOYMENT_URL}/runs \
#   -H "Authorization: Bearer {LANGSMITH_API_KEY}" \
#   -H "Content-Type: application/json" \
#   -d '{"input": {"messages": [{"role": "user", "content": "hello"}]}}'

김개발 씨는 당황했습니다. 배포는 성공했는데, 정작 어떻게 연결해야 하는지 모르겠습니다.

박시니어 씨가 화면을 가리키며 설명을 시작합니다. "배포 상세 페이지 들어가봐.

거기 API Endpoint라고 있어." 그렇다면 API URL이란 정확히 무엇일까요? 쉽게 비유하자면, API URL은 마치 식당의 주소와 같습니다.

아무리 맛있는 음식을 만들어도 주소를 모르면 찾아갈 수 없겠죠. 여러분의 에이전트가 아무리 훌륭해도 URL을 모르면 다른 서비스에서 사용할 수가 없습니다.

이 주소를 알아야 주문도 하고 음식도 받을 수 있는 것입니다. API URL을 찾는 방법은 간단합니다.

LangSmith 대시보드에서 Deployments 메뉴로 들어갑니다. 배포 목록에서 해당 배포를 클릭하면 상세 페이지가 나타납니다.

여기서 API Endpoint 또는 Deployment URL이라고 적힌 부분을 찾으면 됩니다. 복사 버튼을 클릭하면 클립보드에 URL이 복사됩니다.

URL의 구조를 이해하면 도움이 됩니다. 기본 형식은 https://api.smith.langchain.com/v1/deployments/{deployment_id}입니다.

deployment_id는 각 배포마다 고유하게 부여되는 식별자입니다. 이 URL 뒤에 /runs, /threads 등의 경로를 붙여서 다양한 기능을 사용할 수 있습니다.

API URL과 함께 API 키도 필요합니다. URL만 알아서는 에이전트를 호출할 수 없습니다.

LangSmith API 키를 함께 전달해야 인증이 완료됩니다. 이 키는 LangSmith 설정 페이지에서 생성할 수 있습니다.

보안을 위해 키는 환경변수로 관리하고, 절대로 코드에 직접 작성하지 마세요. 실제 현업에서는 어떻게 활용할까요?

백엔드 서버에서 환경변수로 URL과 API 키를 관리합니다. 개발 환경과 프로덕션 환경에서 다른 URL을 사용하도록 설정 파일을 분리합니다.

CI/CD 파이프라인에서 자동으로 환경변수를 주입하여 배포 과정을 자동화합니다. 하지만 주의할 점도 있습니다.

API 키가 노출되면 누구나 여러분의 에이전트를 호출할 수 있습니다. 그러면 비용이 발생하고 보안 사고로 이어질 수 있습니다.

키는 반드시 안전하게 관리하고, 의심스러운 활동이 감지되면 즉시 키를 재발급받으세요. 또한 rate limiting을 설정하여 과도한 호출을 방지하는 것도 좋습니다.

김개발 씨는 대시보드에서 API URL을 찾아 복사했습니다. 환경변수 파일에 URL과 API 키를 안전하게 저장했습니다.

이제 실제 코드에서 에이전트를 호출할 준비가 되었습니다.

실전 팁

💡 - API 키는 절대로 Git에 커밋하지 마세요

• 개발/스테이징/프로덕션 환경별로 다른 배포를 사용하세요
• API 호출 로그를 모니터링하여 비정상적인 트래픽을 감지하세요

---

5. langgraph sdk 클라이언트

API URL을 손에 넣은 김개발 씨는 이제 실제 코드를 작성하려고 합니다. 그런데 박시니어 씨가 또 한마디 합니다.

"직접 HTTP 요청 보내려고? langgraph-sdk 쓰면 훨씬 편한데."

langgraph-sdk는 배포된 LangGraph 에이전트와 통신하기 위한 공식 Python 클라이언트 라이브러리입니다. 마치 리모컨처럼, 복잡한 내부 동작을 몰라도 버튼 하나로 원하는 기능을 실행할 수 있습니다.

HTTP 요청을 직접 작성하는 것보다 훨씬 간편하고 오류 가능성도 줄어듭니다.

다음 코드를 살펴봅시다.

from langgraph_sdk import get_client

# 클라이언트 생성
client = get_client(
    url="https://api.smith.langchain.com/v1/deployments/abc123xyz"
)

# 동기 방식으로 에이전트 호출
async def chat_with_agent(user_message: str):
    # 새로운 스레드 생성 (대화 세션)
    thread = await client.threads.create()

    # 메시지 전송 및 응답 대기
    response = await client.runs.create(
        thread_id=thread["thread_id"],
        assistant_id="agent",
        input={"messages": [{"role": "user", "content": user_message}]}
    )

    return response

# 스트리밍 방식으로 에이전트 호출
async def stream_chat(user_message: str, thread_id: str):
    async for chunk in client.runs.stream(
        thread_id=thread_id,
        assistant_id="agent",
        input={"messages": [{"role": "user", "content": user_message}]}
    ):
        print(chunk, end="", flush=True)

김개발 씨는 처음에 requests 라이브러리로 직접 HTTP 요청을 보내려고 했습니다. 헤더 설정하고, JSON 파싱하고, 에러 처리하고...

생각보다 복잡합니다. 박시니어 씨의 조언이 떠올랐습니다.

"SDK를 쓰면 이런 복잡한 건 다 알아서 해줘." 그렇다면 langgraph-sdk란 정확히 무엇일까요? 쉽게 비유하자면, SDK는 마치 통역사와 같습니다.

여러분이 한국어로 말하면 통역사가 알아서 영어로 바꿔서 전달하고, 영어로 온 답변도 한국어로 바꿔서 알려줍니다. SDK도 마찬가지입니다.

Python 코드로 작성하면 알아서 HTTP 요청으로 변환하고, 응답도 Python 객체로 변환해줍니다. SDK 설치는 pip 한 줄이면 됩니다.

터미널에서 pip install langgraph-sdk를 실행하면 설치가 완료됩니다. 이후 from langgraph_sdk import get_client로 임포트하면 바로 사용할 수 있습니다.

환경변수에 LANGSMITH_API_KEY가 설정되어 있으면 자동으로 인증됩니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 get_client 함수로 클라이언트를 생성합니다. url 파라미터에 앞서 획득한 API URL을 전달합니다.

이 클라이언트 객체를 통해 모든 통신이 이루어집니다. threads.create()는 새로운 대화 세션을 만듭니다.

runs.create()는 실제로 에이전트를 호출하고 응답을 받습니다. 스트리밍은 특히 유용한 기능입니다.

긴 응답을 기다리지 않고 생성되는 대로 바로 받아볼 수 있습니다. ChatGPT처럼 글자가 하나씩 나타나는 효과를 구현할 때 필수적입니다.

runs.stream()을 사용하면 async for 루프로 청크 단위로 응답을 받을 수 있습니다. 실제 현업에서는 어떻게 활용할까요?

웹 애플리케이션의 백엔드에서 SDK를 사용하여 에이전트를 호출합니다. FastAPI나 Django 같은 프레임워크와 쉽게 통합할 수 있습니다.

스트리밍을 활용하면 사용자 경험이 크게 향상됩니다. 응답이 완성될 때까지 빈 화면을 보여주는 것보다 실시간으로 글자가 나타나는 것이 훨씬 자연스럽기 때문입니다.

하지만 주의할 점도 있습니다. SDK는 비동기 함수(async/await)를 사용합니다.

동기 코드와 혼합할 때는 주의가 필요합니다. asyncio.run()으로 감싸거나, 비동기를 지원하는 웹 프레임워크를 사용해야 합니다.

또한 네트워크 오류에 대한 예외 처리를 반드시 추가해야 합니다. 서버가 일시적으로 응답하지 않을 수 있기 때문입니다.

김개발 씨는 SDK를 사용해보니 코드가 훨씬 깔끔해졌습니다. 복잡한 HTTP 헤더나 JSON 직렬화를 신경 쓰지 않아도 됩니다.

몇 줄의 코드로 에이전트와 대화할 수 있게 되었습니다.

실전 팁

💡 - 비동기 함수는 await 키워드와 함께 호출해야 합니다

• 스트리밍을 사용하면 사용자 경험이 크게 향상됩니다
• 네트워크 오류에 대비해 try-except로 예외 처리를 추가하세요

---

6. 상태 유지 에이전트 호스팅

기본적인 API 호출은 성공했습니다. 그런데 김개발 씨가 테스트 중 이상한 점을 발견했습니다.

"어? 아까 했던 대화 내용을 기억 못 하네?" 박시니어 씨가 고개를 끄덕입니다.

"thread를 제대로 관리해야 상태가 유지돼."

상태 유지 에이전트는 대화의 맥락을 기억하는 에이전트입니다. 마치 단골 손님을 알아보는 카페 직원처럼, 이전 대화 내용을 바탕으로 더 자연스러운 응답을 제공합니다.

LangGraph SDK의 thread 기능을 활용하면 여러 번의 호출에 걸쳐 상태를 유지할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph_sdk import get_client

client = get_client(url="https://api.smith.langchain.com/v1/deployments/abc123xyz")

class ConversationManager:
    def __init__(self):
        self.threads = {}  # 사용자별 스레드 관리

    async def get_or_create_thread(self, user_id: str) -> str:
        # 기존 스레드가 있으면 재사용
        if user_id in self.threads:
            return self.threads[user_id]

        # 새 스레드 생성
        thread = await client.threads.create()
        self.threads[user_id] = thread["thread_id"]
        return thread["thread_id"]

    async def chat(self, user_id: str, message: str):
        thread_id = await self.get_or_create_thread(user_id)

        # 같은 스레드로 계속 대화하면 상태 유지됨
        response = await client.runs.create(
            thread_id=thread_id,
            assistant_id="agent",
            input={"messages": [{"role": "user", "content": message}]}
        )
        return response

김개발 씨는 테스트를 하다가 문제를 발견했습니다. "제 이름은 김개발입니다"라고 말한 후 "제 이름이 뭐였죠?"라고 물으니 에이전트가 모른다고 답합니다.

분명 방금 말했는데 왜 기억을 못 할까요? 박시니어 씨가 코드를 보더니 문제점을 짚어줍니다.

"매번 새 스레드를 만들고 있네. 그러니까 기억을 못 하지." 그렇다면 상태 유지란 정확히 무엇일까요?

쉽게 비유하자면, 스레드는 마치 대화 노트와 같습니다. 같은 노트에 계속 적으면 이전 대화 내용을 볼 수 있지만, 매번 새 노트를 꺼내면 이전에 뭘 얘기했는지 알 수 없겠죠.

LangGraph의 thread가 바로 이 대화 노트 역할을 합니다. thread의 핵심은 thread_id를 재사용하는 것입니다.

처음 대화를 시작할 때 threads.create()로 새 스레드를 만들면 고유한 thread_id가 부여됩니다. 이후 같은 대화를 이어가려면 이 thread_id를 저장해두었다가 다음 호출에서 재사용해야 합니다.

그래야 에이전트가 이전 대화 내용을 참고할 수 있습니다. 위의 코드에서 ConversationManager 클래스를 살펴보겠습니다.

이 클래스는 사용자별로 thread_id를 관리합니다. threads 딕셔너리에 user_id를 키로, thread_id를 값으로 저장합니다.

get_or_create_thread 메서드는 기존 스레드가 있으면 재사용하고, 없으면 새로 생성합니다. 이렇게 하면 같은 사용자와의 대화는 항상 같은 스레드에서 이루어집니다.

스레드 만료도 고려해야 합니다. LangSmith의 스레드는 일정 기간이 지나면 만료될 수 있습니다.

만료된 스레드로 요청을 보내면 에러가 발생합니다. 따라서 스레드가 유효한지 확인하고, 만료되었다면 새 스레드를 생성하는 로직이 필요합니다.

실제 현업에서는 어떻게 활용할까요? 채팅 서비스에서 각 채팅방마다 별도의 스레드를 생성합니다.

고객 지원 시스템에서는 고객별로 스레드를 관리하여 이전 문의 내역을 참고한 응답을 제공합니다. 스레드 ID는 데이터베이스에 저장하여 서버가 재시작되어도 대화 연속성을 유지합니다.

하지만 주의할 점도 있습니다. 스레드가 너무 길어지면 성능에 영향을 줄 수 있습니다.

대화가 수백 턴 이상 이어지면 메모리 사용량이 증가하고 응답 시간도 느려집니다. 적절한 시점에 새 스레드를 시작하거나, 요약 기능을 활용하여 컨텍스트를 압축하는 것이 좋습니다.

김개발 씨는 ConversationManager를 구현하고 다시 테스트해봤습니다. 이번에는 이전 대화 내용을 완벽하게 기억합니다.

"제 이름이 뭐였죠?"라고 물으니 "김개발 님이시죠"라고 정확하게 답합니다. 드디어 진정한 대화형 에이전트가 완성되었습니다.

실전 팁

💡 - 프로덕션에서는 thread_id를 데이터베이스에 영구 저장하세요

• 스레드 만료 에러에 대비해 재생성 로직을 추가하세요
• 대화가 너무 길어지면 새 스레드로 전환하는 것을 고려하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!