<경고> 알파 공지: 이 문서는 v1-alpha 릴리스에 대해 다룹니다. 내용은 불완전하며 변경될 수 있습니다.
최신 안정 버전은 v0 LangChain Python 또는 LangChain JavaScript 문서를 참조하세요. </경고>
미들웨어는 에이전트 내부에서 일어나는 일을 더 엄격하게 제어할 수 있는 방법을 제공합니다.
핵심 에이전트 루프는 model을 호출하고, 실행할 tools을 선택하게 한 다음, 더 이상 도구를 호출하지 않을 때 종료하는 과정을 포함합니다.
%%{ init: { "fontFamily": "monospace", "flowchart": { "curve": "curve" }, "themeVariables": {"edgeLabelBackground": "transparent"} } }%% graph TD %% 에이전트 외부 QUERY([입력]) LLM{모델} TOOL(도구) ANSWER([출력]) %% 주요 흐름 (인라인 레이블 없음) QUERY --> LLM LLM --"액션"--> TOOL TOOL --"관찰"--> LLM LLM --"종료"--> ANSWER classDef blueHighlight fill:#0a1c25,stroke:#0a455f,color:#bae6fd; classDef greenHighlight fill:#0b1e1a,stroke:#0c4c39,color:#9ce4c4; class QUERY blueHighlight; class ANSWER blueHighlight;
미들웨어는 이러한 단계 전후에 일어나는 일을 제어합니다. 각 미들웨어는 세 가지 다른 유형의 수정자를 추가할 수 있습니다.
before_model: 모델 실행 전에 실행됩니다. 상태를 업데이트하거나 다른 노드(model,tools,end)로 점프할 수 있습니다.modify_model_request: 모델 실행 전에 실행되어 모델 요청 객체를 준비합니다. 현재 모델 요청 객체만 수정할 수 있으며(영구적인 상태 업데이트 없음) 다른 노드로 점프할 수 없습니다.after_model: 모델 실행 후, 도구가 실행되기 전에 실행됩니다. 상태를 업데이트하거나 다른 노드(model,tools,END)로 점프할 수 있습니다.
그 외에도 각 미들웨어는 다음과 같은 정적 속성을 정의할 수 있습니다.
name: 미들웨어의 이름 (필수)tools: 미들웨어가 에이전트에 제공하는 도구 (선택 사항)state_schema: 미들웨어에 필요한 상태의 스키마 (선택 사항)
에이전트는 before_model, modify_model_request 또는 after_model 미들웨어를 포함할 수 있습니다. 세 가지 모두 구현할 필요는 없습니다.
%%{ init: { "fontFamily": "monospace", "flowchart": { "curve": "curve" }, "themeVariables": {"edgeLabelBackground": "transparent"} } }%% graph TD %% 에이전트 외부 QUERY([입력]) BEFORE_MODEL(Middleware.before_model) MODIFY_MODEL_REQUEST(Middleware.modify_model_request) LLM{모델} AFTER_MODEL(Middleware.after_model) TOOL(도구) ANSWER([출력]) %% 주요 흐름 (인라인 레이블 없음) QUERY --> BEFORE_MODEL BEFORE_MODEL --> MODIFY_MODEL_REQUEST MODIFY_MODEL_REQUEST --> LLM LLM --> AFTER_MODEL AFTER_MODEL --"액션"--> TOOL TOOL --"관찰"--> LLM LLM --"종료"--> ANSWER classDef blueHighlight fill:#0a1c25,stroke:#0a455f,color:#bae6fd; classDef greenHighlight fill:#0b1e1a,stroke:#0c4c39,color:#9ce4c4; class QUERY blueHighlight; class ANSWER blueHighlight;
에이전트에서 사용하기
create_agent에 미들웨어를 전달하여 에이전트에서 사용할 수 있습니다.
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware, HumanInTheLoopMiddleware
agent = create_agent(
...,
middleware=[SummarizationMiddleware(), HumanInTheLoopMiddleware()],
...
)미들웨어는 매우 유연하며 에이전트의 다른 일부 기능을 대체합니다. 따라서 미들웨어를 사용할 때 에이전트를 생성하는 데 사용되는 인수에 몇 가지 제한이 있습니다.
model은 문자열 또는BaseChatModel이어야 합니다. 함수가 전달되면 오류가 발생합니다. 모델을 동적으로 제어하려면AgentMiddleware.modify_model_request를 사용하세요.prompt는 문자열 또는 None이어야 합니다. 함수가 전달되면 오류가 발생합니다. 프롬프트를 동적으로 제어하려면AgentMiddleware.modify_model_request를 사용하세요.pre_model_hook은 제공되어서는 안 됩니다. 대신AgentMiddleware.before_model을 사용하세요.post_model_hook은 제공되어서는 안 됩니다. 대신AgentMiddleware.after_model을 사용하세요.
내장 미들웨어
LangChain은 즉시 사용할 수 있는 여러 내장 미들웨어를 제공합니다.
요약
summarizationMiddleware는 토큰 제한에 가까워지면 이전 메시지를 요약하여 대화 기록을 자동으로 관리합니다. 이 미들웨어는 메시지의 총 토큰 수를 모니터링하고 모델 제한 내에서 컨텍스트를 보존하기 위해 간결한 요약을 생성합니다.
주요 기능:
- 자동 토큰 계산 및 임계값 모니터링
- AI/도구 메시지 쌍을 보존하는 지능적인 메시지 분할
- 사용자 정의 가능한 요약 프롬프트 및 토큰 제한
사용 사례:
- 토큰 제한을 초과하는 장기 실행 대화
- 광범위한 컨텍스트를 가진 다중 턴 대화
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
agent = create_agent(
model="openai:gpt-4o",
tools=[weather_tool, calculator_tool],
middleware=[
SummarizationMiddleware(
model="openai:gpt-4o-mini",
max_tokens_before_summary=4000, # 4000 토큰에서 요약 트리거
messages_to_keep=20, # 요약 후 마지막 20개 메시지 유지
summary_prompt="Custom prompt for summarization...", # 선택 사항
),
],
)구성 옵션:
model: 요약 생성에 사용할 언어 모델 (필수)max_tokens_before_summary: 요약을 트리거하는 토큰 임계값messages_to_keep: 보존할 최근 메시지 수 (기본값: 20)token_counter: 토큰 계산을 위한 사용자 정의 함수 (기본값은 문자 기반 근사치)summary_prompt: 요약 생성을 위한 사용자 정의 프롬프트 템플릿summary_prefix: 요약을 포함하는 시스템 메시지에 추가되는 접두사 (기본값: ”## 이전 대화 요약:”)
미들웨어는 다음을 통해 도구 호출 무결성을 보장합니다.
- AI 메시지를 해당 도구 응답과 절대 분리하지 않음
- 연속성을 위해 가장 최근 메시지 보존
- 새 요약 주기에 이전 요약 포함
인간 참여형
HumanInTheLoopMiddleware는 에이전트가 수행하는 도구 호출에 대한 인간의 감독 및 개입을 가능하게 합니다. 자세한 내용은 인간 참여형 문서를 참조하세요.
이 미들웨어는 도구 실행을 가로채고 인간 운영자가 실행되기 전에 도구 호출을 승인, 수정, 거부 또는 수동으로 응답할 수 있도록 합니다.
Anthropic 프롬프트 캐싱
AnthropicPromptCachingMiddleware는 Anthropic의 기본 프롬프트 캐싱을 활성화할 수 있는 미들웨어입니다.
프롬프트 캐싱은 프롬프트의 특정 접두사에서 재개를 허용하여 최적의 API 사용을 가능하게 합니다. 이는 반복적인 프롬프트나 중복 정보가 있는 프롬프트가 있는 작업에 특히 유용합니다.
프롬프트 캐싱을 사용할 때 호출 간에 대화 기록을 저장하기 위해 검사 포인터를 사용하는 것이 좋습니다.
from langchain_anthropic import ChatAnthropic
from langchain.agents.middleware.prompt_caching import AnthropicPromptCachingMiddleware
from langchain.agents import create_agent
LONG_PROMPT = '''
도움이 되는 조수가 되어주세요.
<더 많은 컨텍스트 ...>
'''
agent = create_agent(
model=ChatAnthropic(model="claude-sonnet-4-latest"),
prompt=LONG_PROMPT,
middleware=[AnthropicPromptCachingMiddleware(ttl="5m")],
)
# 캐시 저장
agent.invoke({"messages": [HumanMessage("안녕하세요, 제 이름은 밥입니다")]})
# 캐시 히트, 시스템 프롬프트가 캐시됨
agent.invoke({"messages": [HumanMessage("제 이름이 뭐죠?")]})동적 시스템 프롬프트
시스템 프롬프트는 @modify_model_request 데코레이터를 사용하여 각 모델 호출 직전에 동적으로 설정할 수 있습니다. 이 미들웨어는 프롬프트가 현재 에이전트 상태 또는 런타임 컨텍스트에 따라 달라질 때 특히 유용합니다.
예를 들어 사용자의 전문 지식 수준에 따라 시스템 프롬프트를 조정할 수 있습니다.
from typing import TypedDict
from langchain.agents import create_agent
from langchain.agents.middleware.types import modify_model_request, AgentState, ModelRequest
from langgraph.runtime import Runtime
class Context(TypedDict):
user_role: str
@modify_model_request
def dynamic_system_prompt(request: ModelRequest, state: AgentState, runtime: Runtime[Context]) -> ModelRequest:
user_role = runtime.context.get("user_role", "user")
base_prompt = "당신은 도움이 되는 조수입니다."
if user_role == "expert":
prompt = f"{base_prompt} 상세한 기술적 답변을 제공하세요."
elif user_role == "beginner":
prompt = f"{base_prompt} 개념을 간단하게 설명하고 전문 용어를 피하세요."
else:
prompt = base_prompt
request.system_prompt = prompt
return request
agent = create_agent(
model="openai:gpt-4o",
tools=[web_search],
middleware=[dynamic_system_prompt],
context_schema=Context
)
# 컨텍스트와 함께 사용
result = agent.invoke(
{"messages": [{"role": "user", "content": "비동기 프로그래밍 설명"}]},
context={"user_role": "expert"}
)또는 대화 길이에 따라 시스템 프롬프트를 조정할 수 있습니다.
from langchain.agents.middleware.types import modify_model_request
@modify_model_request
def simple_prompt(state: AgentState, request: ModelRequest) -> ModelRequest:
message_count = len(state["messages"])
if message_count > 10:
prompt = "확장된 대화 중입니다. 더 간결하게 하세요."
else:
prompt = "당신은 도움이 되는 조수입니다."
request.system_prompt = prompt
return request
agent = create_agent(
model="openai:gpt-4o",
tools=[search_tool],
middleware=[simple_prompt],
)사용자 정의 미들웨어
에이전트용 미들웨어는 AgentMiddleware의 하위 클래스이며, 하나 이상의 훅을 구현합니다.
AgentMiddleware는 현재 핵심 에이전트 루프를 수정하는 세 가지 다른 방법을 제공합니다.
before_model: 모델이 실행되기 전에 실행됩니다. 상태를 업데이트하거나 점프를 통해 조기 종료할 수 있습니다.modify_model_request: 모델이 실행되기 전에 실행됩니다. 상태를 업데이트하거나 점프를 통해 조기 종료할 수 없습니다.after_model: 모델이 실행된 후에 실행됩니다. 상태를 업데이트하거나 점프를 통해 조기 종료할 수 있습니다.
조기 종료하려면 상태 업데이트에 jump_to 키를 다음 값 중 하나와 함께 추가할 수 있습니다.
"model": 모델 노드로 점프"tools": 도구 노드로 점프"end": 종료 노드로 점프
이것이 지정되면 모든 후속 미들웨어는 실행되지 않습니다.
에이전트 점프 섹션에서 조기 종료에 대해 자세히 알아보세요.
before_model
모델이 실행되기 전에 실행됩니다. 새 상태 객체 또는 상태 업데이트를 반환하여 상태를 수정할 수 있습니다.
서명:
from langchain.agents.middleware import AgentMiddleware, AgentState
from langchain_core.messages import AIMessage
class MyMiddleware(AgentMiddleware):
def before_model(self, state: AgentState) -> dict[str, Any] | None:
# 대화가 너무 길면 조기 종료
if len(state["messages"]) > 50:
return {
"messages": [AIMessage("죄송합니다, 대화가 종료되었습니다.")],
"jump_to": "end"
}
return statemodify_model_request
모델이 실행되기 전, 모든 before_model 호출 후에 실행됩니다.
이러한 함수는 영구 상태를 수정하거나 조기 종료할 수 없습니다.
오히려 상태 비저장 방식으로 모델에 대한 호출을 수정하기 위한 것입니다.
상태 저장 방식으로 모델에 대한 호출을 수정하려면 before_model을 사용해야 합니다.
모델 요청을 수정합니다. 모델 요청에는 몇 가지 주요 속성이 있습니다.
-
model(BaseChatModel): 사용할 모델. 참고: 문자열이 아닌 기본 채팅 모델이어야 합니다. -
system_prompt(str): 사용할 시스템 프롬프트.messages앞에 추가됩니다. -
messages(메시지 목록): 메시지 목록. 시스템 프롬프트를 포함해서는 안 됩니다. -
tool_choice(Any): 사용할 도구 선택 -
tools(문자열 목록): 이 모델 호출에 사용할 도구 이름 -
response_format(ResponseFormat): 구조화된 출력에 사용할 응답 형식
서명:
from langchain.agents.middleware import AgentState, ModelRequest, AgentMiddleware
class MyMiddleware(AgentMiddleware):
def modify_model_request(self, request: ModelRequest, state: AgentState) -> ModelRequest:
if len(state["messages"]) > 10:
request.model = "gpt-5"
else:
request.model = "gpt-5-nano"
return requestafter_model
모델이 실행된 후에 실행됩니다. 새 상태 객체 또는 상태 업데이트를 반환하여 상태를 수정할 수 있습니다.
서명:
from langchain.agents.middleware import AgentState, AgentUpdate, AgentMiddleware
class MyMiddleware(AgentMiddleware):
def after_model(self, state: AgentState) -> dict[str, Any] | None:
...새 상태 키
미들웨어는 사용자 정의 속성으로 에이전트의 상태를 확장하여 미들웨어 구성 요소 간의 풍부한 데이터 흐름을 가능하게 하고 에이전트 실행 전반에 걸쳐 유형 안전성을 보장할 수 있습니다.
상태 확장
미들웨어는 에이전트 실행 내내 지속되는 추가 상태 속성을 정의할 수 있습니다. 이러한 속성은 에이전트 상태의 일부가 되며 해당 미들웨어의 모든 훅에서 사용할 수 있습니다.
from langchain.agents.middleware import AgentState, AgentMiddleware
class MyState(AgentState):
model_call_count: int
class MyMiddleware(AgentMiddleware[MyState]):
state_schema: MyState
def before_model(self, state: AgentState) -> dict[str, Any] | None:
# 모델이 너무 많이 호출되면 조기 종료
if state["model_call_count"] > 10:
return {"jump_to": "end"}
return state
def after_model(self, state: AgentState) -> dict[str, Any] | None:
return {"model_call_count": state["model_call_count"] + 1}컨텍스트 확장
컨텍스트 속성은 실행 가능한 구성을 통해 전달되는 구성 값입니다. 상태와 달리 컨텍스트는 읽기 전용이며 일반적으로 실행 중에 변경되지 않는 구성에 사용됩니다.
여러 미들웨어 결합
여러 미들웨어를 사용할 때 상태 및 컨텍스트 스키마가 병합됩니다. 모든 미들웨어의 모든 필수 속성을 충족해야 합니다.
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from typing import Any, Dict
class Middleware1State(AgentState):
prop_1: str
shared_prop: int
class Middleware2State(AgentState):
prop_2: bool
shared_prop: int
class Middleware1(AgentMiddleware):
def before_model(self, state: Dict[str, Any]) -> Dict[str, Any] | None:
# 상태에서 prop1 및 sharedProp에 액세스
print(f"Middleware1: prop1={state.get('prop_1')}, sharedProp={state.get('shared_prop')}")
return None
class Middleware2(AgentMiddleware):
def before_model(self, state: Dict[str, Any]) -> Dict[str, Any] | None:
# 상태에서 prop2 및 sharedProp에 액세스
print(f"Middleware2: prop2={state.get('prop_2')}, sharedProp={state.get('shared_prop')}")
return None
agent = create_agent(
model="openai:gpt-4o",
tools=[],
middleware=[Middleware1(), Middleware2()],
)에이전트 수준 컨텍스트 스키마
에이전트는 미들웨어 요구 사항과 결합되는 자체 컨텍스트 요구 사항을 정의할 수도 있습니다.
# ...모범 사례
- 동적 데이터에 상태 사용: 실행 중에 변경되는 속성 (사용자 세션, 누적 데이터)
- 구성에 컨텍스트 사용: 정적 구성 값 (API 키, 기능 플래그, 제한)
- 가능한 경우 기본값 제공: Zod 스키마에서
.default()를 사용하여 속성을 선택 사항으로 만듭니다. - 요구 사항 문서화: 미들웨어에 필요한 상태 및 컨텍스트 속성을 명확하게 문서화합니다.
미들웨어 실행 순서
여러 미들웨어를 제공할 수 있습니다. 다음 논리에 따라 실행됩니다.
before_model: 전달된 순서대로 실행됩니다. 이전 미들웨어가 조기 종료되면 다음 미들웨어는 실행되지 않습니다.
modify_model_request: 전달된 순서대로 실행됩니다.
after_model: 전달된 역순으로 실행됩니다. 이전 미들웨어가 조기 종료되면 다음 미들웨어는 실행되지 않습니다.
에이전트 점프
조기 종료하려면 상태 업데이트에 jump_to 키를 다음 값 중 하나와 함께 추가할 수 있습니다.
"model": 모델 노드로 점프"tools": 도구 노드로 점프"end": 종료 노드로 점프
이것이 지정되면 모든 후속 미들웨어는 실행되지 않습니다.
model 노드로 점프하면 모든 before_model 미들웨어가 실행됩니다. 기존 before_model 미들웨어에서 model로 점프하는 것은 금지됩니다.
사용 예:
from langchain.agents.types import AgentState, AgentUpdate, AgentJump
from langchain.agents.middleware import AgentMiddleware
class MyMiddleware(AgentMiddleware):
def after_model(self, state: AgentState) -> dict[str, Any]:
return {
"messages": ...,
"jump_to": "model"
}예제
동적으로 도구 선택
많은 응용 프로그램에서 많은 도구 집합이 있을 수 있지만 특정 요청에 대해 관련성이 있는 것은 작은 하위 집합뿐입니다. 성능과 정확성을 최적화하려면 각 요청에 필요한 도구만 노출하는 것이 가장 좋습니다.
그렇게 하면 몇 가지 이점이 있습니다.
- 더 짧은 프롬프트 – 불필요한 복잡성 감소.
- 정확도 향상 – 모델이 더 적은 옵션 중에서 선택합니다.
- 권한 제어 – 사용자 권한에 따라 도구를 선택할 수 있습니다.
미들웨어를 사용하여 컨텍스트에 따라 런타임에 사용할 수 있는 도구를 동적으로 선택합니다.
from langchain.agents import create_agent
from langchain.agents.middleware import AgentState, ModelRequest, modify_model_request
@modify_model_request
def tool_selector(state: AgentState, request: ModelRequest) -> ModelRequest:
'''상태/컨텍스트에 따라 관련 도구를 선택하는 미들웨어.'''
# 상태/컨텍스트에 따라 작고 관련성 있는 도구 하위 집합 선택
request.tools = ["relevant_tool_1", "relevant_tool_2"] # [!code highlight]
return request
agent = create_agent(
...,
tools=all_tools, # 사용 가능한 모든 도구는 미리 등록해야 합니다.
# 미들웨어를 사용하여 주어진 실행에 관련성이 있는 더 작은 하위 집합을 선택할 수 있습니다.
middleware=[tool_selector], # [!code highlight]
)확장 예제: 런타임 컨텍스트에 따라 도구 선택
이 예제는 사용자의 공급자에 따라 GitHub와 GitLab 도구 중에서 선택하는 방법을 보여줍니다.
from dataclasses import dataclass
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.middleware import AgentState, ModelRequest, modify_model_request
from langchain.tools import tool
from langgraph.runtime import get_runtime
@tool
def github_create_issue(repo: str, title: str) -> dict:
'''GitHub 리포지토리에서 이슈를 생성합니다.'''
return {"url": f"https://github.com/{repo}/issues/1", "title": title}
@tool
def gitlab_create_issue(project: str, title: str) -> dict:
'''GitLab 프로젝트에서 이슈를 생성합니다.'''
return {"url": f"https://gitlab.com/{project}/-/issues/1", "title": title}
all_tools = [github_create_issue, gitlab_create_issue]
@dataclass
class Context:
provider: Literal["github", "gitlab"]
@modify_model_request
def select_tools(request: ModelRequest, state: AgentState) -> ModelRequest:
'''VCS 공급자에 따라 도구를 선택합니다.'''
runtime = get_runtime(Context)
provider = runtime.context.provider
selected_tools = ["gitlab_create_issue"] if provider == "gitlab" else ["github_create_issue"]
request.tools = selected_tools
return request
agent = create_agent(
model="openai:gpt-4o",
tools=all_tools,
middleware=[select_tools],
context_schema=Context,
)
# GitHub 컨텍스트로 호출
agent.invoke(
{
"messages": [{
"role": "user",
"content": "`its-a-cats-game` 리포지토리에 '버그: 고양이는 어디에 있나요'라는 제목의 이슈를 엽니다."
}]
},
context=Context(provider="github"),
)핵심 사항:
- 에이전트에 모든 도구를 미리 등록합니다.
- 미들웨어를 사용하여 요청당 관련 하위 집합을 선택합니다.
contextSchema를 사용하여 필요한 컨텍스트 속성을 정의합니다.- 실행 중에 변경되지 않는 구성에 컨텍스트를 사용합니다.
- 에이전트 실행 중에 변경되는 값에 상태를 사용합니다.