[Deep Agents] 2. Middleware (미들웨어)

[Deep Agents] 2. Middleware (미들웨어)

 

지난 1편에서는 DeepAgents가 무엇인지, 그리고 Tool을 연결해 기본적인 에이전트를 만드는 방법을 정리했습니다

하지만 실제로 DeepAgents를 사용하다 보면 곧 이런 궁금증이 생깁니다

• 에이전트가 정말 Tool을 호출한 걸까?
• 어떤 Tool을 어떤 인자로 호출했을까?
• Tool 호출 횟수는 몇 번일까?
• 문제가 생기면 어디서부터 확인해야 할까?

이런 질문에 답하기 위해 필요한 것이 바로 미들웨어(Middleware) 입니다.

DeepAgents를 단순한 데모 수준이 아니라 실제로 디버깅하고, 검증하고, 확장 가능한 형태로 사용하려면
미들웨어 사용이 매우 중요합니다.

필요한 패키지 설치

pip install deepagents tavily-python
pip install langchain-openai
pip install python-dotenv

예시 코드

import os
from langchain.tools import tool
from langchain.agents.middleware import wrap_tool_call
from deepagents import create_deep_agent
from dotenv import load_dotenv

# .env 파일에서 환경변수 로드
load_dotenv()

# -----------------------------
# 1. 툴 정의
# -----------------------------
# @tool 데코레이터를 붙이면 이 함수는 에이전트가 사용할 수 있는 "툴"이 됨
@tool
def get_weather(city: str) -> str:
    """도시 이름을 받아 날씨 문자열을 반환하는 예제 툴"""
    return f"The weather in {city} is sunny."

# -----------------------------
# 2. 미들웨어에서 사용할 호출 횟수 저장 변수
# -----------------------------
# 내부 함수에서 값을 증가시키기 위해 리스트 사용
call_count = [0]

# -----------------------------
# 3. 툴 호출 미들웨어 정의
# -----------------------------
# 에이전트가 툴을 호출할 때 실행 전/후로 끼어들 수 있음
@wrap_tool_call
def log_tool_calls(request, handler):
    """모든 툴 호출을 가로채서 로그를 남기는 미들웨어"""

    # 호출 횟수 증가
    call_count[0] += 1

    # request 객체에 name 속성이 있으면 툴 이름 추출
    tool_name = request.name if hasattr(request, 'name') else str(request)

    # 호출 정보 출력
    print(f"[Middleware] Tool call #{call_count[0]}: {tool_name}")
    print(f"[Middleware] Arguments: {request.args if hasattr(request, 'args') else 'N/A'}")

    # 실제 툴 실행
    result = handler(request)

    # 실행 완료 로그
    print(f"[Middleware] Tool call #{call_count[0]} completed")

    # 결과 반환
    return result

# -----------------------------
# 4. 에이전트 생성
# -----------------------------
agent = create_deep_agent(
    model="openai:gpt-5.4",      # 사용할 모델
    tools=[get_weather],         # 사용할 툴 등록
    middleware=[log_tool_calls], # 툴 호출 시 적용할 미들웨어 등록
)

# -----------------------------
# 5. 에이전트 실행
# -----------------------------
# 사용자의 질문을 전달
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "서울의 날씨는?"}
    ]
})

# -----------------------------
# 6. 최종 응답 출력
# -----------------------------
print(result["messages"][-1].content)

이번 코드에서 중요한 부분은 아래 코드입니다.

@wrap_tool_call
def log_tool_calls(request, handler):

 

이 함수는 그냥 로그용 함수가 아닌 Tool 호출을 감싸는 미들웨어입니다.

즉, 에이전트가 Tool을 실행하려고 할 때마다 이 함수가 먼저 실행됩니다.

wrap_tool_call 미들웨어를 사용하는 이유는 

1. 실제로 Tool을 썼는지 확인하기 위해

에이전트는 때로 Tool 없이 바로 답할 수도 있다. 그래서 “정말 Tool을 사용했는가?”를 눈으로 확인할 필요가 있다.

2. 어떤 Tool이 선택됐는지 보기 위해

Tool이 여러 개라면 모델이 어떤 Tool을 골랐는지 추적해야 한다.

3. 어떤 인자로 호출됐는지 확인하기 위해

질문은 같아도 모델이 인자를 다르게 해석할 수 있다.
예를 들어 "서울 날씨"를 city="서울"로 넣는지, 다른 형태로 넣는지 확인해야 한다.

4. 실행 전후 시점을 분리해서 보기 위해

Tool 실행 전 로그와 후 로그를 남기면 문제가 어디서 발생했는지 찾기 쉬워진다.

 

1편에서는 DeepAgents의 기본 개념과 Tool 연결을 다뤘다면, 이번 2편에서는 그 Tool 사용 흐름을 추적하는 미들웨어에 대해서 알아봤습니다. 

즉, Tool이 에이전트의 능력이라면 미들웨어는 그 능력을 검증하고 추적하는 장치라고 볼 수 있습니다.