DeepAgents Tools 제공 방식 가이드

DeepAgents에서 agent에 도구(tools)를 제공하는 세 가지 방식을 비교하고 사용 사례를 정리한 문서입니다.

1. create_deep_agent에 tools 제공

from deepagents import create_deep_agent
 
def internet_search(query: str) -> str:
    """Run a web search"""
    return tavily_client.search(query)
 
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="Conduct research and write a polished report."
)

특징

• Main agent가 직접 도구 사용: agent가 tool을 즉시 호출할 수 있습니다
• 단일 context window: 모든 실행이 하나의 agent 내에서 진행됩니다
• 가장 간단한 방식: 도구만 추가하는 경우에 적합합니다

사용 시점

• 모든 도구를 main agent에서 항상 사용 가능하게 하고 싶을 때
• 도구와 특별한 instruction이 없을 때
• 간단한 커스텀 도구를 추가할 때

---

2. subagents에 tools 제공

from deepagents import create_deep_agent
 
research_subagent = {
    "name": "research-agent",
    "description": "Used to research in-depth questions",
    "prompt": "You are an expert researcher",
    "tools": [internet_search],  # subagent만 사용
    "model": "openai:gpt-4o",  # Optional
}
 
agent = create_deep_agent(subagents=[research_subagent])

특징

• Subagent가 도구 사용: main agent는 task() 도구를 사용해서 subagent에 작업을 위임합니다
• 격리된 context window: 각 subagent가 독립적인 컨텍스트에서 실행됩니다
• 작업 분리: 다양한 도메인의 작업을 전문화된 agent에게 할당합니다

사용 시점

• 특정 작업(예: research, analysis)에 전문화된 agent가 필요할 때
• Context window를 효율적으로 관리하고 싶을 때
• Domain-specific instructions가 필요할 때
• 다양한 모델을 사용하고 싶을 때 (subagent별로 다른 model 설정 가능)

장점

• Context window 효율성
• 작업 병렬 실행 가능
• 각 agent의 독립적인 instruction 관리

---

3. Middleware로 tools 제공

from langchain_core.tools import tool
from deepagents import create_deep_agent
from langchain.agents.middleware import AgentMiddleware
 
@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."
 
class WeatherMiddleware(AgentMiddleware):
    tools = [get_weather]
 
agent = create_deep_agent(middleware=[WeatherMiddleware()])

특징

• 도구 + 라이프사이클 관리: 도구 제공뿐만 아니라 라이프사이클 훅(hook)을 통해 추가 기능 구현
• 자동 instruction 추가: 도구 사용법을 자동으로 system prompt에 추가
• 가장 확장성 높음: extensibility와 유연성을 제공합니다

사용 시점

• 도구 + 자동 instruction + 추가 기능이 필요할 때
• 여러 agent 또는 middleware에서 재사용 가능한 도구 세트를 만들 때
• Lifecycle 훅을 활용한 추가 동작이 필요할 때

장점

• 도구와 관련 instruction을 함께 관리
• Lifecycle 훅으로 사전/사후 처리 가능
• 코드 재사용성과 일관성 향상

Built-in Middleware 예시

DeepAgents는 다음과 같은 built-in middleware를 제공합니다:

Middleware	제공되는 Tools	역할
TodoListMiddleware	write_todos, read_todos	작업 계획 및 진행상황 추적
FilesystemMiddleware	ls, read_file, write_file, edit_file, glob, grep, execute	파일 작업 및 컨텍스트 오프로딩
SubAgentMiddleware	task	Subagent 작업 위임
SummarizationMiddleware	(내부 사용)	컨텍스트 170k 토큰 초과 시 자동 요약

---

세 가지 방식의 비교

항목	tools 매개변수	middleware	subagents
용도	간단한 커스텀 도구 추가	도구 + 라이프사이클 관리	작업 위임 + 컨텍스트 격리
적용 범위	Main agent 전체	라이프사이클 동안 계속 작동	특정 subagent만
사용 복잡도	낮음	중간	중간
자동 instruction	없음	있음	있음 (subagent별)
Extensibility	낮음	높음 (lifecycle 훅)	중간 (독립적 agent)
Code 재사용성	낮음	높음	중간
Context 격리	없음	없음	있음

---

선택 가이드

tools 매개변수를 사용하세요

# ✅ 간단한 도구를 main agent에 추가
agent = create_deep_agent(tools=[calculator, get_weather])

middleware를 사용하세요

# ✅ 도구 + 자동 instruction + 특정 동작이 필요할 때
class CustomMiddleware(AgentMiddleware):
    tools = [specialized_search]
 
    def process_model_response(self, response):
        # 추가 처리 로직
        return response
 
agent = create_deep_agent(middleware=[CustomMiddleware()])

subagents를 사용하세요

# ✅ 작업 분리 + 컨텍스트 격리가 필요할 때
research_agent = {
    "name": "researcher",
    "prompt": "You are an expert researcher",
    "tools": [internet_search, arxiv_search]
}
 
analysis_agent = {
    "name": "analyst",
    "prompt": "You are a data analyst",
    "tools": [data_processing_tools]
}
 
agent = create_deep_agent(subagents=[research_agent, analysis_agent])

---

실제 사용 예시

예시 1: 간단한 검색 에이전트

# tools 매개변수 사용 (가장 간단)
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="You are a helpful search assistant."
)

예시 2: 연구 전문 에이전트

# middleware 사용 (도구 + 자동 instruction)
class ResearchMiddleware(AgentMiddleware):
    tools = [internet_search, arxiv_search, pdf_reader]
 
    def process_model_response(self, response):
        # 연구 결과 자동 정리
        return response
 
agent = create_deep_agent(middleware=[ResearchMiddleware()])

예시 3: 복잡한 멀티 태스크 에이전트

# subagents 사용 (작업 분리 + 컨텍스트 격리)
research_subagent = {
    "name": "researcher",
    "description": "Conducts in-depth research",
    "prompt": "You are an expert researcher. Focus on accuracy and depth.",
    "tools": [internet_search, arxiv_search]
}
 
analysis_subagent = {
    "name": "analyst",
    "description": "Analyzes and synthesizes information",
    "prompt": "You are a data analyst. Focus on patterns and insights.",
    "tools": [data_processor, statistical_tools]
}
 
agent = create_deep_agent(
    system_prompt="Coordinate research and analysis tasks",
    subagents=[research_subagent, analysis_subagent]
)

---

결론

상황	권장 방식
빠르게 프로토타입을 만들 때	tools
도구와 자동화된 instruction이 필요할 때	middleware
복잡한 멀티 태스크 에이전트를 설계할 때	subagents
여러 도메인의 작업을 효율적으로 관리할 때	middleware + subagents

세 가지 방식을 상황에 맞게 조합하여 사용하면 효과적인 에이전트 시스템을 구축할 수 있습니다.

---

참고

• DeepAgents 공식 문서: https://docs.langchain.com/oss/python/deepagents/overview
• LangGraph 문서: https://langchain-ai.github.io/langgraph/
• Quickstarts: https://github.com/langchain-ai/deepagents-quickstarts