새벽에 서비스가 멈춘 원인을 찾는 일을 Agent에게 시켰다고 해 봅니다. 로그를 읽고 변경 이력을 보고 원인을 정리하려면 몇십 번 도구를 부르게 되고 그때마다 결과가 대화에 쌓입니다. 모델이 한 번에 읽는 범위인 컨텍스트 창(context window)은 한정되어 있어서 결과가 쌓이면 처음 계획을 잊거나 창이 가득 찹니다.
Deep Agents는 이런 긴 일에 쓰려고 계획표, 파일함, 하위 일꾼, 스킬을 처음부터 갖춘 Agent입니다. 아래에서 일반 Agent와 Deep Agent가 같은 일을 할 때 창이 어떻게 달라지는지 보세요.
설명을 위한 예시 장면입니다. 칩의 크기는 차지하는 공간을 대략 나타낸 것이고 실제 토큰 수가 아닙니다.
긴 일을 시작할 때 Agent는 write_todos 도구로 할 일 목록을 적습니다. 각 항목에는 대기(pending), 진행 중(in_progress), 완료(completed) 중 하나의 상태가 붙습니다. 목록은 State의 todos 칸에 저장되고 일이 끝날 때마다 고쳐집니다.
대화가 길어져 처음 지시가 멀리 밀려나도 계획표는 State에 남아 있습니다. 그래서 지금 어디까지 했고 무엇이 남았는지 다시 확인할 수 있습니다. Deep Agents 0.7부터 이 도구는 기본으로 꺼져 있어서 TodoListMiddleware를 넣어야 합니다.
Deep Agent는 파일을 다루는 도구를 기본으로 갖고 있습니다. 목록 보기(ls), 읽기(read_file), 쓰기(write_file), 고치기(edit_file), 지우기(delete), 이름으로 찾기(glob), 내용으로 찾기(grep)입니다. 직접 실행해 보니 이 일곱 가지가 기본 목록에 들어 있었습니다.
기본 설정에서 파일은 State의 files 칸에 저장됩니다. 로그 3천 줄 같은 큰 결과를 대화에 그대로 두는 대신 파일에 적고 경로만 들고 있으면 창이 가벼워집니다. 필요할 때 grep이나 read_file로 다시 꺼내 읽습니다.
task 도구는 하위 Agent를 하나 만들어 일을 맡기고 보고서 하나만 돌려받습니다. 하위 Agent가 읽은 자료와 중간 과정은 그 안에 남으니 주 Agent의 창은 깨끗합니다. 앞에서 본 Subagent 방식을 Deep Agents가 기본으로 넣어 둔 것입니다.
하위 Agent는 기본으로 격리(isolated) 모드라 새 창에서 시작합니다. 복제(fork) 모드로 바꾸면 주 Agent의 대화 기록을 물려받습니다. 어떤 정보를 넘길지에 따라 고릅니다.
스킬(skill)은 특정 일을 하는 방법을 적어 둔 폴더입니다. 폴더 안의 SKILL.md 파일 맨 위에 이름과 설명을 적고 그 아래에 자세한 절차를 씁니다. 지식을 전부 프롬프트에 넣으면 창이 무거워지므로 필요한 만큼만 단계적으로 읽습니다. 이를 단계적 공개(progressive disclosure)라고 합니다.
시작할 때는 스킬의 이름과 설명만 시스템 프롬프트에 들어갑니다. 일이 스킬과 맞으면 그제야 read_file로 본문을 읽습니다. 본문이 가리키는 참고 파일은 더 필요할 때 읽습니다. 단계를 눌러 보세요.
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from langchain.agents.middleware import TodoListMiddleware
agent = create_deep_agent(
model=model,
system_prompt="장애 조사 담당이다. 긴 내용은 파일에 적는다.",
middleware=[TodoListMiddleware()], # 1 계획 도구 켜기
backend=StateBackend(), skills=["/skills/"], # 2 스킬 폴더 지정
)
r = agent.invoke({"messages": [...], "files": {...}}) # 3 스킬 파일을 State로 넘김
print(r["todos"], list(r["files"]))출력은 예시입니다. deepagents 0.7.26을 모의 서버에 붙여 도구 목록과 State 칸을 직접 확인했습니다. files 칸에 넘기는 값은 create_file_data()로 만드는데 여기서는 생략했습니다.
create_deep_agent는 파일 도구와 task 도구를 기본으로 갖습니다. write_todos는 TodoListMiddleware를 넣어야 생깁니다.skills에는 스킬 폴더들이 모인 상위 폴더 경로를 줍니다. 기본 저장소(StateBackend)를 쓰면 파일이 State 안에 있습니다.files 칸에 /skills/incident-triage/SKILL.md 같은 파일을 담아 보냅니다. 이름은 폴더 이름과 같아야 하고 설명은 1,024자 안으로 씁니다.다음 글에서는 Agent가 쓰는 도구를 표준 방식으로 이어 주는 MCP가 무엇인지 알아보겠습니다.