DeepAgents 아키텍처 해설: 계획 도구, 서브 에이전트와 파일 시스템

당신의 AI Agent는 왜 복잡한 작업에서 늘 무너질까요?

기술 주제를 조사하게 하면 20단계쯤 지나 출력 품질이 떨어지기 시작합니다. 코드베이스를 리팩터링하게 하면 한참 수정한 뒤 원래 기능까지 망가뜨립니다. 긴 보고서를 쓰게 하면 중간부터 같은 말을 반복합니다.

저도 예전에 이 함정을 밟았습니다. 그때는 전통적인 Agent로 깊이 있는 리서치를 하면서 LangGraph의 모범 사례를 조사하게 했습니다. 초반 출력은 꽤 체계적이었지만 30단계를 넘기자 Agent가 “기억상실”을 보이기 시작했습니다. 앞에서 찾은 자료를 잊고, 원래의 분석 틀도 흐트러졌고, 마지막 보고서는 여기저기 조각을 붙인 듯 앞뒤가 맞지 않았습니다.

이 문제들의 뿌리는 같습니다. 전통적인 Agent는 “Shallow”하다는 점입니다. 단일 단계의 반응형 실행만 할 수 있고, 계획 능력도, 기억 시스템도, 하위 작업 분해도 없습니다. 5000자짜리 보고서를 쓰라고 하면서 개요를 주지 않는 것과 비슷합니다. 중간에 방향이 틀어지는 것이 당연합니다.

그런데 Claude Code, Deep Research, Manus 같은 Agent는 복잡한 작업을 해냅니다. 수천 줄 코드의 프로젝트 리팩터링, 수십 페이지짜리 심층 리서치 보고서도 처리합니다. 이들은 어떤 방법을 쓸까요?

답은 Deep Agent 아키텍처입니다. LangChain은 이 아키텍처를 DeepAgents 패키지로 공식화했습니다. 오늘은 이 구조의 네 가지 핵심 축인 계획 도구, 서브 에이전트, 파일 시스템, 시스템 프롬프트를 뜯어보겠습니다.

왜 Deep Agents가 필요할까요?

먼저 사실 하나부터 보겠습니다. 전통적인 Agent는 10단계를 넘는 작업에서 성공률이 절반 이상 떨어집니다.

근거 없는 말이 아닙니다. Prompting Guide의 연구 데이터에 따르면 작업 단계가 10개를 넘으면 Shallow Agent의 출력 품질은 눈에 띄게 하락하기 시작합니다. 왜 그럴까요? “생각을 유지하는 구조”가 없기 때문입니다.

전통적인 Agent 설계는 반응형입니다. 지시를 받으면 도구를 호출하고 결과를 반환합니다. 각 단계는 독립적이며 장기 계획도, 중간 상태 관리도 없습니다. 비유하자면 집 전체를 청소하라고 하면서 청소 순서도 알려 주지 않고, 어떤 방을 이미 청소했는지도 기록하지 못하게 하는 셈입니다. 주방을 반쯤 청소하다가 갑자기 거실로 가고, 다시 주방이 아직 끝나지 않았다는 사실을 잊을 수 있습니다.

가장 전형적인 붕괴 장면은 세 가지입니다.

심층 리서치 작업. Agent에게 “프로덕션 환경에서 LangGraph의 모범 사례” 같은 기술 주제를 조사하게 합니다. Agent는 검색하고, 문서를 읽고, 정보를 추출합니다. 20단계가 지나면 이미 확인한 자료가 Context Window 밖으로 밀려나고, 새로운 검색 결과가 이전의 분석 틀을 덮어씁니다. 마지막에는 앞뒤가 맞지 않는 보고서가 나옵니다.

코드 리팩터링 작업. Agent에게 수천 줄짜리 프로젝트를 리팩터링하게 합니다. 한 모듈을 고치고, 또 다른 모듈을 고치지만 두 모듈 사이의 의존 관계를 잊어버립니다. 마지막에는 원래 잘 돌아가던 기능이 모두 깨집니다.

긴 콘텐츠 생성. Agent에게 5000자짜리 기술 글을 쓰게 합니다. 2000자쯤 쓰면 앞에서 했던 말을 반복하거나 원래 주제에서 벗어나기 시작합니다.

이 문제의 핵심은 Context 통제 실패입니다.

Claude Code는 수천 줄 코드의 프로젝트 리팩터링을 처리할 수 있고, Deep Research는 수십 페이지짜리 구조화된 보고서를 만들 수 있으며, Manus는 복잡한 다단계 작업을 수행할 수 있습니다. 이것은 마법이 아니라 하나의 공통 구조를 쓴 결과입니다. 바로 Deep Agent 아키텍처입니다.

Deep Agent는 Agent에게 “머리”를 붙이는 일입니다. 계획하고, 작업을 나누고, 기억을 관리하고, 진행 상황을 점검하게 만드는 구조입니다. LangChain은 이 아키텍처를 DeepAgents로 패키징했습니다. 구체적인 설계를 살펴보겠습니다.

DeepAgents의 네 가지 핵심 아키텍처

DeepAgents의 설계 철학은 명확합니다. 복잡한 작업을 관리 가능한 단위로 나누고, 각 단위에 명확한 책임을 부여합니다.

네 가지 축은 서로 맞물려 작동합니다. Planning Tools는 계획과 진행 추적을 맡고, Sub-agents는 전문 분업과 Context 격리를 구현하며, File System은 기억 저장 문제를 해결하고, System Prompts는 행동 경계를 정의합니다. 오케스트라에 비유하면 지휘자(Planning), 서로 다른 악기 파트(Sub-agents), 악보 저장소(File System), 연주 규칙(System Prompts)이 함께 움직이는 구조입니다.

Planning Tools: Agent에게 “머리”를 붙이다

Planning Tools의 핵심은 todo_write입니다.

작동 방식이 흥미롭습니다. 본질적으로는 no-op, 즉 아무 실제 작업도 하지 않는 빈 동작입니다. 실제 작업을 수행하지 않고 작업 목록을 만들고 갱신할 뿐입니다. 하지만 이 작업 목록은 Context Window를 통해 working memory로 작동하기 때문에 Agent는 전체 실행 과정에서 자신의 계획과 진행 상황을 계속 “볼” 수 있습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

예를 들어 Agent에게 기술 리서치를 맡긴다고 해 보겠습니다. Agent는 먼저 todo_write로 다음 계획을 만듭니다.

- [ ] LangGraph 공식 문서 검색
- [ ] LangGraph State Machine 설계 읽기
- [ ] 모범 사례 추출
- [ ] 핵심 설계 패턴 정리
- [ ] 구조화된 보고서 출력

작업 하나를 끝낼 때마다 Agent는 이 목록을 갱신하고 [ ]를 [x]로 바꿉니다. 이렇게 하면 몇 단계를 실행하든 Agent가 언제든 자신의 진행 상태를 확인할 수 있습니다. 무엇을 끝냈는지, 무엇을 아직 시작하지 않았는지, 무엇을 진행 중인지가 계속 보입니다.

이것이 해결하는 핵심 문제는 장기 목표 일관성입니다.

전통적인 Agent는 20단계쯤 실행하면 1단계에서 정한 목표가 무엇이었는지 잊을 수 있습니다. 하지만 Deep Agent의 todo list는 냉장고에 붙여 둔 메모처럼 “도대체 무엇을 하려는지” 계속 상기시킵니다.

"Claude Code와 Manus의 planning tool도 같은 원리입니다. Context Window를 working memory로 사용해 Agent가 방향을 잃지 않게 합니다."

Sub-agents: 전문 분업과 Context 격리

Sub-agents는 Deep Agent의 두 번째 핵심 축입니다.

설계 논리는 이렇습니다. 하나의 주 오케스트레이터(Orchestrator)가 전체 계획과 작업 배분을 담당하고, 여러 전문 서브 에이전트가 구체적인 작업을 실행합니다. 각 서브 에이전트는 독립적인 Context Window를 가지며, 실행이 끝난 뒤 최종 결과만 오케스트레이터에게 반환합니다.

이 구조는 네 가지 중요한 장점을 가져옵니다.

Context Preservation. 오케스트레이터의 Context Window가 서브 에이전트의 중간 단계로 오염되지 않습니다. 전통적인 Agent가 검색 작업을 수행할 때는 모든 검색 결과, 웹페이지 내용, 추출 과정이 Context에 들어갑니다. 하지만 Sub-agent가 실행을 마치면 “이런 핵심 정보를 찾았습니다”라는 깨끗한 결과만 반환합니다. 오케스트레이터의 Context는 가볍게 유지됩니다.

Specialized Expertise. 각 서브 에이전트는 한 영역에 집중할 수 있습니다. research_subagent는 정보 검색과 추출을, writer_subagent는 콘텐츠 구성을, coder_subagent는 코드 분석을 전담합니다. 전문 분업은 각 서브 에이전트가 자기 영역에서 더 좋은 결과를 내게 합니다.

Reusability. 같은 서브 에이전트를 여러 오케스트레이터가 호출할 수 있습니다. 예를 들어 research_subagent는 조사 작업, 글쓰기 작업, 분석 작업에서 모두 사용할 수 있습니다. 한 번 만들면 여러 곳에서 재사용할 수 있습니다.

Fine-Grained Permissions. 서브 에이전트마다 서로 다른 권한 경계를 줄 수 있습니다. 어떤 서브 에이전트는 파일 읽기만 가능하고, 어떤 서브 에이전트는 파일 쓰기가 가능하며, 어떤 서브 에이전트는 네트워크 접근이 가능합니다. 세밀한 권한 제어는 보안 위험을 낮춥니다.

"Orchestrator-Sub-agent 아키텍처를 권장합니다. 이는 Task Decomposition Pattern이라고도 하며, 복잡한 작업을 하위 작업으로 나누고 각 하위 작업을 전문 처리 단위에 맡기는 방식입니다."

구체적으로 어떻게 구현할까요? DeepAgents는 간단한 API를 제공합니다.

from deepagents import create_deep_agent, create_subagent

# 서브 에이전트 정의
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="정보 검색과 추출을 전담"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="콘텐츠 구성과 출력을 전담"
)

# 주 Agent 생성
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

오케스트레이터가 서브 에이전트를 호출하면 DeepAgents가 Context 전환과 결과 전달을 자동으로 처리합니다.

File System: Context Window 제한을 넘어서다

이것은 Deep Agent가 기억 문제를 해결하는 핵심 방법입니다.

Context Window에는 크기 제한이 있습니다. Claude는 대략 200K tokens, GPT-4는 약 128K tokens입니다. 짧은 작업에는 충분합니다. 하지만 긴 작업, 예를 들어 수천 줄의 코드를 처리하거나 수십 편의 문서를 읽는 경우에는 이 공간이 금방 가득 찹니다.

File System Backend의 해결 방식은 영리합니다. 직접 로딩 대신 파일 참조를 사용합니다.

Agent는 모든 내용을 Context Window에 밀어 넣지 않습니다. 대신 중간 결과를 파일 시스템에 저장합니다. 특정 파일이 필요할 때만 read_file 도구로 필요한 만큼 읽습니다. 연구를 할 때 모든 참고문헌을 머릿속에 외우지 않고 문서로 정리해 두었다가 필요할 때 열어 보는 것과 같습니다.

DeepAgents는 세 가지 Backend를 지원합니다.

StateBackend. 메모리 저장 방식으로 테스트 환경과 단기 작업에 적합합니다. Agent의 상태와 중간 결과가 메모리에 저장되며 세션이 끝나면 사라집니다. 빠르지만 지속성이 없습니다.

FilesystemBackend. 로컬 파일 시스템 저장 방식으로 프로덕션 환경과 지속성이 필요한 상황에 적합합니다. Agent의 중간 결과가 로컬 파일에 기록되므로 다음 실행에서도 읽을 수 있습니다. 지속적이지만 로컬 저장소에 의존합니다.

StoreBackend. 클라우드 저장 방식으로 엔터프라이즈급 배포와 감사 추적이 필요한 상황에 적합합니다. Agent의 상태가 클라우드 데이터베이스에 저장되며 버전 관리와 감사 로그를 지원합니다. 안정적이지만 설정이 복잡합니다.

어떤 Backend를 선택할지는 상황에 따라 다릅니다. 빠른 테스트라면 StateBackend, 프로덕션 배포라면 FilesystemBackend, 감사가 필요한 엔터프라이즈 애플리케이션이라면 StoreBackend를 사용하면 됩니다.

FlowHunt의 Context Management Strategy 비교 표는 이 세 가지 방식을 명확하게 설명합니다.

DeepAgents는 기본적으로 Hybrid 방식을 사용합니다. 핵심 정보는 Context에 유지하고, 대량의 데이터는 파일 시스템에 저장합니다.

System Prompts: 과소평가되는 핵심

System Prompts는 네 가지 핵심 축 중 가장 쉽게 간과되는 요소입니다.

많은 사람은 System Prompt를 “당신은 유용한 도우미입니다” 같은 간단한 지시문 정도로 생각합니다. 하지만 Deep Agent의 System Prompts는 실제로 수백 줄에서 수천 줄에 이르는 엔지니어링 문서입니다.

Claude Code의 System Prompt는 수백 줄이며, 완전한 도구 호출 규칙, 파일 작업 절차, 코드 스타일 제약을 정의합니다. Deep Research의 System Prompt는 천 줄이 넘고, 연구 방법론, 정보 추출 규칙, 출력 형식 템플릿까지 포함합니다.

왜 이렇게 상세한 System Prompt가 필요할까요?

Agent는 긴 작업에서 여러 경계 상황을 만납니다. 짧은 지시만으로는 모든 상황을 덮을 수 없습니다. 상세한 System Prompt의 역할은 다음과 같습니다.

행동 경계 정의. 어떤 상황에서 todo_write를 호출해야 하는지, 어떤 상황에서 sub-agent에게 넘겨야 하는지, 어떤 상황에서 바로 결과를 반환해야 하는지 정합니다. 이런 규칙이 충분히 자세해야 Agent가 올바르게 판단할 수 있습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

도구 호출 규격화. 각 도구를 어떻게 쓰는지, 매개변수 형식은 무엇인지, 반환 결과를 어떻게 처리하는지 정합니다. 예를 들어 read_file 도구의 매개변수가 파일 경로인지 파일 ID인지, 반환값이 원문인지 요약인지가 명확해야 합니다.

출력 형식 설정. 작업 유형마다 출력 형식 요구사항이 다릅니다. 연구 보고서는 Markdown 구조를 쓰고, 코드 리팩터링은 diff 형식을 쓰며, 콘텐츠 생성은 특정 템플릿을 사용할 수 있습니다.

DeepAgents의 Middleware Architecture는 System Prompts를 자동으로 주입합니다. 직접 수천 줄을 쓸 필요는 없습니다. 프레임워크가 설정에 따라 자동으로 생성합니다. 하지만 System Prompts의 역할을 이해하는 것은 중요합니다. 이것은 Agent 행동의 “헌법”입니다.

네 가지 핵심 축을 모두 살펴봤습니다. 이제 실전 코드를 보겠습니다.

DeepAgents 실전 코드 해설

기술 리서치 Agent를 구현하는 완전한 코드 예시를 보겠습니다.

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. 도구 정의
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="인터넷을 검색해 정보를 가져옵니다"
)

# 2. 서브 에이전트 정의
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="당신은 정보 검색 전문가입니다.\
                   당신의 작업은 핵심 정보를 검색하고 추출하는 것입니다.\
                   중간 단계는 포함하지 말고 구조화된 연구 결과만 반환하세요.",
    description="정보 검색을 담당하는 서브 에이전트"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],  # writer는 외부 도구가 필요 없습니다
    system_prompt="당신은 콘텐츠 구성 전문가입니다.\
                   당신의 작업은 연구 결과를 정리해 구조화된 보고서를 출력하는 것입니다.\
                   Markdown 형식을 사용하고 명확한 섹션 구조를 포함하세요.",
    description="콘텐츠 출력을 담당하는 서브 에이전트"
)

# 3. Deep Agent 생성
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"  # 파일 시스템 저장 사용
)

# 4. 작업 실행
result = agent.invoke(
    "LangGraph의 모범 사례를 조사하고\
     구조화된 연구 보고서를 출력하세요"
)

실행 흐름은 다음과 같습니다.

첫 번째 단계: Plan. Agent가 todo_write를 호출해 계획 목록을 만듭니다.

todo_write([
    "LangGraph 공식 문서 검색",
    "핵심 아키텍처 설계 읽기",
    "모범 사례 추출",
    "설계 패턴 정리",
    "구조화된 보고서 출력"
])

두 번째 단계: Delegate. Agent가 research_subagent를 호출해 검색 작업을 실행합니다.

call_subagent("research", "LangGraph 모범 사례 관련 문서 검색")

research_subagent는 internet_search 도구를 호출해 검색 결과를 얻고, 핵심 정보를 추출한 뒤 깨끗한 구조화 결과만 오케스트레이터에게 반환합니다. 오케스트레이터의 Context Window에는 모든 검색 결과 원문이 아니라 “여기에서 5개의 핵심 모범 사례를 찾았습니다” 같은 요약만 들어갑니다.

세 번째 단계: Update. Agent가 todo list를 갱신하고 완료 상태를 표시합니다.

todo_write([
    "[x] LangGraph 공식 문서 검색",
    "[x] 핵심 아키텍처 설계 읽기",
    "[ ] 모범 사례 추출",
    ...
])

네 번째 단계: 계속 실행. Agent가 writer_subagent를 호출해 콘텐츠를 구성하고, write_file로 최종 보고서를 출력합니다.

call_subagent("writer", "연구 결과를 정리해 보고서 출력")
write_file("langgraph_best_practices.md", report_content)

실행 로그는 다음처럼 보입니다.

[Step 1] todo_write: 작업 항목 5개 생성
[Step 2] call_subagent(research): 정보 검색 시작
[Step 3] internet_search: "LangGraph best practices" 검색
[Step 4] read_url: 공식 문서 3편 읽기
[Step 5] subagent_complete: research가 구조화 결과 반환
[Step 6] todo_write: 진행 상황 갱신, 2개 완료
[Step 7] call_subagent(writer): 콘텐츠 구성 시작
[Step 8] subagent_complete: writer가 Markdown 보고서 반환
[Step 9] write_file: 보고서를 파일로 출력
[Step 10] todo_write: 모든 작업 완료

전체 흐름에서 오케스트레이터의 Context Window는 항상 깨끗하게 유지됩니다. 작업 목록과 서브 에이전트가 반환한 요약 결과만 있고, 중간 단계의 잡음은 없습니다.

이것이 Deep Agent의 힘입니다. 구조화된 프로세스, Context 관리, 전문 분업입니다.

다른 Agent 프레임워크와의 비교

DeepAgents만이 유일한 선택지는 아닙니다. 시장에는 LangGraph, AutoGen, CrewAI, SmolAgents 같은 프레임워크도 있습니다. 각자 초점이 다르고 적합한 상황도 다릅니다.

한 표로 정리하면 다음과 같습니다.

몇 가지 핵심 차이를 보겠습니다.

DeepAgents vs LangGraph. DeepAgents는 LangGraph 위의 상위 래퍼이며 Deep Agent 패턴에 집중합니다. Planning Tools, File System Backend, Sub-agent Management 같은 공통 기능을 미리 감싸 두었으므로 직접 구축할 필요가 없습니다. LangGraph는 더 저수준이며 상태 머신과 워크플로 오케스트레이션 기능을 제공합니다. 각 노드와 엣지를 자유롭게 정의할 수 있지만 Memory와 Planning은 직접 구현해야 합니다.

간단히 말해 Deep Agent를 빠르게 만들고 싶다면 DeepAgents를 쓰고, 저수준 커스터마이징이 필요하다면 LangGraph를 쓰면 됩니다.

DeepAgents vs AutoGen. AutoGen은 Microsoft의 프레임워크이며 다중 에이전트 대화와 Pipeline 오케스트레이션을 지원합니다. 특징은 에이전트끼리 서로 대화하면서 토론, 협상 같은 복잡한 상호작용 패턴을 만들 수 있다는 점입니다. DeepAgents는 작업 분해와 실행에 더 가깝고, AutoGen은 에이전트 협업과 커뮤니케이션에 더 가깝습니다.

간단히 말해 에이전트 팀의 협업, 토론, 협상을 만들고 싶다면 AutoGen을 쓰고, 작업 분해와 전문 분업을 만들고 싶다면 DeepAgents를 쓰면 됩니다.

DeepAgents vs CrewAI. CrewAI는 “역할 수행”을 강조합니다. 각 에이전트는 연구원, 편집자, 프로그래머처럼 서로 다른 역할을 갖고 협업해 작업을 완수합니다. DeepAgents의 Sub-agent 패턴과 비슷하지만 CrewAI는 역할의 페르소나와 상호작용을 더 강조하고, DeepAgents는 작업 분해와 격리를 더 강조합니다.

간단히 말해 팀 협업과 역할 수행을 시뮬레이션하고 싶다면 CrewAI를 쓰고, 기술적인 작업 분해를 하고 싶다면 DeepAgents를 쓰면 됩니다.

DeepAgents vs SmolAgents. SmolAgents는 Hugging Face가 만든 경량 프레임워크로, 코드 우선이 특징입니다. Agent가 도구를 호출하는 대신 Python 코드를 직접 작성해 작업을 실행합니다. 빠른 프로토타입 개발에는 적합하지만 복잡하고 긴 작업에는 적합하지 않습니다.

간단히 말해 단순한 Agent를 빠르게 시험해 보고 싶다면 SmolAgents를 쓰고, 복잡한 장기 작업을 처리하고 싶다면 DeepAgents를 쓰면 됩니다.

"프레임워크 선택은 상황에 따라 달라야 합니다. DeepAgents는 복잡한 추론 작업 처리에 적합하고, LangGraph는 프로덕션급 시스템에 적합하며, AutoGen과 CrewAI는 다중 에이전트 협업에, SmolAgents는 빠른 아이디어 검증에 적합합니다. 만능 프레임워크는 없고, 상황에 맞는 프레임워크만 있습니다."

프로덕션 배포와 모범 사례

DeepAgents를 프로덕션 환경에서 사용할 때는 몇 가지 핵심 포인트에 주의해야 합니다.

Backend 선택 전략

세 가지 Backend의 선택 논리는 다음과 같습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

StateBackend: 테스트 환경과 단기 작업. 장점은 빠르다는 점입니다. 모든 데이터가 메모리에 있으므로 읽기와 쓰기에 IO 지연이 없습니다. 단점은 지속성이 없다는 점입니다. Agent를 재시작하면 상태가 모두 사라집니다. 단위 테스트, 빠른 검증, 단기 작업에 적합합니다.

FilesystemBackend: 프로덕션 환경과 지속성 요구. 장점은 안정적이라는 점입니다. 데이터가 파일 시스템에 기록되므로 재시작 후에도 읽을 수 있습니다. 단점은 IO 비용이 있다는 점입니다. 파일 읽기와 쓰기는 메모리보다 느립니다. 프로덕션 배포, 긴 작업, 지속성이 필요한 경우에 적합합니다.

StoreBackend: 엔터프라이즈급 환경과 감사 추적 요구. 장점은 통제 가능하다는 점입니다. 데이터가 클라우드 데이터베이스에 저장되고 버전 관리와 감사 로그를 지원합니다. 단점은 복잡하다는 점입니다. 데이터베이스 연결과 권한 관리를 설정해야 합니다. 엔터프라이즈 애플리케이션, 컴플라이언스 요구, 감사 요구에 적합합니다.

설정 예시는 다음과 같습니다.

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",  # 저장 경로
        max_file_size=10 * 1024 * 1024,  # 단일 파일 최대 10MB
        cleanup_after_days=30  # 30일 후 오래된 파일 정리
    )
)

서브 에이전트 입도 설계

과도하게 쪼개지 마세요.

어떤 사람은 조사 작업 하나를 10개의 서브 에이전트로 나눴습니다. search_google, search_bing, read_wikipedia, read_github, extract_summary, extract_quotes, format_markdown, check_citations 등입니다. 결과적으로 오케스트레이터가 서브 에이전트를 호출하는 시간이 실제 작업 실행 시간보다 더 길어졌습니다.

합리적인 설계는 3-5개의 핵심 서브 에이전트입니다.

• research: 모든 정보 검색과 추출 담당
• analysis: 데이터 처리와 논리 추론 담당
• writer: 콘텐츠 구성과 출력 담당
• reviewer: 품질 검사와 검증 담당(선택 사항)

각 서브 에이전트에는 명확한 책임 경계가 있어야 합니다. research 서브 에이전트가 콘텐츠 구성을 해서는 안 되고, writer 서브 에이전트가 정보 검색을 해서는 안 됩니다. 책임이 분명해야 호출도 명확해집니다.

성능 최적화

핵심은 두 가지입니다.

파일을 필요할 때만 읽기. 모든 중간 결과를 한 번에 read_file하지 마세요. Agent는 실행 과정에서 현재 작업에 필요한 관련 파일만 읽어야 합니다. DeepAgents의 파일 참조 메커니즘은 바로 이를 위해 설계되었습니다. 파일 경로는 Context에 저장하고, 내용은 필요할 때만 로드합니다.

Context Summarization의 적절한 사용. 긴 작업을 실행하다 보면 Context Window에 많은 내용이 쌓일 수 있습니다. DeepAgents는 중간 단계의 자동 요약을 지원합니다. 길어진 실행 기록을 짧은 상태 설명으로 압축합니다. 이는 Context 공간을 절약하지만 요약의 정확성에 주의해야 합니다. 핵심 정보가 빠지면 안 됩니다.

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,  # 50K tokens에서 요약 트리거
        "preserve_last_n_steps": 5  # 최근 5단계의 상세 기록 보존
    }
)

오류 처리와 검증

Deep Agents는 실행 과정이 길기 때문에 오류 가능성도 큽니다. 오류 처리 메커니즘이 필요합니다.

LLM-as-a-Judge. 다른 LLM을 사용해 Agent의 출력 품질을 검사합니다. 예를 들어 reviewer_subagent가 writer_subagent가 출력한 보고서에 논리적 허점이나 정보 누락이 있는지 확인합니다.

사람이 개입하는 지점. 핵심 의사결정 지점에 사람의 확인을 둡니다. 예를 들어 Agent가 조사를 마친 뒤 잠시 멈추고 사용자에게 방향이 맞는지 확인받은 다음 계속 실행합니다.

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,  # 자동 검증 활성화
        "human_checkpoint": "before_output"  # 출력 전 사람 확인
    }
)

정리

DeepAgents의 네 가지 핵심 축을 다시 정리해 보겠습니다.

Planning Tools는 Agent에게 계획 능력을 줍니다. todo_write는 Context Window를 working memory로 사용해 장기 목표 일관성을 유지합니다.

Sub-agents는 전문 분업과 Context 격리를 구현합니다. 오케스트레이터의 Context는 깨끗하게 유지되고, 서브 에이전트의 중간 단계는 주 흐름을 오염시키지 않습니다.

File System은 Context Window 제한을 해결합니다. 직접 로딩 대신 파일 참조를 사용하고, 필요할 때만 읽어 공간을 절약합니다.

System Prompts는 Agent의 행동 경계를 정의합니다. 수백 줄에서 수천 줄에 이르는 엔지니어링 문서가 다양한 경계 상황을 덮습니다.

이 네 가지 축은 함께 작동하며 Agent를 “반응형 실행”에서 “구조화된 추론”으로 진화시킵니다. Claude Code, Deep Research, Manus의 성공은 이 아키텍처의 유효성을 증명합니다.

다음 단계로 해볼 만한 일은 다음과 같습니다.

• DeepAgents로 첫 번째 장기 작업 Agent를 만들어 보세요. 공식 GitHub 저장소 langchain-ai/deepagents에 완전한 예제 코드가 있습니다.
• LangChain 공식 문서를 읽고 더 깊이 학습해 보세요. DeepAgents 문서는 docs.langchain.com/oss/python/deepagents에 있습니다.
• AI 개발 실전 시리즈를 계속 지켜보세요. 앞으로 LangGraph 상태 머신 설계, Agent Memory 시스템 최적화 등 Agent 아키텍처에 대한 더 깊은 분석이 이어질 예정입니다.