deepagent.ipynb

from dotenv import load_dotenv
 
 
load_dotenv(".env", override=True)

🧠🤖Deep Agents

LLM이 루프에서 도구를 호출하는 것이 에이전트의 가장 단순한 형태입니다. 그러나 이 아키텍처는 “얕은” 에이전트를 만들 수 있으며, 더 길고 복잡한 작업에 대해 계획하고 행동하지 못할 수 있습니다.

“Deep Research”, “Manus”, “Claude Code”와 같은 애플리케이션은 네 가지 기능의 조합을 구현하여 이 한계를 극복했습니다: 계획 도구, 하위 에이전트, 파일 시스템 접근, 그리고 상세한 프롬프트.

deepagents는 일반적인 용도로 이들을 구현하는 Python 패키지이므로 애플리케이션을 위해 Deep Agent를 쉽게 만들 수 있습니다.

deepagents의 전체 개요와 빠른 시작을 위해서는 Deep Agents overview 문서를 참고하는 것이 좋습니다.

설치

pip install deepagents tavily-python

사용법

환경에 TAVILY_API_KEY를 설정해야 합니다. 여기에서 생성할 수 있습니다.

import os
from typing import Literal
 
from deepagents import create_deep_agent
from tavily import TavilyClient
 
 
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
 
# 웹 검색 도구
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """웹 검색 실행"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
 
 
# 에이전트를 전문 연구원으로 유도하는 시스템 프롬프트
research_instructions = """당신은 전문 연구원입니다. 당신의 역할은 철저한 연구를 수행하고 정교한 보고서를 작성하는 것입니다.
 
인터넷 검색 도구에 접근할 수 있으며, 이것이 정보 수집의 주요 수단입니다.
 
## `internet_search`
 
주어진 쿼리에 대해 인터넷 검색을 실행하려면 이 기능을 사용합니다. 반환할 결과의 최대 수, 주제, 원본 콘텐츠 포함 여부를 지정할 수 있습니다.
"""
 
# Deep Agent 생성
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions,
)
agent

from utils import format_messages
 
 
# 에이전트 호출
result = agent.invoke(
    {"messages": [{"role": "user", "content": "langgraph란 무엇인가요?"}]}
)
format_messages(result)

더 복잡한 예제는 research_agent.py를 참고하세요.

create_deep_agent로 만든 에이전트는 단순한 LangGraph 그래프이므로, LangGraph 에이전트와 같은 방식으로(스트리밍, 휴먼-인-더-루프, 메모리, 스튜디오) 상호작용할 수 있습니다.

참고: create_deep_agent는 모델명을 생략하면 기본 모델로 Claude Sonnet 4.5를 사용한다.

def get_default_model() -> ChatAnthropic:
    """Get the default model for deep agents.
 
    Returns:
        ChatAnthropic instance configured with Claude Sonnet 4.
    """
    return ChatAnthropic(
        model_name="claude-sonnet-4-5-20250929",
        max_tokens=20000,
    )

소스코드: https://github.com/langchain-ai/deepagents/blob/338787bbb186004b0d1f0a8333274e3e34f8d61e/libs/deepagents/deepagents/graph.py#L28-L37

핵심 기능

계획 및 작업 분해

Deep Agents는 에이전트가 복잡한 작업을 개별 단계로 분해하고, 진행 상황을 추적하고, 새로운 정보가 나타나면 계획을 수정할 수 있도록 하는 내장 write_todos 도구를 포함합니다.

컨텍스트 관리

파일 시스템 도구(ls, read_file, write_file, edit_file, glob, grep)를 통해 에이전트는 큰 컨텍스트를 메모리로 오프로드할 수 있으며, 컨텍스트 윈도우 오버플로우를 방지하고 가변 길이 도구 결과로 작업할 수 있습니다.

하위 에이전트 생성

내장 task 도구를 통해 에이전트는 컨텍스트 격리를 위해 특화된 하위 에이전트를 생성할 수 있습니다. 이는 메인 에이전트의 컨텍스트를 깔끔하게 유지하면서 특정 하위 작업을 깊이 있게 수행합니다.

장기 메모리

LangGraph의 Store를 사용하여 에이전트를 스레드 간 지속적인 메모리로 확장합니다. 에이전트는 이전 대화에서 정보를 저장하고 검색할 수 있습니다.

Deep Agents 커스터마이징

create_deep_agent에 전달할 수 있는 여러 매개변수가 있어 자신의 커스텀 Deep Agent를 만들 수 있습니다.

model

기본적으로 deepagents는 "claude-sonnet-4-5-20250929"를 사용합니다. 모든 LangChain 모델 객체를 전달하여 커스터마이징할 수 있습니다.

from deepagents import create_deep_agent
 
from langchain.chat_models import init_chat_model
 
 
model = init_chat_model("openai:gpt-4o")
agent = create_deep_agent(
    model=model,
)

from deepagents import create_deep_agent
 
from langchain.chat_models import init_chat_model
 
 
model = init_chat_model("openai:gpt-4o")
agent = create_deep_agent(
    model=model,
)

system_prompt

Deep Agents는 내장 시스템 프롬프트를 가지고 있습니다. 이것은 Claude Code의 시스템 프롬프트를 복제하려는 시도에 기반을 두고 영감을 받은 상대적으로 상세한 프롬프트입니다. Claude Code의 시스템 프롬프트보다 더 일반적인 용도로 만들어졌습니다. 기본 프롬프트는 내장 계획 도구, 파일 시스템 도구, 하위 에이전트 사용 방법에 대한 상세한 지침을 포함합니다.

각 사용 사례에 맞춘 Deep Agent는 그 사용 사례에 특화된 커스텀 시스템 프롬프트도 포함해야 합니다. 성공적인 Deep Agent를 만드는 데 있어 프롬프팅의 중요성을 아무리 강조해도 부족합니다.

from deepagents import create_deep_agent
 
 
research_instructions = """당신은 전문 연구원입니다.
당신의 역할은 철저한 연구를 수행하고 정교한 보고서를 작성하는 것입니다.
"""
 
agent = create_deep_agent(
    system_prompt=research_instructions,
)

tools

도구 호출 에이전트와 마찬가지로 Deep Agent에 접근 가능한 도구 세트를 제공할 수 있습니다.

import os
from typing import Literal
 
from deepagents import create_deep_agent
from tavily import TavilyClient
 
 
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
 
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """웹 검색 실행"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
 
 
agent = create_deep_agent(tools=[internet_search])

middleware

create_deep_agent는 커스터마이징 가능한 미들웨어로 구현됩니다.

기능을 확장하고, 도구를 추가하거나, 커스텀 훅을 구현하기 위해 추가 미들웨어를 제공할 수 있습니다.

from deepagents import create_deep_agent
from langchain_core.tools import tool
 
from langchain.agents.middleware import AgentMiddleware
 
 
@tool
def get_weather(city: str) -> str:
    """도시의 날씨를 가져옵니다."""
    return f"{city}의 날씨는 맑습니다."
 
 
@tool
def get_temperature(city: str) -> str:
    """도시의 기온을 가져옵니다."""
    return f"{city}의 기온은 화씨 70도입니다."
 
 
class WeatherMiddleware(AgentMiddleware):
    tools = [get_weather, get_temperature]
 
 
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    middleware=[WeatherMiddleware()],
)

subagents

Deep Agents의 주요 기능은 하위 에이전트를 생성할 수 있다는 것입니다. subagents 매개변수에 에이전트가 작업을 위임할 수 있는 커스텀 하위 에이전트를 지정할 수 있습니다. 하위 에이전트는 컨텍스트 격리(메인 에이전트의 전체 컨텍스트가 오염되는 것을 방지하기 위해)와 커스텀 지침 제공에 유용합니다.

subagents는 각 딕셔너리가 다음 스키마를 따르는 딕셔너리 목록이어야 합니다:

from collections.abc import Callable, Sequence
from typing import Any, NotRequired, TypedDict
 
from langchain_core.runnables import Runnable
from langchain_core.tools import BaseTool
 
from langchain.agents.middleware import InterruptOnConfig
from langchain.chat_models import BaseChatModel
 
 
class SubAgent(TypedDict):
    name: str
    description: str
    prompt: str
    tools: Sequence[BaseTool | Callable | dict[str, Any]]
    model: NotRequired[str | BaseChatModel]
    middleware: NotRequired[list[AgentMiddleware]]
    interrupt_on: NotRequired[dict[str, bool | InterruptOnConfig]]
 
 
class CompiledSubAgent(TypedDict):
    name: str
    description: str
    runnable: Runnable

SubAgent 필드:

• name: 하위 에이전트의 이름이며, 메인 에이전트가 하위 에이전트를 호출할 때 사용합니다.
• description: 메인 에이전트에게 표시되는 하위 에이전트의 설명입니다.
• prompt: 하위 에이전트에 사용되는 프롬프트입니다.
• tools: 하위 에이전트가 접근할 수 있는 도구 목록입니다.
• model: 선택적 모델 이름 또는 모델 인스턴스입니다.
• middleware: 하위 에이전트에 첨부할 추가 미들웨어입니다. 미들웨어 소개와 작동 방식에 대해서는 여기를 참고하세요.
• interrupt_on: 도구에 대한 휴먼-인-더-루프 상호작용을 지정하는 커스텀 인터럽트 구성입니다.

CompiledSubAgent 필드:

• name: 하위 에이전트의 이름이며, 메인 에이전트가 하위 에이전트를 호출할 때 사용합니다.
• description: 메인 에이전트에게 표시되는 하위 에이전트의 설명입니다.
• runnable: 하위 에이전트로 사용될 미리 구축된 LangGraph 그래프/에이전트입니다.

SubAgent 사용

from collections.abc import Sequence
import os
from typing import Literal
 
from deepagents import CompiledSubAgent, SubAgent, create_deep_agent
from tavily import TavilyClient
 
 
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
 
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """웹 검색 실행"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )
 
 
research_subagent: SubAgent = {
    "name": "research-agent",
    "description": "더 심화된 질문을 조사하는 데 사용됩니다",
    "system_prompt": "당신은 훌륭한 연구원입니다",
    "tools": [internet_search],
    "model": "openai:gpt-4o",  # 선택적 오버라이드, 기본값은 메인 에이전트 모델
}
 
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    subagents=[research_subagent],
)

CustomSubAgent 사용

더 복잡한 사용 사례를 위해 자신의 미리 구축된 LangGraph 그래프를 하위 에이전트로 제공할 수 있습니다:

from langchain.agents import create_agent
 
 
specialized_tools = []
 
# 미리 구축된 커스텀 에이전트 그래프
custom_graph = create_agent(
    model=model,
    tools=specialized_tools,
    system_prompt="당신은 데이터 분석을 위한 전문화된 에이전트입니다...",
)
 
# 커스텀 하위 에이전트로 사용
custom_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="복잡한 데이터 분석 작업을 위한 전문화된 에이전트",
    runnable=custom_graph,
)
 
subagents = [custom_subagent]
 
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[internet_search],
    system_prompt=research_instructions,
    subagents=subagents,
)

interrupt_on

에이전트의 일반적인 현실은 일부 도구 작업이 민감할 수 있으며 실행 전에 사람의 승인이 필요할 수 있다는 것입니다. Deep Agents는 LangGraph의 인터럽트 기능을 통해 휴먼-인-더-루프 워크플로우를 지원합니다. 체크포인터를 사용하여 어떤 도구가 승인을 요구하는지 구성할 수 있습니다.

이러한 도구 구성은 미리 구축된 HITL 미들웨어에 전달되므로 에이전트가 실행을 일시 중지하고 구성된 도구를 실행하기 전에 사용자의 피드백을 기다립니다.

from deepagents import create_deep_agent
from langchain_core.tools import tool
 
from langgraph.checkpoint.memory import InMemorySaver
 
 
@tool
def get_weather(city: str) -> str:
    """도시의 날씨를 가져옵니다."""
    return f"{city}의 날씨는 맑습니다."
 
 
# Deep Agent 인스턴스 생성
agent = create_deep_agent(
    # 사용할 LLM 모델 지정
    model="anthropic:claude-sonnet-4-20250514",
    # 에이전트가 사용 가능한 도구 목록
    tools=[get_weather],
    # 휴먼-인-더-루프(Human-in-the-Loop) 설정
    # 특정 도구가 호출될 때 사람의 개입을 요청하도록 설정
    # get_weather 도구가 호출되려 할 때:
    # - "approve": 사람이 승인하면 도구 실행
    # - "edit": 사람이 도구 입력값을 수정
    # - "reject": 사람이 거절하면 도구 실행 안 함
    interrupt_on={
        "get_weather": {"allowed_decisions": ["approve", "edit", "reject"]},
    },
    checkpointer=InMemorySaver(),
)

from uuid import uuid4
 
from langchain_core.runnables import RunnableConfig
 
 
config = RunnableConfig(configurable={"thread_id": uuid4()})
 
# 에이전트 호출
result = agent.invoke(
    {"messages": [{"role": "user", "content": "오늘 서울 날씨는?"}]},
    config=config,
)
result

{'messages': [HumanMessage(content='오늘 서울 날씨는?', additional_kwargs={}, response_metadata={}, id='4d0bf508-ca45-4015-94b6-269a11344a43'),
  AIMessage(content=[{'text': '서울의 오늘 날씨를 확인해드리겠습니다.', 'type': 'text'}, {'id': 'toolu_01MeKvCBnJ66DsCnqrXvARJB', 'input': {'city': '서울'}, 'name': 'get_weather', 'type': 'tool_use'}], additional_kwargs={}, response_metadata={'id': 'msg_01XYTekbagQ7pUAf4qoDn9jH', 'model': 'claude-sonnet-4-20250514', 'stop_reason': 'tool_use', 'stop_sequence': None, 'usage': {'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 0}, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 5676, 'input_tokens': 3, 'output_tokens': 80, 'server_tool_use': None, 'service_tier': 'standard'}, 'model_name': 'claude-sonnet-4-20250514', 'model_provider': 'anthropic'}, id='lc_run--4b14eb35-a9af-49b0-afa7-a9ce2232c48e-0', tool_calls=[{'name': 'get_weather', 'args': {'city': '서울'}, 'id': 'toolu_01MeKvCBnJ66DsCnqrXvARJB', 'type': 'tool_call'}], usage_metadata={'input_tokens': 5679, 'output_tokens': 80, 'total_tokens': 5759, 'input_token_details': {'cache_read': 5676, 'cache_creation': 0, 'ephemeral_5m_input_tokens': 0, 'ephemeral_1h_input_tokens': 0}})],
 '__interrupt__': [Interrupt(value={'action_requests': [{'name': 'get_weather', 'args': {'city': '서울'}, 'description': "Tool execution requires approval\n\nTool: get_weather\nArgs: {'city': '서울'}"}], 'review_configs': [{'action_name': 'get_weather', 'allowed_decisions': ['approve', 'edit', 'reject']}]}, id='be4534667c08a16555d41340e83a8fcb')]}

from langgraph.graph.state import Command
 
 
result = agent.invoke(
    Command(resume={"decisions": [{"type": "approve"}]}),
    config=config,
)
result

{'messages': [HumanMessage(content='오늘 서울 날씨는?', additional_kwargs={}, response_metadata={}, id='4d0bf508-ca45-4015-94b6-269a11344a43'),
  AIMessage(content=[{'text': '서울의 오늘 날씨를 확인해드리겠습니다.', 'type': 'text'}, {'id': 'toolu_01MeKvCBnJ66DsCnqrXvARJB', 'input': {'city': '서울'}, 'name': 'get_weather', 'type': 'tool_use'}], additional_kwargs={}, response_metadata={'id': 'msg_01XYTekbagQ7pUAf4qoDn9jH', 'model': 'claude-sonnet-4-20250514', 'stop_reason': 'tool_use', 'stop_sequence': None, 'usage': {'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 0}, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 5676, 'input_tokens': 3, 'output_tokens': 80, 'server_tool_use': None, 'service_tier': 'standard'}, 'model_name': 'claude-sonnet-4-20250514', 'model_provider': 'anthropic'}, id='lc_run--4b14eb35-a9af-49b0-afa7-a9ce2232c48e-0', tool_calls=[{'name': 'get_weather', 'args': {'city': '서울'}, 'id': 'toolu_01MeKvCBnJ66DsCnqrXvARJB', 'type': 'tool_call'}], usage_metadata={'input_tokens': 5679, 'output_tokens': 80, 'total_tokens': 5759, 'input_token_details': {'cache_creation': 0, 'cache_read': 5676, 'ephemeral_5m_input_tokens': 0, 'ephemeral_1h_input_tokens': 0}}),
  ToolMessage(content='서울의 날씨는 맑습니다.', name='get_weather', id='0a18ce11-39f6-466f-916a-90109c8bc5c6', tool_call_id='toolu_01MeKvCBnJ66DsCnqrXvARJB'),
  AIMessage(content='오늘 서울의 날씨는 **맑습니다**. 좋은 날씨네요!', additional_kwargs={}, response_metadata={'id': 'msg_01TmMB9PowPsDUxUzfVoEzSi', 'model': 'claude-sonnet-4-20250514', 'stop_reason': 'end_turn', 'stop_sequence': None, 'usage': {'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 104}, 'cache_creation_input_tokens': 104, 'cache_read_input_tokens': 5676, 'input_tokens': 5, 'output_tokens': 35, 'server_tool_use': None, 'service_tier': 'standard'}, 'model_name': 'claude-sonnet-4-20250514', 'model_provider': 'anthropic'}, id='lc_run--371f3335-656e-4665-8bde-b913e679747e-0', usage_metadata={'input_tokens': 5785, 'output_tokens': 35, 'total_tokens': 5820, 'input_token_details': {'cache_read': 5676, 'cache_creation': 104, 'ephemeral_5m_input_tokens': 104, 'ephemeral_1h_input_tokens': 0}})]}

config = RunnableConfig(configurable={"thread_id": uuid4()})
result = agent.invoke(
    {"messages": [{"role": "user", "content": "오늘 서울 날씨는?"}]},
    config=config,
)
result = agent.invoke(
    Command(resume={"decisions": [{"type": "reject"}]}),
    config=config,
)
result

{'messages': [HumanMessage(content='오늘 서울 날씨는?', additional_kwargs={}, response_metadata={}, id='1d58209f-13d9-4066-aa11-300fcd9e5f81'),
  AIMessage(content=[{'text': '서울의 오늘 날씨를 확인해드리겠습니다.', 'type': 'text'}, {'id': 'toolu_01SneWTNnYpRBtKowmzWwSwe', 'input': {'city': '서울'}, 'name': 'get_weather', 'type': 'tool_use'}], additional_kwargs={}, response_metadata={'id': 'msg_01ESgyzVktH7ocXAJ4LziqSM', 'model': 'claude-sonnet-4-20250514', 'stop_reason': 'tool_use', 'stop_sequence': None, 'usage': {'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 0}, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 5676, 'input_tokens': 3, 'output_tokens': 80, 'server_tool_use': None, 'service_tier': 'standard'}, 'model_name': 'claude-sonnet-4-20250514', 'model_provider': 'anthropic'}, id='lc_run--f29fa7e8-7d3e-4188-bc9b-86dab8a2e857-0', tool_calls=[{'name': 'get_weather', 'args': {'city': '서울'}, 'id': 'toolu_01SneWTNnYpRBtKowmzWwSwe', 'type': 'tool_call'}], usage_metadata={'input_tokens': 5679, 'output_tokens': 80, 'total_tokens': 5759, 'input_token_details': {'cache_creation': 0, 'cache_read': 5676, 'ephemeral_5m_input_tokens': 0, 'ephemeral_1h_input_tokens': 0}}),
  ToolMessage(content='User rejected the tool call for `get_weather` with id toolu_01SneWTNnYpRBtKowmzWwSwe', name='get_weather', id='bfd73daf-5505-4f24-9c74-18bead370b2c', tool_call_id='toolu_01SneWTNnYpRBtKowmzWwSwe', status='error'),
  AIMessage(content='죄송합니다. 날씨 정보를 가져올 수 없습니다. 날씨 정보를 확인하시려면 다음과 같은 방법을 추천드립니다:\n\n1. **날씨 앱 사용**: 스마트폰의 기본 날씨 앱이나 네이버 날씨, 웨더채널 등의 앱 활용\n2. **포털 사이트**: 네이버, 다음 등에서 "서울 날씨" 검색\n3. **기상청 홈페이지**: weather.go.kr에서 정확한 기상정보 확인\n4. **실시간 검색**: "서울 날씨"로 검색하면 현재 기온, 습도, 강수확률 등을 확인할 수 있습니다\n\n다른 도움이 필요하시면 언제든 말씀해 주세요!', additional_kwargs={}, response_metadata={'id': 'msg_01MVzFJpFx6j2kr6ZAKX4tu8', 'model': 'claude-sonnet-4-20250514', 'stop_reason': 'end_turn', 'stop_sequence': None, 'usage': {'cache_creation': {'ephemeral_1h_input_tokens': 0, 'ephemeral_5m_input_tokens': 132}, 'cache_creation_input_tokens': 132, 'cache_read_input_tokens': 5676, 'input_tokens': 7, 'output_tokens': 271, 'server_tool_use': None, 'service_tier': 'standard'}, 'model_name': 'claude-sonnet-4-20250514', 'model_provider': 'anthropic'}, id='lc_run--a5f43739-4766-4c09-aca7-07fc33339f38-0', usage_metadata={'input_tokens': 5815, 'output_tokens': 271, 'total_tokens': 6086, 'input_token_details': {'cache_read': 5676, 'cache_creation': 132, 'ephemeral_5m_input_tokens': 132, 'ephemeral_1h_input_tokens': 0}})]}

Deep Agents 미들웨어

Deep Agents는 모듈식 미들웨어 아키텍처로 구축됩니다. 상기했듯이, Deep Agents는 다음에 접근할 수 있습니다:

• 계획 도구
• 컨텍스트와 장기 메모리를 저장하기 위한 파일 시스템
• 하위 에이전트를 생성하는 기능

이러한 각 기능은 별도의 미들웨어로 구현됩니다. create_deep_agent로 Deep Agent를 만들 때, 우리는 자동으로 TodoListMiddleware, FilesystemMiddleware, SubAgentMiddleware를 에이전트에 첨부합니다.

미들웨어는 구성 가능한 개념이며, 사용 사례에 따라 에이전트에 원하는 만큼 많거나 적은 미들웨어를 추가할 수 있습니다. 즉, 앞서 언급한 미들웨어 중 어느 것도 독립적으로 사용할 수 있습니다!

TodoListMiddleware

계획은 복잡한 문제를 해결하는 데 필수적입니다. 최근에 Claude Code를 사용해본 적이 있다면, 복잡한 다중 부분 작업을 수행하기 전에 어떻게 To-Do 목록을 작성하는지 알 수 있습니다. 새로운 정보가 들어오면서 이 To-Do 목록을 즉석에서 어떻게 수정하고 업데이트할 수 있는지도 알 수 있습니다.

TodoListMiddleware는 에이전트에 이 To-Do 목록을 업데이트하기 위한 특정 도구를 제공합니다. 다중 부분 작업을 실행하기 전후에 에이전트는 write_todos 도구를 사용하여 자신이 하고 있는 작업과 남은 작업을 추적하라는 프롬프트가 표시됩니다.

from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware
 
 
# TodoListMiddleware는 create_deep_agent에서 기본적으로 포함됩니다
# 커스텀 에이전트를 구축할 때 커스터마이징할 수 있습니다
agent = create_agent(
    model="anthropic:claude-haiku-4-5",
    # 커스텀 계획 지침은 미들웨어를 통해 추가할 수 있습니다
    middleware=[
        TodoListMiddleware(
            system_prompt="write_todos 도구를 사용하여..."  # 선택적: 시스템 프롬프트에 대한 커스텀 추가
        ),
    ],
)

FilesystemMiddleware

컨텍스트 엔지니어링은 효과적인 에이전트를 구축하는 데 있어 주요 과제 중 하나입니다. 특히 가변 길이 결과를 반환할 수 있는 도구(예: web_search, rag)를 사용할 때는 더욱 어려울 수 있으며, 긴 ToolResults가 빠르게 컨텍스트 윈도우를 채울 수 있습니다.

FilesystemMiddleware는 에이전트에 단기 및 장기 메모리와 상호작용할 수 있는 네 가지 도구를 제공합니다.

• ls: 파일 시스템의 파일 목록 표시
• read_file: 파일 전체 또는 파일의 특정 행 수 읽기
• write_file: 파일 시스템에 새 파일 작성
• edit_file: 파일 시스템의 기존 파일 편집

from deepagents.middleware.filesystem import FilesystemMiddleware
 
from langchain.agents import create_agent
 
 
# FilesystemMiddleware는 create_deep_agent에서 기본적으로 포함됩니다
# 커스텀 에이전트를 구축할 때 커스터마이징할 수 있습니다
agent = create_agent(
    model="anthropic:claude-sonnet-4-20250514",
    middleware=[
        FilesystemMiddleware(
            # backend=...,  # 선택적: 저장소 백엔드 커스터마이징
            system_prompt="파일 시스템에 쓸 때...",  # 선택적: 커스텀 시스템 프롬프트 오버라이드
            custom_tool_descriptions={
                "ls": "다음의 경우에 ls 도구를 사용하세요...",
                "read_file": "read_file 도구를 사용하여...",
            },  # 선택적: 파일 시스템 도구에 대한 커스텀 설명
        ),
    ],
)

SubAgentMiddleware

하위 에이전트에 작업을 위임하는 것은 컨텍스트를 격리하는 좋은 방법으로, 메인(감독) 에이전트의 컨텍스트 윈도우를 깔끔하게 유지하면서도 작업을 깊이 있게 수행할 수 있습니다. 하위 에이전트 미들웨어를 통해 task 도구를 통해 하위 에이전트를 제공할 수 있습니다.

하위 에이전트는 이름, 설명, 시스템 프롬프트, 도구로 정의됩니다. 하위 에이전트에 커스텀 모델이나 추가 미들웨어를 제공할 수도 있습니다. 이는 하위 에이전트에 메인 에이전트와 공유할 추가 상태 키를 제공하려는 경우 특히 유용할 수 있습니다.

from deepagents.middleware.subagents import SubAgentMiddleware
from langchain_core.tools import tool
 
from langchain.agents import create_agent
 
 
@tool
def get_weather(city: str) -> str:
    """도시의 날씨를 가져옵니다."""
    return f"{city}의 날씨는 맑습니다."
 
 
agent = create_agent(
    model="claude-sonnet-4-20250514",
    middleware=[
        SubAgentMiddleware(
            default_model="anthropic:claude-haiku-4-5",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "이 하위 에이전트는 도시의 날씨를 가져올 수 있습니다.",
                    "system_prompt": "get_weather 도구를 사용하여 도시의 날씨를 가져옵니다.",
                    "tools": [get_weather],
                    "model": "gpt-4.1",
                    "middleware": [],
                }
            ],
        )
    ],
)

더 복잡한 사용 사례의 경우 자신의 미리 구축된 LangGraph 그래프를 하위 에이전트로 제공할 수 있습니다.

from langgraph import StateGraph
 
 
# 커스텀 LangGraph 그래프 생성
def create_weather_graph():
    workflow = StateGraph(...)
    # 커스텀 그래프 구축
    return workflow.compile()
 
 
weather_graph = create_weather_graph()
 
# CompiledSubAgent에 래핑
weather_subagent = CompiledSubAgent(
    name="weather",
    description="이 하위 에이전트는 도시의 날씨를 가져올 수 있습니다.",
    runnable=weather_graph,
)
 
agent = create_agent(
    model="anthropic:claude-sonnet-4-20250514",
    middleware=[
        SubAgentMiddleware(
            default_model="anthropic:claude-haiku-4-5",
            default_tools=[],
            subagents=[weather_subagent],
        )
    ],
)

동기 대 비동기

deepagents의 이전 버전은 동기 및 비동기 에이전트 팩토리를 구분했습니다.

async_create_deep_agent가 create_deep_agent로 통합되었습니다.

동기 및 비동기 에이전트 모두에 대해 팩토리로 create_deep_agent를 사용해야 합니다.

MCP

deepagents 라이브러리는 MCP 도구와 함께 실행할 수 있습니다. 이는 Langchain MCP Adapter 라이브러리를 사용하여 달성할 수 있습니다.

참고: MCP 도구는 비동기이므로 from deepagents import async_create_deep_agent를 사용하려고 합니다.

(아래 예제를 실행하려면 pip install langchain-mcp-adapters를 설치해야 합니다.)

import asyncio
 
from deepagents import create_deep_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
import nest_asyncio
 
 
nest_asyncio.apply()
 
 
async def main():
    # MCP 도구 수집
    mcp_client = MultiServerMCPClient(
        {
            "fetch": {
                "transport": "stdio",
                "command": "uvx",
                "args": ["mcp-server-fetch"],
            }
        }
    )
    mcp_tools = await mcp_client.get_tools()
 
    # 에이전트 생성
    agent = create_deep_agent(tools=mcp_tools)
 
    # 에이전트 스트리밍
    async for chunk in agent.astream(
        {"messages": [{"role": "user", "content": "langgraph란 무엇인가요?"}]},
        stream_mode="values",
    ):
        if "messages" in chunk:
            chunk["messages"][-1].pretty_print()
 
 
asyncio.run(main())

================================ Human Message =================================

langgraph란 무엇인가요?
================================ Human Message =================================

langgraph란 무엇인가요?
================================== Ai Message ==================================

LangGraph는 **LangChain 생태계의 일부로 개발된 라이브러리**로, LLM(대규모 언어 모델) 애플리케이션에서 **복잡한 에이전트 워크플로우를 그래프 형태로 구축**할 수 있게 해주는 프레임워크입니다.

## 주요 특징

### 1. **그래프 기반 워크플로우**
- 애플리케이션의 흐름을 노드(node)와 엣지(edge)로 구성된 그래프로 표현
- 각 노드는 특정 작업이나 함수를 나타내고, 엣지는 실행 흐름을 정의

### 2. **상태 관리(Stateful)**
- 대화나 작업의 상태를 지속적으로 관리
- 이전 상호작용의 컨텍스트를 유지하면서 복잡한 다단계 작업 처리

### 3. **순환 구조 지원**
- 일반적인 DAG(방향성 비순환 그래프)와 달리 **순환(cycle)**을 허용
- 에이전트가 이전 단계로 돌아가거나 반복 작업을 수행할 수 있음

### 4. **체크포인트와 시간 여행**
- 워크플로우의 특정 시점을 저장하고 복원 가능
- 디버깅이나 오류 복구에 유용

## 주요 사용 사례

- **복잡한 AI 에이전트**: 다양한 도구를 사용하는 자율 에이전트
- **멀티 에이전트 시스템**: 여러 에이전트가 협업하는 시스템
- **대화형 애플리케이션**: 복잡한 대화 흐름을 가진 챗봇
- **워크플로우 자동화**: 조건부 분기와 루프가 있는 작업 자동화

## 기본 구조 예시

```python
from langgraph.graph import StateGraph

# 그래프 정의
workflow = StateGraph(State)

# 노드 추가
workflow.add_node("agent", agent_function)
workflow.add_node("tool", tool_function)

# 엣지 추가 (흐름 정의)
workflow.add_edge("agent", "tool")
workflow.add_conditional_edges("tool", should_continue)

# 컴파일
app = workflow.compile()
```

LangGraph는 특히 **복잡한 의사결정 로직**이 필요하거나, **여러 단계를 거쳐야 하는 AI 애플리케이션**을 구축할 때 매우 유용합니다.

더 자세한 정보가 필요하시거나 특정 사용 예시를 알고 싶으시다면 말씀해 주세요!