Deep Agent

깃허브: https://github.com/langchain-ai/deepagents

개요

에이전트는 점점 더 긴 작업(long-horizon task)을 처리할 수 있게 되었으며, 에이전트 작업 길이는 7개월마다 2배씩 증가하고 있습니다! 그러나 긴 작업은 종종 수십 번의 도구 호출을 포함하며, 이는 비용과 신뢰성 측면에서 과제를 제시합니다. Claude Code와 Manus와 같은 인기 있는 에이전트들은 이러한 과제를 해결하기 위해 몇 가지 공통 원칙을 사용하는데, 여기에는 planning(계획) (작업 실행 전), computer access(컴퓨터 접근) (에이전트에게 셸과 파일시스템 접근 권한 부여), sub-agent delegation(하위 에이전트 위임) (격리된 작업 실행)이 포함됩니다. deepagents는 이러한 도구들을 구현하는 간단한 에이전트 하네스(harness)로, 오픈 소스이며 사용자 정의 도구와 명령어로 쉽게 확장할 수 있습니다.

📚 리소스

문서 - 전체 개요 및 API 참조
빠른 시작 저장소 - 예제 및 사용 사례
CLI - 스킬, 메모리, HITL 워크플로우를 갖춘 대화형 명령줄 인터페이스

🚀 빠른 시작

deepagents에 사용자 정의 도구를 제공할 수 있습니다. 아래에서는 웹 검색을 위한 tavily 도구를 선택적으로 제공합니다. 이 도구는 deepagents의 내장 도구에 추가됩니다(아래 참조).

pip install deepagents tavily-python

환경에 TAVILY_API_KEY를 설정하세요(여기서 받기):

import os
from deepagents import create_deep_agent
 
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
 
def internet_search(query: str, max_results: int = 5):
    """Run a web search"""
    return tavily_client.search(query, max_results=max_results)
 
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="Conduct research and write a polished report.",
)
 
result = agent.invoke({"messages": [{"role": "user", "content": "What is LangGraph?"}]})

create_deep_agent로 생성된 에이전트는 컴파일된 LangGraph StateGraph이므로, 다른 LangGraph 에이전트처럼 스트리밍(streaming), human-in-the-loop(인간 개입), 메모리(memory), Studio(스튜디오)와 함께 사용할 수 있습니다. 더 많은 예제는 빠른 시작 저장소를 참조하세요.

Deep Agent 커스터마이징

create_deep_agent에 전달할 수 있는 여러 매개변수가 있습니다.

`model`

기본적으로 deepagents는 "claude-sonnet-4-5-20250929"를 사용합니다. 이것은 LangChain 모델 객체를 전달하여 사용자 정의할 수 있습니다.

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

`system_prompt`

create_deep_agent()에 system_prompt 매개변수를 제공할 수 있습니다. 이 사용자 정의 프롬프트(prompt)는 미들웨어(middleware)에 의해 자동으로 주입되는 기본 명령어에 추가됩니다.

사용자 정의 시스템 프롬프트를 작성할 때 다음을 수행해야 합니다:

✅ 도메인별 워크플로우 정의 (예: 연구 방법론, 데이터 분석 단계)
✅ 사용 사례에 대한 구체적인 예제 제공
✅ 특화된 가이드 추가 (예: “유사한 연구 작업을 단일 TODO로 일괄 처리”)
✅ 중지 기준 및 리소스 제한 정의
✅ 워크플로우에서 도구가 함께 작동하는 방식 설명

하지 말아야 할 것:

❌ 표준 도구의 기능을 다시 설명 (이미 미들웨어에서 다룸)
❌ 도구 사용에 대한 미들웨어 명령어 중복
❌ 기본 명령어와 충돌 (이에 대항하지 말고 함께 작업)

from deepagents import create_deep_agent
research_instructions = """your custom system prompt"""
agent = create_deep_agent(
    system_prompt=research_instructions,
)

더 많은 예제는 빠른 시작 저장소를 참조하세요.

`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])

langchain-mcp-adapters를 통해 MCP 도구를 연결할 수도 있습니다:

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent
 
async def main():
    mcp_client = MultiServerMCPClient(...)
    mcp_tools = await mcp_client.get_tools()
    agent = create_deep_agent(tools=mcp_tools)
 
    async for chunk in agent.astream({"messages": [{"role": "user", "content": "..."}]}):
        chunk["messages"][-1].pretty_print()

`middleware`

Deep Agent는 확장성을 위해 미들웨어를 사용합니다(기본값은 내장 도구 참조). 도구를 주입하거나, 프롬프트를 수정하거나, 에이전트 수명 주기에 연결하기 위해 사용자 정의 미들웨어를 추가하세요:

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()])

`subagents`

메인 에이전트는 task 도구를 통해 하위 에이전트(sub-agent)에게 작업을 위임할 수 있습니다(내장 도구 참조). 컨텍스트 격리와 사용자 정의 명령어를 위해 사용자 정의 하위 에이전트를 제공할 수 있습니다:

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],
    "model": "openai:gpt-4o",  # Optional, defaults to main agent model
}
 
agent = create_deep_agent(subagents=[research_subagent])

복잡한 경우, 미리 구축된 LangGraph 그래프를 전달하세요:

from deepagents import CompiledSubAgent, create_deep_agent
 
custom_graph = create_agent(model=..., tools=..., prompt=...)
 
agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="data-analyzer",
        description="Specialized agent for data analysis",
        runnable=custom_graph
    )]
)

자세한 내용은 하위 에이전트 문서를 참조하세요.

`interrupt_on`

일부 도구는 민감할 수 있으며 실행 전에 사람의 승인이 필요할 수 있습니다. Deep Agent는 LangGraph의 인터럽트(interrupt) 기능을 통해 human-in-the-loop 워크플로우를 지원합니다. 체크포인터(checkpointer)를 사용하여 승인이 필요한 도구를 구성할 수 있습니다.

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

from langchain_core.tools import tool
from deepagents import create_deep_agent
 
@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."
 
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[get_weather],
    interrupt_on={
        "get_weather": {
            "allowed_decisions": ["approve", "edit", "reject"]
        },
    }
)

자세한 내용은 human-in-the-loop 문서를 참조하세요.

`backend`

Deep Agent는 플러그형 백엔드(backend)를 사용하여 파일시스템 작업이 작동하는 방식을 제어합니다. 기본적으로 파일은 에이전트의 임시 상태(ephemeral state)에 저장됩니다. 로컬 디스크 접근, 대화 간 지속적인 저장소(persistent storage) 또는 하이브리드 라우팅을 위해 다른 백엔드를 구성할 수 있습니다.

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
 
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/path/to/project"),
)

사용 가능한 백엔드는 다음과 같습니다:

StateBackend (기본값): 에이전트 상태에 저장되는 임시 파일
FilesystemBackend: 루트 디렉토리 아래의 실제 디스크 작업
StoreBackend: LangGraph Store를 사용한 지속적인 저장소
CompositeBackend: 다른 경로를 다른 백엔드로 라우팅

자세한 내용은 백엔드 문서를 참조하세요.

장기 메모리(Long-term Memory)

Deep Agent는 CompositeBackend를 사용하여 대화 간에 지속적인 메모리를 유지할 수 있으며, 이는 특정 경로를 영구 저장소로 라우팅합니다.

이를 통해 작업 파일은 임시로 유지되지만 중요한 데이터(예: 사용자 기본 설정 또는 지식 베이스)는 스레드 간에 지속되는 하이브리드 메모리가 가능합니다.

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
 
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={"/memories/": StoreBackend(store=InMemoryStore())},
    ),
)

/memories/ 아래의 파일은 모든 대화에 걸쳐 지속되고, 다른 경로는 임시로 유지됩니다. 사용 사례는 다음과 같습니다:

세션 간 사용자 기본 설정 보존
여러 대화에서 지식 베이스 구축
피드백을 기반으로 자체 개선되는 명령어
세션 간 연구 진행 상황 유지

자세한 내용은 장기 메모리 문서를 참조하세요.

내장 도구

create_deep_agent로 생성된 모든 Deep Agent에는 표준 도구 세트가 함께 제공됩니다:

도구 이름	설명	제공자
`write_todos`	복잡한 워크플로우를 통한 진행 상황을 추적하기 위해 구조화된 작업 목록 생성 및 관리	TodoListMiddleware
`read_todos`	현재 할 일 목록 상태 읽기	TodoListMiddleware
`ls`	디렉토리의 모든 파일 나열 (절대 경로 필요)	FilesystemMiddleware
`read_file`	선택적 페이지네이션(offset/limit 매개변수)을 사용하여 파일에서 콘텐츠 읽기	FilesystemMiddleware
`write_file`	새 파일 생성 또는 기존 파일 완전히 덮어쓰기	FilesystemMiddleware
`edit_file`	파일에서 정확한 문자열 교체 수행	FilesystemMiddleware
`glob`	패턴과 일치하는 파일 찾기 (예: `*/.py`)	FilesystemMiddleware
`grep`	파일 내에서 텍스트 패턴 검색	FilesystemMiddleware
`execute`*	샌드박스 환경에서 셸 명령 실행	FilesystemMiddleware
`task`	격리된 컨텍스트 윈도우를 가진 특화된 하위 에이전트에게 작업 위임	SubAgentMiddleware

execute 도구는 백엔드가 SandboxBackendProtocol을 구현하는 경우에만 사용할 수 있습니다. 기본적으로 명령 실행을 지원하지 않는 인메모리 상태 백엔드를 사용합니다. 표시된 대로, 이러한 도구(및 기타 기능)는 기본 미들웨어에서 제공됩니다:

내장 도구 및 기능에 대한 자세한 내용은 에이전트 하네스 문서를 참조하세요.

내장 미들웨어

deepagents는 내부적으로 미들웨어를 사용합니다. 다음은 사용되는 미들웨어 목록입니다.

미들웨어	목적
TodoListMiddleware	작업 계획 및 진행 상황 추적
FilesystemMiddleware	파일 작업 및 컨텍스트 오프로딩 (큰 결과 자동 저장)
SubAgentMiddleware	격리된 하위 에이전트에게 작업 위임
SummarizationMiddleware	컨텍스트가 170k 토큰을 초과하면 자동 요약
AnthropicPromptCachingMiddleware	비용 절감을 위해 시스템 프롬프트 캐시 (Anthropic만 해당)
PatchToolCallsMiddleware	인터럽트로 인한 미완료 도구 호출 수정
HumanInTheLoopMiddleware	사람의 승인을 위해 실행 일시 중지 (`interrupt_on` 구성 필요)

내장 프롬프트

미들웨어는 표준 도구에 대한 명령어를 자동으로 추가합니다. 사용자 정의 명령어는 이러한 기본값을 중복하지 않고 보완해야 합니다:

TodoListMiddleware에서

write_todos와 read_todos 사용 시기 설명
작업 완료 표시 지침
할 일 목록 관리 모범 사례
할 일을 사용하지 말아야 할 때 (간단한 작업)

FilesystemMiddleware에서

모든 파일시스템 도구 나열 (ls, read_file, write_file, edit_file, glob, grep, execute*)
파일 경로가 /로 시작해야 함을 설명
각 도구의 목적과 매개변수 설명
큰 도구 결과에 대한 컨텍스트 오프로딩 관련 참고 사항

SubAgentMiddleware에서

하위 에이전트에게 위임하기 위한 task() 도구 설명
하위 에이전트를 사용할 때와 사용하지 말아야 할 때
병렬 실행 지침
하위 에이전트 수명 주기 (생성 → 실행 → 반환 → 조정)

Jeongsk

탐색기