Deep Agents v0.7

https://www.langchain.com/blog/deep-agents-v0-7

오늘 deep agents v0.7을 출시합니다. 이번 릴리스는 기본 하네스를 단순화해, 성능은 비슷하게 유지하면서 기본 입력 토큰을 65% 줄였습니다.

효과적인 에이전트를 만드는 일은 결국 컨텍스트 엔지니어링으로 귀결됩니다. 모델의 능력은 주어진 컨텍스트만큼만 발휘되고, 그 컨텍스트는 결국 프롬프트에 무엇이 들어 있느냐로 결정됩니다. 그 프롬프트를 잘 조립하는 것이 하네스의 역할입니다. 하지만 이를 어떻게 해야 하는지에 대한 지침은 끊임없이 바뀝니다. OpenAI, Anthropic, Google이 각자 프롬프팅 가이드를 발행하는데, 셋 모두 모델이 더 강력해지면서 가이드를 다시 썼습니다. 하네스도 그 속도를 따라가야 합니다. 그러지 않으면 모델이 이미 벗어난 낡은 프롬프팅을 계속 지고 가게 됩니다.

Anthropic은 최근 최신 모델을 위한 컨텍스트 엔지니어링 가이드를 새로 발행하면서, Opus 5나 Fable 5 같은 모델에서는 Claude Code 시스템 프롬프트의 80% 이상을 잘라냈는데도 코딩 평가에서 측정 가능한 성능 하락이 없었다는 결과를 함께 공개했습니다. 그중 몇 가지 발견은 우리가 v0.7을 만들며 확인한 것과 일치합니다.

예시보다 인터페이스: 잘 만든 도구 스키마가 한때 유행했던 퓨샷(few-shot) 예시보다 사용법을 더 잘 가르칩니다. 퓨샷 예시는 모델의 탐색 폭을 좁힐 수 있습니다.
반복 금지: 같은 지시를 시스템 프롬프트와 도구 설명 양쪽에 반복해도 의미 있는 강화 효과가 없습니다.

Deep Agents v0.7은 더 가볍고 설정 자유도가 높으며, 토큰과 비용 효율도 더 좋은 기본 하네스를 제공합니다.

더 가벼워진 기본 하네스

우리의 가설은 이랬습니다. 기본 입력 프롬프트에서 불필요한 토큰을 덜어내면 성능은 그대로 유지하면서 토큰과 비용 효율을 높일 수 있다는 것입니다. 이를 검증하기 위해 세 가지를 바꿨습니다.

기본 시스템 프롬프트 제거: Deep Agents가 내부적으로 사용하던 시스템 프롬프트를 제거했습니다. 여기에는 일반 지침과 도구 사용법 설명문이 들어 있었습니다 (#4859).
도구 설명 축소: 내장 도구 설명을 43% 줄였습니다 (#5009).
todo는 옵트인으로: create_deep_agent가 더 이상 TodoListMiddleware를 기본으로 포함하지 않습니다. 평가 결과 계획 수립 프롬프트와 write_todos 도구가 성능을 유의미하게 개선하지 못하는 것으로 나타났습니다 (#4929).

이 변경들을 합치면 기본 에이전트 턴의 기본 입력 토큰*이 65% 줄어듭니다(약 6,000개에서 약 2,000개로).

* 기본 입력 토큰: 내장 프롬프트, 도구, 미들웨어에 들어가는 토큰

변경을 검증한 방법

성능이 떨어지지 않았다는 것은 세 가지 벤치마크 범주로 구성한 새 평가 스위트로 검증했습니다. 각 범주는 서로 다른 종류의 에이전트 작업을 겨냥합니다.

자율(Autonomous): 코딩, 데이터 분석 같은 엔드투엔드 작업
대화(Conversational): 시뮬레이션된 사용자와의 멀티턴 대화
롱 컨텍스트(Long-context): 긴 컨텍스트에 대한 검색과 추론이 필요한 작업

새 v0.7 하네스를 기존 기준선(v0.6.12)과 비교해, 세 평가 범주 전체와 네 가지 모델(gpt-5.6-luna, gemini-3.6-flash, claude-sonnet-4-6, claude-opus-4-8)을 조합한 매트릭스로 실행했습니다.

보상(reward)은 전반적으로 그대로 유지되었고, 토큰과 비용은 대체로 줄었습니다*. 특히 gpt-5.6-luna는 토큰이 34%, 비용이 15% 줄면서 보상은 4% 올랐습니다. claude-sonnet-4-6은 예외였는데, LangSmith 트레이스를 분석해 보니 비용이 크게 늘어난 것은 대부분 난도 높은 자율 작업 두 건 때문이었습니다.

* 보상의 신뢰구간은 모든 모델에서 0을 포함합니다. Luna와 Opus는 통계적으로 뚜렷한 토큰 감소를 보였고, Luna는 비용 감소도 통계적으로 뚜렷했습니다. 전체 리포트는 여기에서 볼 수 있습니다.

자세한 내용은 Deep Agents 평가를 어떻게 운영하는지 다룬 최근 블로그 글을 참고하세요.

todo 리스트에 대한 참고 사항

TodoListMiddleware는 이제 옵트인입니다. 세 범주와 세 모델에 걸친 평가에서 todo를 끈 쪽이 보상은 약간 더 높고 비용은 더 낮았기 때문에, 기본 하네스에서 write_todos 도구를 제거했습니다. 변경 내용과 전체 실험 결과는 여기에서 볼 수 있습니다.

그래도 다음 몇 가지 경우에는 여전히 제 몫을 합니다.

길고 단계가 많은 작업: 여러 턴에 걸쳐 궤도를 유지하려면 명시적인 계획이 도움이 됩니다.
성능이 낮은 모델: 단계를 빠뜨리거나 흐름을 놓치지 않으려면 더 많은 발판이 필요합니다.
UI에 노출되는 사용 사례: 눈에 보이는 계획과 진행 상황이 실제 실행만큼 중요합니다.

위 세 경우에 해당한다면 다시 켜는 것은 한 줄이면 됩니다: middleware=[TodoListMiddleware()].

더 높아진 설정 자유도

설정 자유도는 지난 6개월 동안 Deep Agents 사용자들이 가장 많이 요청한 것이었습니다. FilesystemMiddleware를 오버라이드하고 싶다, SummarizationMiddleware 임계값을 조정하고 싶다, 기본 프롬프트를 전역으로 바꾸고 싶다는 요청이 있었습니다. 모두 같은 벽에 부딪혔습니다. 기본 하네스 스택의 동작을 바꿀 공식적인 방법이 없었던 것입니다. v0.7은 이를 두 가지 방식으로 해결합니다.

프롬프트에 대한 완전한 통제. 숨은 프롬프팅을 제거하면 부수 효과가 있습니다. 내부에 잘해야 비대화, 최악에는 충돌을 일으킬 수 있는 프롬프팅이 사라지므로, 직접 작성한 커스텀 프롬프팅이 더 효과적으로 작동합니다.

미들웨어 스택에 대한 완전한 통제. v0.7에서는 내장 미들웨어 오버라이드가 정식 기능이 되었습니다. .name이 기본 미들웨어와 같은 인스턴스를 middleware=로 전달하면, 중복 오류를 내는 대신 해당 기본 미들웨어를 그 자리에서 대체합니다. (#4251)

한 파워 유저는 이렇게 말했습니다.

"예전에는 기본 미들웨어 일부를 제거하려고 꼼수를 좀 썼습니다. 미들웨어 오버라이드는 정말 반가운 기능입니다."

SummarizationMiddleware가 좋은 예입니다. 기본 설정에서는 대화가 컨텍스트 윈도우의 85%를 넘으면 범용 요약 프롬프트로 요약이 시작됩니다. 하지만 애플리케이션마다 필요한 프롬프팅이 다르고, 개발자들은 컨텍스트 열화(context rot)와 "덤 존(dumb zone)"을 미리 피하기 위해 요약이 시작되는 임계값도 다르게 잡고 싶어 합니다. 이제 원하는 설정을 담은 요약 미들웨어를 직접 끼워 넣을 수 있습니다.

from deepagents import create_deep_agent
from deepagents.middleware import SummarizationMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    middleware=[
        SummarizationMiddleware(
            model="fireworks:accounts/fireworks/models/kimi-k3",
            # 기본값 대신 컨텍스트 윈도우의 50% 시점에 요약
            trigger=("fraction", 0.5),
            summary_prompt="Summarize the conversation so far, keeping any file paths and decisions verbatim...",
        ),
    ],
)

같은 패턴은 프롬프트 캐싱 TTL처럼 다시 조정하고 싶은 다른 내장 기본값에도 그대로 적용됩니다.

파일시스템 성능

파일시스템은 Deep Agents의 핵심 컨텍스트 관리 레이어로, 에이전트가 상태를 읽고 쓰고 탐색하는 환경입니다. 이번 릴리스에서는 같은 평가 스위트에 더해, 오픈 모델과 클로즈드 모델을 가리지 않고 실제 dcode 사용에서 확인한 궤적(trajectory) 최적화를 바탕으로 몇 가지 최적화를 진행했습니다.

write_file은 이제 기존 파일이 있으면 오류를 내는 대신 덮어씁니다 (#4109). 페이지네이션되는 read_file은 전체 줄 수와 남은 줄 수, 다음 offset을 알려 줍니다 (#4540). grep과 glob은 큰 트리에서 멈춰 있는 대신 truncated 플래그와 함께 부분 결과를 반환하며, grep에는 1,000개 매치 상한, 스트리밍 출력, 선택적 컨텍스트 줄 기능도 추가되었습니다 (#4063, #4570, #4706).

호환성이 깨지는 변경

이번 릴리스에서는 일부 호환성 심(shim)을 제거하고 몇 가지 기본 동작을 변경했습니다.

TodoListMiddleware가 더 이상 기본으로 켜져 있지 않습니다 (#4929). TodoListMiddleware()로 옵트인할 수 있습니다.
v0.5에서 사용 중단이 예고됐던 백엔드 팩토리 지원이 제거되고, 구체적인 BackendProtocol 인스턴스를 사용하는 방식으로 대체되었습니다 (#4541). v0.5에서 사용 중단이 예고된 파일 포맷과 백엔드 프로토콜 관련 다른 항목들도 함께 제거되었습니다.
기본 파일시스템 도구 목록에 delete 도구가 추가되었습니다. FilesystemMiddleware는 도구 허용 목록을 받으므로 원하지 않으면 제외할 수 있습니다 (#4325, #4698).

마이그레이션 안내와 코딩 에이전트용 "업그레이드" 프롬프트를 포함한 전체 내용은 체인지로그에 있습니다.

사용해 보기

deepagents v0.7이 PyPI에 공개되었습니다.

uv pip install -U deepagents

npm에서도 설치할 수 있습니다.

npm install deepagents@latest

최신 deepagents를 사용해 보고, GitHub 이슈, 포럼, X나 LinkedIn으로 의견을 들려주세요.