미들웨어 개요

미들웨어 개요 (Middleware Overview)

에이전트 내부에서 일어나는 일을 한 단계씩 더 세밀하게 제어하고 싶을 때 쓰는 게 미들웨어예요. "모든 단계에서 에이전트 실행을 제어하고 커스터마이즈한다"가 이 페이지의 한 줄 요약이죠. 모델 호출 전후에 무엇이 실행되고, 어떤 도구가 노출되고, 출력이 어떻게 포맷되는지를 미들웨어가 중간에서 조율합니다.

출처: LangChain 공식 문서 — middleware-overview

미들웨어는 어떤 때 유용한가요?

미들웨어는 이런 것들을 할 수 있게 해줍니다.

로깅, 분석, 디버깅으로 에이전트 동작을 추적하기
프롬프트, 도구 선택, 출력 포맷 변환하기
재시도(retries), 폴백(fallbacks), 조기 종료(early termination) 로직 추가하기
요율 제한(rate limits), 가드레일(guardrails), PII 감지 적용하기

미들웨어는 create_agent에 넘겨서 추가해요.

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

agent = create_agent(
    model="gpt-5.5",
    tools=[...],
    middleware=[
        SummarizationMiddleware(...),
        HumanInTheLoopMiddleware(...)
    ],
)

에이전트 루프 (The agent loop)

핵심 에이전트 루프는 모델을 호출하고, 모델이 실행할 도구를 고르게 하고, 더 이상 호출할 도구가 없으면 끝내는 것으로 이루어져요. 미들웨어는 이 각 단계 전후에 훅을 노출합니다.

LangGraph 워크플로 안에서 미들웨어 쓰기

미들웨어는 별도의 런타임이 아니에요. 훅은 create_agent가 반환하는 컴파일된 LangGraph 안에서 실행됩니다. 에이전트 전체(미들웨어까지 포함해서)를 더 큰 StateGraph의 노드나 서브그래프로 통째로 넣어도 되고, 모든 미들웨어 훅은 계속 동작해요.

이 패턴은 주변 토폴로지가 단순한 "끝날 때까지 루프" 이상일 때 유용합니다. 예를 들어 여러 에이전트 중 하나로 라우팅하기 전에 입력을 분류하거나, 작업을 병렬로 팬아웃하거나, 결정적 단계들을 에이전트 호출과 이어 붙일 때요.

HumanInTheLoopMiddleware는 각 도구의 .name과 매칭돼요. Python에서 @tool 데코레이터가 붙은 함수는 함수 이름을 그 이름으로 가져가요(아래 예시의 키는 "send_email"). TypeScript에서는 tool({...}, { name })에 넘기는 name과 매칭됩니다.

from langchain.agents import AgentState, create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.graph import START, StateGraph

# Assumes read_email, send_email, classify_node, and route are defined elsewhere.
email_agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[read_email, send_email],
    middleware=[HumanInTheLoopMiddleware(interrupt_on={"send_email": True})],
)

graph = (
    StateGraph(AgentState)
    .add_node("classify", classify_node)
    .add_node("email_agent", email_agent)
    .add_edge(START, "classify")
    .add_conditional_edges("classify", route)
    .compile()
)

HITL 인터럽트, 요약, PII 마스킹, 재시도, 그리고 어떤 커스텀 훅이든 모두 에이전트 노드와 함께 이동해요. 서브그래프 체크포인터 스코프(호출별 대 스레드별)를 포함한 전체 컴포지션 패턴은 "Use subgraphs" 문서를 참고하세요.

내장 미들웨어 (Built-in middleware)

일반적인 용례를 위한 내장 미들웨어도 따로 준비되어 있어요. 요약(Summarization), Human-in-the-loop(HITL), PII 마스킹, 프롬프트 캐싱 같은 것들이 대표적이죠. 직접 만들어야 할 상황이 아니라면 내장 미들웨어를 먼저 살펴보는 게 좋습니다.

미들웨어 개요