LangChain의 deepagents는 긴 작업을 단순 ReAct 반복에 맡기지 않고 TODO 계획, 파일 형태의 중간 상태와 서브에이전트 위임으로 나누는 에이전트 하네스입니다. 이 구조는 진행 상황과 문맥을 관리하는 데 도움을 줄 수 있지만 잘못된 계획과 하위 결과도 체계적으로 확대할 수 있습니다. 도입 판단은 기능 이름보다 상태를 복구하고 권한, 비용, 완료 조건을 강제할 수 있는지에 달려 있습니다.
LangChain deepagents는 긴 작업을 어떻게 관리하나: 계획, 파일, 위임의 한계
deepagents는 어떤 문제를 풀려 하나
짧은 도구 호출은 현재 메시지와 최근 결과만으로 이어 갈 수 있습니다. 수십 개 파일을 조사하고 여러 결과를 합쳐야 하는 작업은 초기에 세운 목표, 완료한 단계와 중간 자료를 오랫동안 유지해야 합니다. 모든 내용을 대화에 계속 붙이면 컨텍스트가 커지고 중요한 요구가 묻힐 수 있습니다.
deepagents 저장소는 계획, 파일과 위임을 기본 구조로 제공해 이런 상태를 메시지 밖에서도 다루려 합니다. 프레임워크가 상태를 제공한다고 모델의 판단력이 자동으로 높아지는 것은 아닙니다. 상태의 정확성과 검증 규칙을 함께 설계해야 합니다.
TODO 계획은 어떻게 진행을 드러내나
에이전트가 큰 목표를 작은 항목으로 나누고 각 항목의 상태를 갱신하면 현재 진행과 남은 일을 확인하기 쉽습니다. 작업 중 요구가 바뀌거나 장애가 생겼을 때 계획을 다시 조정할 수 있습니다. 완료 문구 하나보다 어떤 단계를 어떤 근거로 끝냈는지 보는 편이 감사하기 좋습니다.
문제는 첫 분해가 틀릴 수 있다는 점입니다. 핵심 선행 조건을 빠뜨리거나 서로 의존하는 일을 병렬로 놓으면 뒤의 실행이 모두 잘못될 수 있습니다. 계획을 실행하기 전에 수정 대상, 위험한 행동, 검증 단계와 완료 조건을 사람이 검토하거나 결정론적 규칙으로 검사할 수 있어야 합니다.
TODO가 너무 세밀하면 상태 갱신 호출과 토큰이 늘고, 너무 크면 진행을 판단하기 어렵습니다. 산출물 하나와 검증 하나가 연결되는 단위를 기준으로 시작하고 실제 실패에 따라 조정하는 편이 좋습니다.
가상 파일 시스템은 컨텍스트를 어떻게 바꾸나
긴 문서, 조사 메모와 중간 산출물을 메시지에 전부 남기는 대신 파일로 저장하고 필요할 때 읽을 수 있습니다. 파일명과 작은 인덱스를 사용하면 현재 단계에 필요한 자료만 문맥으로 가져올 수 있습니다. 이는 무한 메모리가 아니라 컨텍스트를 외부 상태로 옮겨 선택적으로 읽는 방식입니다.
잘못된 파일명, 오래된 요약과 중복 산출물이 쌓이면 모델이 엉뚱한 근거를 읽을 수 있습니다. 파일에 출처, 작성 단계, 버전과 유효 기간을 남기고 최종 결론에서 사용한 파일을 추적해야 합니다. 중요한 사용자 요구는 중간 파일로만 옮겨 원래 목표에서 사라지지 않게 합니다.
가상 파일과 실제 저장소 파일도 구분해야 합니다. 대화 상태를 되돌려도 이미 실제 코드나 외부 시스템에 적용한 변경은 남을 수 있습니다. 실제 변경은 Git, worktree, 트랜잭션과 별도 복구 절차로 관리합니다.
서브에이전트는 무엇을 격리하나
메인 에이전트가 작은 조사나 특정 파일 검토를 하위 에이전트에 맡기면 모든 도구 설명과 세부 로그가 메인 컨텍스트를 차지하지 않을 수 있습니다. 역할과 입력이 분명한 독립 작업을 병렬로 실행할 수도 있습니다. 이를 문맥 격리의 이점으로 볼 수 있습니다.
그러나 하위 에이전트가 원래 목표와 보안 조건을 모두 알고 있다는 보장은 없습니다. 위임에는 담당 질문, 읽을 수 있는 경로, 허용 도구, 금지 행동, 완료 조건과 반환 형식을 포함해야 합니다. 하위 답은 사실, 근거, 불확실성을 함께 반환하고 메인 에이전트가 실제 파일과 테스트로 확인합니다.
같은 파일을 두 하위 작업이 수정하거나 한 작업의 결과가 다른 작업의 입력인 경우에는 무작정 병렬화하지 않습니다. 작업 소유권과 합치는 순서를 정하고 충돌을 사람에게 보여 줍니다. 위임은 실행을 나눌 뿐 최종 검증 책임을 없애지 않습니다.
시스템 프롬프트는 왜 코드처럼 관리해야 하나
deepagents의 동작 규칙은 TODO를 언제 만들고 파일과 위임 도구를 어떻게 사용할지 모델에 알려 줍니다. 이런 지침은 자연어지만 실행 흐름에 영향을 주므로 코드와 비슷하게 버전, 리뷰와 회귀 테스트가 필요합니다. 예시 하나가 특정 작업에는 맞고 다른 작업에서는 과도한 행동을 유도할 수 있습니다.
프롬프트 변경 전후에 같은 작업 세트를 실행해 계획 누락, 도구 선택, 비용과 완료 품질을 비교합니다. 규칙이 서로 충돌하거나 오래된 API를 참조하면 모델이 올바른 계획을 세워도 실행이 실패합니다. 숨겨진 문맥과 프로젝트 지침, 작업별 요청의 우선순위도 명시해야 합니다.
최소 실행 예시는 무엇을 보여 주나
기존 글의 예시는 모델과 시스템 프롬프트를 전달해 deep agent를 만들고 메시지를 호출하는 형태였습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model
# Sonnet 3.5 모델과 딥 에이전트 생성
model = init_chat_model("anthropic:claude-3-5-sonnet")
agent = create_deep_agent(
model=model,
system_prompt="당신은 시니어 백엔드 마이그레이션 전문가입니다. 코드를 분석하고 점진적으로 리팩토링하세요."
)
result = agent.invoke({
"messages": [{"role": "user", "content": "/legacy_repo 폴더를 분석하고 마이그레이션을 시작해."}]
})
이 코드는 구조를 설명하는 시점별 스냅샷이지 완전한 마이그레이션 절차가 아닙니다. 현재 패키지, 모델 ID와 인증, 실제 파일 backend, 샌드박스, 쓰기 권한, 테스트와 중단 조건이 빠져 있습니다. PyPI 페이지와 저장소의 현재 문서에서 API를 확인해야 합니다.
특히 /legacy_repo가 실제로 어떻게 노출되고 어떤 파일을 바꿀 수 있는지는 런타임 설정에 달려 있습니다. 예제의 짧은 system prompt는 요구 분석과 안전 규칙을 대신하지 않습니다.
상태 체크포인트와 복구에는 무엇이 필요한가
장기 실행은 모델 오류, 네트워크와 프로세스 중단을 만나므로 TODO, 가상 파일, 실제 변경과 하위 작업 상태를 일관되게 저장해야 합니다. 다시 시작할 때 완료된 도구 호출을 중복 실행하거나 외부 쓰기를 반복하지 않도록 합니다. 체크포인트의 모델, 프롬프트, 도구 버전도 함께 남깁니다.
복구 시험은 정상 실행 중간을 의도적으로 중단하고 다시 시작해 봅니다. 실제 저장소와 가상 상태가 어긋나면 작업을 자동 계속하지 않고 사람에게 차이를 보여 줍니다. 오래된 체크포인트와 다른 프로젝트 상태를 잘못 연결하지 않도록 실행 ID와 작업 공간을 분리합니다.
토큰과 지연은 어디에서 늘어나나
계획 작성과 갱신, 파일 읽기, 서브에이전트, 결과 합성마다 모델 호출이 생길 수 있습니다. 병렬화는 벽시계 시간을 줄여도 총토큰과 외부 도구 부하는 늘릴 수 있습니다. 작업당 모델 호출, 읽은 파일, 하위 작업, 재시도와 총 시간을 단계별로 기록합니다.
모든 작은 작업에 deepagents 구조가 필요한 것은 아닙니다. 한두 파일 수정은 단순 에이전트가 더 싸고 예측 가능할 수 있습니다. 긴 조사와 독립 하위 작업이 있는 경우에만 계획, 파일, 위임의 추가 비용이 오류 감소를 정당화하는지 비교합니다.
최대 단계, 시간, 비용, 하위 작업 수와 동일 오류 반복에 상한을 둡니다. 중단할 때는 마지막 상태와 남은 TODO, 사람이 결정해야 할 내용을 요약합니다. 저렴한 모델로 무한 반복하는 것은 비용 통제가 아닙니다.
권한과 샌드박스는 어디서 강제할까
가상 파일 도구와 실제 코드 실행 도구의 권한을 구분합니다. 읽기 전용 조사에는 쓰기, 네트워크를 주지 않고 실제 패치는 복구 가능한 worktree에서 수행합니다. 패키지 설치, 삭제, Git 원격과 외부 시스템 변경은 사람 승인을 유지합니다.
하위 에이전트에도 메인보다 넓은 자격 증명을 주지 않습니다. 도구 결과와 외부 문서는 신뢰할 수 없는 입력으로 취급하고 프롬프트 인젝션이 계획과 TODO를 바꾸지 않는지 시험합니다. 정책은 자연어 지침뿐 아니라 컨테이너, 파일 경로와 자격 증명에서 강제해야 합니다.
작은 PoC는 어떤 업무로 시작할까
결과를 테스트로 판정할 수 있고 외부 부작용이 없는 중간 규모 작업을 고릅니다. 예를 들어 여러 파일의 API 사용처 조사와 마이그레이션 계획 생성은 파일, 위임 구조를 시험하면서 실제 배포 권한은 주지 않을 수 있습니다. 사람이 만든 정답 범위와 요구 누락을 기준선으로 둡니다.
단순 에이전트와 deepagents를 같은 입력, 모델, 예산으로 비교해 성공률, 근거, 사람 개입, 토큰과 시간을 기록합니다. 하위 결과 오류와 상태 복구, 중단도 평가합니다. 구조가 더 복잡하다는 사실이 아니라 긴 작업의 재작업과 문맥 손실을 실제로 줄였을 때 채택할 가치가 있습니다.
함께 읽으면 이해가 이어지는 글
- Composio는 에이전트 인증을 얼마나 줄여 주나: 권한과 실행 검증 — AI 에이전트 개발의 가장 큰 장벽인 ‘인증(Auth)’과 ‘도구 연동(Integration)’을 한 번에 해결해주는 Composio를 상세히 분석합니다. LangChain, AutoGen 등 주요 프레임워크와의 연동법과 실전…
- 에이전트가 스스로 협업한다는 말의 실제 구조: 계획, 도구, 기억, 승인 — Agentic workflow를 Profile, Memory, Planning, Tools와 피드백 루프로 나누고, 멀티에이전트가 필요한 조건과 재시도, 비용, 비결정성 통제법을 설명합니다.
- Hermes Agent는 무엇을 기억하고 실행하나: 영구 메모리, 스킬, 권한 검증법 — Hermes Agent의 세션 간 메모리, 스킬 생성, Gateway, 서브에이전트 구조를 살펴보고 오염된 기억, 권한, 비용, 복구를 검증하는 기준을 정리합니다.
자주 묻는 질문
deepagents를 쓰면 에이전트가 긴 작업에서 길을 잃지 않나요?
보장되지 않습니다. TODO와 파일은 상태를 드러내지만 첫 계획이 틀리거나 오래된 중간 산출물을 읽으면 오류가 여러 하위 작업으로 전파될 수 있습니다.
가상 파일 시스템은 컨텍스트 제한을 없애나요?
아닙니다. 모든 내용을 메시지에 두지 않게 돕지만 필요한 파일을 정확히 찾아 읽고 요약해야 하며 저장, 검색, 권한, 복구 비용이 남습니다.
서브에이전트 위임은 언제 유용한가요?
입력과 결과가 명확하고 서로 독립적인 조사, 검사에 유용할 수 있습니다. 같은 파일이나 외부 상태를 바꾸는 작업은 충돌과 검증 책임을 별도로 관리해야 합니다.
표지 1 —
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.