[Agent] LangChain deepagents SDK 0.7 업데이트 정리
Introduction
deepagents는 LangChain이 만든 에이전트 하네스(harness) 다. 모델과 도구를 직접 엮어 루프를 짜는 대신, 서브에이전트·파일시스템·컨텍스트 관리처럼 “깊게 파고드는 에이전트”에 반복적으로 필요한 요소를 기본값으로 제공한다. LangGraph 위에 얹혀 있고, Claude Code 류의 코딩 에이전트가 쓰는 구조를 라이브러리로 떼어낸 형태에 가깝다.
uv add deepagents
# 또는
pip install deepagents
from deepagents import create_deep_agent
agent = create_deep_agent(
model="anthropic:claude-sonnet-5",
tools=[my_custom_tool],
system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})
버전이 빠르게 올라가는 중이라 현재 상황을 한 번 정리해 둔다. 기준 시점은 2026년 8월이고, PyPI 최신 버전은 0.7.8(2026-08-20)이다.
| 버전 | 시점 | 성격 |
|---|---|---|
| 0.6 | 2026-05 | 기능 확장 (코드 인터프리터, 델타 채널, ContextHub) |
| 0.7 | 2026-07-29 | 다이어트 + breaking change |
| 0.7.x | 2026-08 | 백엔드·요약 동작 다듬기 |
0.6에서 들어온 것들
0.7을 이해하려면 0.6에서 깔린 판을 먼저 봐야 한다. 0.6의 주제는 한 마디로 성능이었고, 서로 다른 계층에서 각각 비용을 깎는 기능이 한꺼번에 들어왔다.
Code Interpreter
에이전트가 도구를 하나씩 호출하는 대신 코드를 써서 의도를 표현하고, 인메모리 런타임(QuickJS)이 그것을 실행한 뒤 결과만 돌려주는 방식이다. 흔히 PTC(programmatic tool calling)라고 부른다.
from deepagents import create_deep_agent
from langchain_quickjs import REPLMiddleware
agent = create_deep_agent(
model="baseten:zai-org/GLM-5",
middleware=[REPLMiddleware()],
)
핵심은 중간 결과가 모델 컨텍스트로 올라오지 않고 런타임에 머문다는 점이다. 서브에이전트를 여러 개 돌리고 그 출력을 합치는 작업이 특히 이득을 본다.
const topics = ["retrieval", "memory", "evaluation"];
const reports = await Promise.all(
topics.map((topic) =>
tools.task({
description: `Research ${topic} in Deep Agents and return three concise findings.`,
subagent_type: "general-purpose",
}),
),
);
reports.join("\n\n");
세 개의 리서치 결과 전문이 모델 컨텍스트를 거치지 않고, 합쳐진 문자열만 최종적으로 돌아온다.
Harness Profiles
기본 시스템 프롬프트, 도구 설명, 턴을 구성하는 미들웨어를 모델별로 이름과 버전이 붙은 단위로 묶은 것이다. 같은 하네스라도 모델마다 잘 먹는 프롬프트가 다르다는 관찰에서 나왔다. LangChain이 공개한 수치로는 Terminal-Bench 2.0에서 gpt-5.2-codex가 52.8% → 66.5%로 올랐고, opus-4.7은 약 10% 개선됐다. 오픈 웨이트 모델을 튜닝된 프로필로 돌려 비용을 크게 낮추는 것이 원래 의도다.
Streaming v3
메시지, 추론 블록, 도구 호출, 상태 업데이트, 서브그래프, 커스텀 채널을 타입이 붙은 하나의 이벤트 스트림으로 통합했다. UI 쪽에서 청크 종류를 추측할 필요가 없어진다.
stream = agent.stream_events(
{"messages": [{"role": "user", "content": "Research LangChain streaming"}]},
version="v3",
)
for message in stream.messages:
for delta in message.text:
print(delta, end="", flush=True)
for subagent in stream.subagents:
print(f"\n[{subagent.name}] {subagent.status}")
로컬 스트림과 원격 스트림이 같은 프로토콜을 따르고, @langchain/react 등 프론트엔드 패키지도 여기에 맞춰 v1이 나왔다.
Delta Channels
체크포인트를 매 스텝 전체 스냅샷으로 저장하면 저장량이 턴 수의 제곱으로 늘어난다. 델타 채널은 각 스텝에서 바뀐 부분만 저장해 이걸 선형으로 만든다. 200턴짜리 멀티파일 코딩 세션 기준으로 5.27 GB → 129 MB, 약 40배 차이가 난다고 보고됐다. 장시간 도는 에이전트에서는 DB 쓰기 병목까지 같이 줄어든다.
ContextHub
LangSmith 기반 파일시스템 백엔드다. 프롬프트나 스킬 파일을 버전 관리되는 저장소에 두고, 실행 사이에 그 개선분이 남게 한다.
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, ContextHubBackend
agent = create_deep_agent(
model="google_genai:gemini-3.1-pro-preview",
backend=CompositeBackend(
default=StateBackend(),
routes={
"/memories/": ContextHubBackend("my-agent"),
},
),
)
전체를 ContextHub로 쓰기 부담스러우면 위처럼 /memories/ 경로만 라우팅하는 방식이 무난하다. LANGSMITH_API_KEY가 필요하다.
0.7: 기본값을 덜어내다
0.6이 기능을 더한 릴리스였다면, 0.7은 기본값을 걷어낸 릴리스다. 방향이 정반대라서 흥미롭다.
입력 토큰 65% 감소
아무것도 하지 않은 기본 에이전트의 한 턴에서 입력 토큰이 약 5,400~6,000에서 약 1,900~2,000으로 줄었다. 세 가지가 겹친 결과다.
- 기본 시스템 프롬프트 제거
- 내장 도구 설명 43% 축소
TodoListMiddleware기본 탑재 중단
품질이 같이 떨어지지 않았다는 점이 중요한데, gpt-5.6-luna 기준 평가에서 토큰 34% 감소·비용 15% 절감에 보상은 오히려 4% 올랐다고 한다. 기본 프롬프트가 실제로는 성능에 기여하지 못하면서 토큰만 먹고 있었다는 뜻이다.
계획(todo) 도구가 opt-in으로
가장 눈에 띄는 breaking change다. create_deep_agent가 더 이상 TodoListMiddleware를 자동으로 넣지 않는다. 따라서 write_todos 도구, todos 상태 채널, 계획 프롬프트가 모두 사라진다.
# v0.6: 자동 포함
agent = create_deep_agent(model="anthropic:claude-sonnet-5")
# v0.7: 필요하면 직접 넣는다
from deepagents.middleware import TodoListMiddleware
agent = create_deep_agent(
model="anthropic:claude-sonnet-5",
middleware=[TodoListMiddleware()],
)
서브에이전트에서도 쓰려면 각 SubAgent의 middleware에 따로 추가해야 한다. 제거 근거는 평가에서 계획 프롬프트와 write_todos가 유의미한 성능 향상을 만들지 못했다는 것이었다. 사람 눈에 진행 상황이 보이는 UX 가치는 별개이니, 그 목적으로 쓰고 있었다면 그대로 명시해서 유지하면 된다.
미들웨어 오버라이드
같은 .name을 가진 미들웨어를 넘기면 기본 미들웨어를 교체한다. 이전에는 내장 요약 설정을 바꾸기가 번거로웠다.
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",
trigger=("fraction", 0.5),
summary_prompt="Summarize the conversation so far...",
),
],
)
요약만 값싼 모델로 돌리는 구성이 이제 한 블록으로 끝난다.
파일시스템 도구 정리
write_file이 기존 파일 덮어쓰기를 지원한다.read_file이 페이지네이션 시 남은 라인 수를 알려준다.grep/glob이 큰 디렉터리에서 부분 결과를 돌려주고truncated플래그를 붙인다.delete도구가 기본 파일시스템 도구 목록에 들어왔다.- 빈
ls/glob결과가"[]"에서"No files found"로 바뀌었다.
마지막 항목은 출력 문자열을 파싱하던 코드가 있으면 조용히 깨지는 부분이라 확인이 필요하다.
백엔드 호환 shim 제거
0.5에서 deprecated 됐던 BackendFactory, BACKEND_TYPES, FileFormat, Unset이 삭제됐다. 이제 구체 인스턴스를 직접 넘기고 namespace도 명시해야 한다.
backend = StoreBackend(namespace=lambda rt: (rt.server_info.user.identity,))
그 밖에 BASE_AGENT_PROMPT가 최상위 export에서 빠졌고, Bedrock·Fireworks 프롬프트 캐싱과 NVIDIA Nemotron 3 Ultra 프로필 지원이 추가됐다.
0.7.x 패치
8월 들어 나온 패치들은 대체로 백엔드 쪽을 다듬는 내용이다.
- 0.7.6: 대화 이력을 요약할 때 별도 세션 ID로 오프로드
- 0.7.7:
ContextHubBackend변경을 배치로 묶어 동시 처리,BackendProtocol.glob이 단순 패턴에 대해 재귀 동작 - 0.7.8:
files상태를 state 백엔드에서만 생성
특히 0.7.8은 원격/샌드박스 백엔드를 쓸 때 불필요하게 커지던 상태를 줄여주는 변경이라, 체크포인트 크기가 신경 쓰였다면 올릴 값어치가 있다.
마이그레이션 체크리스트
0.6.x에서 올라온다면 이 순서로 확인하면 된다.
write_todos도구나todos상태를 참조하는 코드가 있는가 →TodoListMiddleware()를 main agent와 각 SubAgent에 명시적으로 추가BackendFactory등 shim을 쓰고 있는가 → 구체 백엔드 인스턴스 + 명시적 namespace로 교체BASE_AGENT_PROMPT를 import 하는가 → 자체 프롬프트 상수로 대체ls/glob출력 문자열을 파싱하는가 →"No files found"케이스 처리- 기본 시스템 프롬프트에 의존한 동작이 있는가 →
system_prompt로 필요한 내용만 직접 지정
uv pip install -U deepagents
# TypeScript
npm install deepagents@latest
정리
0.6은 코드 인터프리터·델타 채널·ContextHub로 긴 실행을 감당할 수 있게 만들었고, 0.7은 기본 프롬프트와 계획 도구를 덜어내 짧은 실행을 싸게 만들었다. 평가로 검증되지 않은 기본값은 걷어낸다는 태도가 릴리스 노트 전반에 깔려 있는데, 하네스를 직접 만들 때도 참고할 만한 기준이라고 본다.
버전이 0.x대라 마이너 릴리스에도 breaking change가 들어온다. 프로덕션에서 쓴다면 버전을 고정해두고 changelog를 확인한 뒤 올리는 편이 안전하다.