LangChain v1으로의 전환: 무엇이 바뀌었고, 어떻게 대응해야 할까?

LangChain은 LLM 애플리케이션 개발을 위한 대표적인 프레임워크로, 최근 v1 업데이트를 통해 구조적 변화를 맞이했습니다. 이번 버전에서는 패키지 네임스페이스가 대폭 간소화되고, create_agent 중심의 새로운 에이전트 구조가 도입되었으며, 기존 체인 기능은 langchain-classic으로 분리되었습니다.
이 글에서는 LangChain v1의 주요 변경사항, 코드 마이그레이션 방법, 그리고 새 구조의 특징과 장점을 정리합니다.

반응형

---

LangChain v1 개요 – 업데이트의 핵심 목적

LangChain v1의 가장 큰 변화는 “단순화(Simplification)”입니다.
그동안 langchain 패키지는 에이전트, 체인, 리트리버, 임베딩 등 다양한 기능이 혼재되어 있었지만, 이제는 핵심 빌딩 블록(agents, messages, tools, embeddings) 중심으로 정리되었습니다.

이제 LangChain은 에이전트 중심 구조로 통합되어, 사용자는 불필요한 모듈 혼잡 없이 핵심 로직에 집중할 수 있습니다.

---

핵심 변경 요약

1. 패키지 네임스페이스 간소화

기존의 복잡한 모듈 구조가 단순화되어 주요 기능들이 다음과 같이 정리되었습니다.

모듈	주요 기능	비고
langchain.agents	create_agent, AgentState	에이전트 생성의 중심
langchain.messages	메시지 타입, trim_messages	langchain-core에서 재출시
langchain.tools	@tool, BaseTool	핵심 툴 구성 요소
langchain.chat_models	init_chat_model, BaseChatModel	통합된 모델 초기화
langchain.embeddings	init_embeddings	임베딩 모델 관리

2. langchain-classic 분리

이전 버전의 체인(LLMChain, ConversationChain 등)이나 리트리버, 허브 모듈은 langchain-classic 패키지로 이동했습니다.
기존 코드를 계속 사용하려면 아래와 같이 설치 후 import 경로를 변경해야 합니다.

pip install langchain-classic

예시:

from langchain_classic.chains import LLMChain
from langchain_classic.retrievers import ...
from langchain_classic.indexes import ...
from langchain_classic import hub

---

create_agent로의 전환: 새로운 에이전트 구조

이전에는 langgraph.prebuilt.create_react_agent를 사용했지만, 이제는 다음과 같이 langchain.agents.create_agent를 사용해야 합니다.

from langgraph.prebuilt import create_react_agent 
from langchain.agents import create_agent 

주요 변경점

항목	변경 내용
Import 경로	langgraph.prebuilt → langchain.agents
함수명	create_react_agent → create_agent
프롬프트	prompt → system_prompt 로 변경
Hook	before_model, after_model 메서드를 갖는 middleware로 대체
Custom State	TypedDict 기반으로 변경

예시:

from langchain.agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[check_weather],
    system_prompt="You are a helpful assistant"
)

---

middleware의 도입: 더 유연해진 에이전트 설계

LangChain v1에서는 hook 방식이 middleware로 대체되었습니다.
이 방식은 모델 호출 전후에 여러 개의 미들웨어를 순차적으로 실행할 수 있게 하여, 확장성과 유지보수성을 높입니다.

1. Dynamic Prompt Middleware

대화 컨텍스트에 따라 시스템 프롬프트를 동적으로 변경할 수 있습니다.

from dataclasses import dataclass
from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest
from langgraph.runtime import Runtime

@dataclass
class Context:  
    user_role: str = "user"

@dynamic_prompt
def dynamic_prompt(request: ModelRequest) -> str:  
    user_role = request.runtime.context.user_role
    base_prompt = "You are a helpful assistant."

    if user_role == "expert":
        prompt = f"{base_prompt} Provide detailed technical responses."
    elif user_role == "beginner":
        prompt = f"{base_prompt} Explain concepts simply and avoid jargon."
    else:
        prompt = base_prompt

    return prompt  

agent = create_agent(
    model="openai:gpt-4o",
    tools=tools,
    middleware=[dynamic_prompt],  
    context_schema=Context
)

---

2. Pre-model & Post-model Middleware

before_model과 after_model 메서드를 통해 모델 실행 전후 작업을 수행합니다.
예를 들어, 대화 이력 요약이나 사람 검토(Human in the loop) 기능을 추가할 수 있습니다.

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware, HumanInTheLoopMiddleware

# 요약 미들웨어
agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=tools,
    middleware=[
        SummarizationMiddleware(  
            model="anthropic:claude-sonnet-4-5",  
            max_tokens_before_summary=1000
        )  
    ]  
)

# 사람 검토 미들웨어
agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[read_email, send_email],
    middleware=[HumanInTheLoopMiddleware(
        interrupt_on={
            "send_email": True,
            "description": "Please review this email before sending"
        },
    )]
)

---

Custom State: 상태 확장 방식의 변화

이제 모든 state는 TypedDict 형태를 기반으로 합니다.
state_schema 또는 middleware에서 상태를 정의할 수 있습니다.

from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent, AgentState  

class CustomState(AgentState):
    user_name: str

@tool
def greet(runtime: ToolRuntime[CustomState]) -> str:
    """Use this to greet the user by name."""
    user_name = runtime.state.get("user_name", "Unknown")  
    return f"Hello {user_name}!"

agent = create_agent(  
    model="anthropic:claude-sonnet-4-5",
    tools=[greet],
    state_schema=CustomState  
)

---

Dynamic Model 선택

v1에서는 미들웨어를 통해 런타임 상황에 따라 모델을 다르게 선택할 수 있습니다.

from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelRequestHandler
from langchain.messages import AIMessage
from langchain_openai import ChatOpenAI

basic_model = ChatOpenAI(model="gpt-5-nano")
advanced_model = ChatOpenAI(model="gpt-5")

class DynamicModelMiddleware(AgentMiddleware):
    def wrap_model_call(self, request: ModelRequest, handler: ModelRequestHandler) -> AIMessage:
        if len(request.state.messages) > self.messages_threshold:
            model = advanced_model
        else:
            model = basic_model
        return handler(request.replace(model=model))

    def __init__(self, messages_threshold: int) -> None:
        self.messages_threshold = messages_threshold

agent = create_agent(
    model=basic_model,
    tools=tools,
    middleware=[DynamicModelMiddleware(messages_threshold=10)]
)

---

기타 주요 변경사항

• Python 3.9 지원 종료: 이제 Python 3.10 이상이 필요합니다.
• .text() → .text 속성 변경: 메시지의 텍스트 접근 방식이 메서드에서 속성으로 바뀌었습니다.
• Structured Output 개선: 인공적인 툴 호출(ToolStrategy)이나 제공자 네이티브 출력(ProviderStrategy)을 활용합니다.
• content_blocks 도입: 멀티모달 콘텐츠를 표준화된 블록 형태로 관리합니다.

---

마이그레이션 가이드라인 요약

1. 패키지 구조 정리
   • langchain-classic을 설치하여 기존 체인 및 리트리버 기능을 유지
   • 새로운 기능은 langchain.agents 중심으로 재작성
2. 에이전트 전환
   • create_react_agent → create_agent로 교체
   • prompt 파라미터를 system_prompt로 수정
3. middleware 적용
   • before_model, after_model 로직을 middleware로 이관
   • 필요한 기능별로 별도 미들웨어 작성

---

728x90

LangChain v1이 의미하는 변화

LangChain v1은 단순한 업데이트가 아니라 구조적 혁신에 가깝습니다.
패키지가 간결해졌고, 에이전트 중심으로 통합되었으며, middleware를 통해 확장성과 유지보수성이 크게 향상되었습니다.

기존 사용자에게는 일부 import 수정과 코드 리팩토링이 필요하지만, 한 번 정리하고 나면 훨씬 명확하고 일관된 개발 환경을 경험할 수 있습니다.
지금이 바로 LangChain v1으로 전환할 최적의 시점입니다.

https://docs.langchain.com/oss/python/migrate/langchain-v1

LangChain v1 migration guide - Docs by LangChain