LangChain v0.3 총정리: 에이전트 메모리·도구 시스템이 완전히 바뀌었습니다 (2025년 현재)

LangChain v0.3가 에이전트 개발의 판도를 바꾸고 있습니다. 2024년 9월 첫 릴리스 이후 지금까지 v0.3.26에 이르기까지, 메모리 시스템 전면 교체, 도구 정의 간소화, Pydantic v2 마이그레이션까지—LLM 에이전트를 만드는 방식 자체가 달라졌습니다. 특히 기존의 ConversationBufferMemory를 버리고 LangGraph 체크포인터 기반으로 전환한 것은 실무에서 체감이 큰 변화입니다.

LangChain v0.3, 무엇이 달라졌나

2024년 9월에 공식 발표된 LangChain v0.3는 단순한 버전 업이 아니었습니다. 프레임워크의 근본적인 구조가 변경되었고, 2025년 7월 현재 안정화 단계에 접어들었습니다. 핵심 변경사항을 정리합니다.

Pydantic v2 마이그레이션 완료

가장 큰 기반 변화는 Pydantic v1에서 v2로의 전환입니다. LangChain의 모든 내부 스키마, 도구 정의, 출력 파서가 Pydantic v2 기반으로 재작성되었습니다. 성능 향상(최대 50배 빠른 유효성 검사)은 물론, Python 생태계 전반의 Pydantic v2 채택 흐름에 맞춘 결정입니다.

# v0.2 (Pydantic v1 스타일)
from langchain.pydantic_v1 import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색어")

# v0.3 (Pydantic v2 네이티브)
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색어")

기존 langchain.pydantic_v1 임포트를 사용하던 코드는 마이그레이션이 필요합니다. Python 3.8 지원도 공식 중단되었으므로, 3.9 이상 환경을 권장합니다.

통합 패키지 재편: langchain-{name} 구조

v0.3에서는 LLM 프로바이더별 통합이 langchain-openai, langchain-anthropic, langchain-google-genai 등 독립 패키지로 완전히 분리되었습니다. 이전처럼 거대한 langchain 패키지 하나에 모든 것이 들어있던 구조에서 벗어나, 필요한 프로바이더만 설치하는 모듈러 방식으로 전환되었습니다.

# 필요한 것만 설치
pip install langchain-core langchain-openai langchain-community

# 범용 채팅 모델 생성자
from langchain.chat_models import init_chat_model

# 모델명만으로 자동 프로바이더 감지
model = init_chat_model("gpt-4o", temperature=0)
model = init_chat_model("claude-sonnet-4-20250514", temperature=0)

init_chat_model은 v0.3에서 추가된 범용 생성자로, 모델명만으로 적절한 프로바이더를 자동 감지합니다. 멀티 프로바이더 환경에서 코드 중복을 크게 줄여줍니다.

레거시 메모리의 종말: LangGraph 체크포인터로의 전환

LangChain v0.3에서 가장 실무에 영향이 큰 변화는 메모리 시스템의 전면 교체입니다. 기존의 ConversationBufferMemory, ConversationSummaryMemory, ConversationTokenBufferMemory 등 레거시 메모리 클래스가 모두 deprecated 되었습니다.

대신 LangGraph의 체크포인터 시스템이 공식 메모리 솔루션으로 자리잡았습니다. 단순히 API가 바뀐 것이 아니라, 에이전트의 상태 관리 철학 자체가 달라진 것입니다.

단기 메모리: 스레드 기반 체크포인팅

LangGraph에서 단기 메모리는 스레드(thread) 단위로 관리됩니다. 각 대화 스레드는 고유한 체크포인터를 가지며, 매 노드 실행 후 자동으로 상태가 저장됩니다.

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

# 체크포인터 설정
checkpointer = InMemorySaver()

# 에이전트 생성 시 체크포인터 연결
agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[search_tool, calculator_tool],
    checkpointer=checkpointer
)

# 스레드별 대화 유지
config = {"configurable": {"thread_id": "user-session-001"}}
response = agent.invoke(
    {"messages": [{"role": "user", "content": "서울 날씨 알려줘"}]},
    config=config
)

# 같은 thread_id로 호출하면 이전 대화 기억
response = agent.invoke(
    {"messages": [{"role": "user", "content": "내일은?"}]},
    config=config  # 이전 대화 컨텍스트 자동 로드
)

프로덕션 환경에서는 InMemorySaver 대신 SqliteSaver나 PostgresSaver를 사용하여 영속적인 체크포인팅을 구현할 수 있습니다. 서버 재시작 후에도 대화 상태가 유지되며, 타임트래블 디버깅(특정 시점으로 되돌리기)까지 가능합니다.

LangMem SDK: AI 에이전트 장기 메모리의 새로운 표준

2025년 2월, LangChain 팀은 LangMem SDK를 공개했습니다. 에이전트의 장기 메모리를 세 가지 유형으로 체계화한 라이브러리입니다.

• 시맨틱 메모리(Semantic Memory): 사용자에 대한 사실, 선호도, 지식을 구조화하여 저장합니다. “김 과장은 Python보다 TypeScript를 선호한다” 같은 정보입니다.
• 에피소딕 메모리(Episodic Memory): 과거 상호작용의 핵심을 요약하여 보존합니다. few-shot 예시나 맥락 참조에 활용됩니다.
• 절차적 메모리(Procedural Memory): 에이전트의 시스템 프롬프트와 행동 패턴을 학습과 함께 최적화합니다. 에이전트가 사용할수록 응답 품질이 향상되는 구조입니다.

# LangMem 설치 및 기본 사용
pip install langmem

from langmem import Client

client = Client()

# 시맨틱 메모리: 사용자 정보 저장
client.add_memories(
    messages=[
        {"role": "user", "content": "나는 FastAPI로 주로 개발해요"},
        {"role": "assistant", "content": "FastAPI 프로젝트에 맞춰 도와드릴게요"}
    ],
    user_id="dev-kim"
)

# 저장된 메모리 검색 (시맨틱 서치)
memories = client.search_memories(
    query="이 사용자의 기술 스택은?",
    user_id="dev-kim"
)

특히 2024년 12월에 추가된 시맨틱 검색 기능은 게임 체인저입니다. 정확한 키워드 매칭이 아닌 의미 기반으로 관련 메모리를 찾아주므로, “이 사용자가 좋아하는 프레임워크”라는 쿼리로 “FastAPI를 주로 사용한다”는 메모리를 검색할 수 있습니다. PostgresStore와 InMemoryStore에서 모두 지원됩니다.

도구 정의의 간소화: @tool 데코레이터 개선

LangChain v0.3에서는 에이전트가 사용하는 도구(Tool) 정의가 훨씬 직관적으로 바뀌었습니다. Pydantic v2와의 통합 덕분에 타입 힌트만으로 스키마가 자동 생성됩니다.

from langchain_core.tools import tool
from typing import Annotated

@tool
def get_stock_price(
    ticker: Annotated[str, "주식 티커 심볼 (예: AAPL)"],
    currency: Annotated[str, "통화 단위"] = "USD"
) -> dict:
    """실시간 주가를 조회합니다."""
    # 구현부
    return {"ticker": ticker, "price": 150.25, "currency": currency}

# 도구 스키마 자동 생성 확인
print(get_stock_price.args_schema.model_json_schema())
# {"properties": {"ticker": {"description": "주식 티커 심볼 (예: AAPL)", "type": "string"}, ...}}

또한 채팅 모델 유틸리티가 대폭 강화되었습니다. trim_messages로 토큰 제한에 맞춰 메시지를 자르고, filter_messages로 특정 타입만 추출하며, merge_message_runs로 연속된 같은 역할의 메시지를 합칠 수 있습니다. 레이트 리미터도 내장되어 API 호출 제한을 체계적으로 관리할 수 있게 되었습니다.

from langchain_core.messages import trim_messages, filter_messages

# 토큰 제한에 맞춰 메시지 자르기
trimmed = trim_messages(
    messages,
    max_tokens=4096,
    token_counter=ChatOpenAI(model="gpt-4o"),
    strategy="last"  # 최신 메시지 우선 보존
)

# 시스템 메시지 + 사용자 메시지만 필터링
filtered = filter_messages(
    messages,
    include_types=["system", "human"]
)

LangGraph: 에이전트 런타임의 핵심이 되다

LangChain v0.3 시대에 가장 주목할 트렌드는 LangGraph의 부상입니다. 단순한 체인(Chain) 실행을 넘어, 복잡한 에이전트 워크플로우를 그래프 구조로 설계하는 것이 표준이 되고 있습니다.

LangGraph는 에이전트의 상태 관리, 체크포인팅, Human-in-the-Loop, 병렬 실행을 모두 그래프 노드와 엣지로 표현합니다. v0.3의 메모리 시스템이 LangGraph 위에 구축된 것도 이런 방향성의 연장선입니다.

from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode

# 상태 그래프 정의
workflow = StateGraph(MessagesState)

# 노드 추가
workflow.add_node("agent", call_model)
workflow.add_node("tools", ToolNode(tools=[search, calculator]))

# 엣지 정의 (조건부 라우팅)
workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_use_tool,  # 도구 사용 여부 판단 함수
    {"continue": "tools", "end": END}
)
workflow.add_edge("tools", "agent")

# 컴파일 및 실행
app = workflow.compile(checkpointer=checkpointer)

현재 LangChain 커뮤니티에서는 v1.0 알파 버전에 대한 기대감이 높아지고 있습니다. create_agent 추상화, 미들웨어 시스템(HITL, 요약, PII 마스킹), 구조화된 출력의 메인 루프 통합 등이 예고되어 있어, LangGraph 중심의 에이전트 개발 패러다임이 더욱 강화될 전망입니다.

마이그레이션 체크리스트: v0.2에서 v0.3으로

기존 LangChain v0.2 프로젝트를 v0.3으로 마이그레이션할 때 확인해야 할 핵심 항목입니다.

1. Python 버전 확인: 3.9 이상 필수 (3.8 지원 중단)
2. Pydantic v2 마이그레이션: langchain.pydantic_v1 → 네이티브 pydantic 임포트로 변경
3. 레거시 메모리 교체: ConversationBufferMemory 등 → LangGraph 체크포인터
4. 통합 패키지 설치: langchain-openai, langchain-anthropic 등 개별 설치
5. deprecated API 정리: langchain_core.pydantic_v1, langchain_core.tools.BaseTool.run 등 제거 예정 코드 확인

마이그레이션 도중 가장 흔한 문제는 Pydantic v1/v2 혼용입니다. 의존하는 라이브러리 중 아직 v1에 의존하는 것이 있다면 pydantic.v1 호환 모드를 활용할 수 있지만, 장기적으로는 모든 의존성을 v2로 통일하는 것을 권장합니다.

정리: LangChain v0.3 시대, 무엇을 준비해야 하나

LangChain v0.3는 “체인의 시대”에서 “에이전트의 시대”로 전환하는 분기점입니다. 핵심 메시지는 세 가지입니다.

• LangGraph가 표준 런타임: 단순 체인 대신 상태 그래프 기반의 에이전트 설계가 기본값이 되었습니다.
• 메모리 시스템 통합: 단기(체크포인터) + 장기(LangMem) 메모리가 체계적으로 분리·통합되었습니다.
• 모듈러 아키텍처: 필요한 것만 설치하고, Pydantic v2 기반의 일관된 타입 시스템을 사용합니다.

v1.0이 다가오고 있는 지금, LangGraph와 LangMem SDK에 익숙해지는 것이 LLM 에이전트 개발의 경쟁력을 좌우할 것입니다. 지금 시작하기에 가장 좋은 시점입니다.

---

---