출처: Managed Deep Agents — LangChain 공식 문서 · 수집: 2026-08-15 10:49 KST
이 문서는 에이전트의 비즈니스 로직은 파일로 작성하고, 하네스·실행 환경·운영은 LangSmith에 맡기는 Managed Deep Agents(MDA)의 전체 그림을 설명한다.
개요
Managed Deep Agents는 에이전트를 디렉터리 구조로 정의한 뒤 LangSmith가 하네스와 운영 런타임을 실행하는 배포 모델이다. 개발자는 에이전트의 지능과 애플리케이션 로직에 집중하고, 서버 운영이나 런타임 인프라를 직접 연결하지 않아도 된다.
문서가 나누는 책임은 명확하다.
- 사용자가 제공: 지시문(instructions), 도구(tools), 스킬(skills), 모델(model), 애플리케이션별 로직
- MDA가 제공: 계획·도구 호출·파일시스템·서브에이전트를 포함한 Deep Agents harness와 Agent Server·sandbox·schedule을 포함한 managed runtime
프로젝트 디렉터리 = 에이전트 정의
MDA 프로젝트는 에이전트가 무엇을 하고 어떻게 운영되는지를 파일과 디렉터리로 표현한다. agent.py가 필수 진입점이며, 나머지는 필요한 기능만 추가한다.
| 구성요소 | 경로 | 역할 |
|---|---|---|
| 모델·설정 | agent.py | 모델과 핵심 옵션을 선언한다. 필수 파일이다. |
| 지시문 | instructions.md | 에이전트의 시스템 프롬프트와 행동 원칙을 정의한다. |
| 스킬 | skills/ | 관련 작업에서 불러오는 업무별 플레이북이다. |
| 도구 | tools/ | 애플리케이션 로직이나 외부 서비스를 호출하는 함수다. |
| MCP 커넥터 | connectors/ | 원격 MCP 서버가 제공하는 도구를 연결한다. |
| 미들웨어 | middleware/ | 모델 호출과 도구 호출 전후에 실행되는 사용자 로직이다. |
| 샌드박스 | sandbox/ | 에이전트가 작성한 코드의 실행에 쓰는 격리 파일시스템·셸이다. |
| 메모리 | memory.py | 스레드 사이에 유지되는 선호와 지식이다. |
| 신원 | identity.py | 멀티유저 배포에서 호출자별 private thread·memory·credential을 분리한다. |
| 채널 | channels/ | Slack 같은 메시징 서비스에서 실행을 시작하고 응답을 받는다. |
| 스케줄 | schedules/ | 관리형 cron으로 에이전트를 반복 실행한다. |
| 평가 | evals/ | Harbor 스타일 task로 에이전트를 테스트한다. |
공식 예시는 define_deep_agent에서 모델, 도구, middleware를 묶는 형태를 보여 준다. 즉 MDA 프로젝트의 핵심은 거대한 서버 애플리케이션보다 선언적 에이전트 진입점과 기능별 파일 경계에 있다.
실행 흐름
- 에이전트 프로젝트 폴더에
agent.py와 필요한 구성 파일을 만든다. - 모델·도구·middleware를
define_deep_agent로 연결하고, 지시문·스킬·메모리·채널·스케줄 등을 파일로 추가한다. mdaCLI로 프로젝트 폴더를 업로드한다.- LangSmith 관리 인프라에서 Deep Agents harness와 runtime이 에이전트를 실행한다.
- Quickstart와 Tutorial에서 첫 배포, 검색 도구, durable memory, daily schedule을 단계적으로 확장한다.
핵심 설계 포인트
하네스와 런타임을 애플리케이션 코드에서 분리
MDA는 에이전트의 업무 규칙과 실행 기반을 분리한다. 사용자는 무엇을 할지와 어떤 도구·스킬을 노출할지를 결정하고, Deep Agents harness는 계획·도구 호출·파일시스템·서브에이전트 실행을 담당한다. managed runtime은 Agent Server, sandbox, schedule 같은 운영 표면을 맡는다.
기능별 확장 지점이 파일 구조에 드러남
메모리, 호출자 신원, 메시징 채널, cron, 평가를 각각 별도 파일·디렉터리로 분리해 두면, 에이전트가 단순한 단일 프롬프트가 아니라 운영 가능한 구성요소의 묶음이라는 사실이 코드 구조에 반영된다. 특히 connectors/, middleware/, sandbox/는 외부 도구·정책·실행 환경을 교체할 수 있는 경계다.
“서버를 운영하지 않는다”는 책임의 이동
MDA는 서버와 인프라 배선 부담을 줄이지만, 도구가 허용하는 외부 효과, 샌드박스 범위, 호출자별 데이터 분리, 메모리 수명, 스케줄 중복 실행, 평가 기준까지 자동으로 결정해 주는 것은 아니다. 이 문서의 “간단함”은 운영 책임이 사라진다는 뜻보다, 책임의 중심이 인프라 구축에서 에이전트 구성·권한·품질 설계로 이동한다는 뜻으로 읽는 편이 정확하다.
llm-wiki 관점
MDA는 langchain-deep-agents가 제공하는 에이전트 하네스를 LangSmith의 관리형 실행면과 결합한 사례다. 2026-08-10-anthropic-managed-agents가 세션·하네스·샌드박스의 안정적인 인터페이스와 brain/hands 분리를 강조했다면, 이 문서는 그와 유사한 문제를 프로젝트 디렉터리와 관리형 런타임의 사용자 경험으로 번역한다.
따라서 이 페이지의 핵심 키워드는 “새 모델”보다 파일 기반 에이전트 정의 → 관리형 하네스 → 운영 런타임이라는 배포 경계다. 하네스 설계 관점은 moc-ai-agents-harness, 운영·채널·스케줄 관점은 moc-ai-agents-orchestration에서 함께 볼 수 있다.
출처와 범위
- 원문: Managed Deep Agents
- 관련 문서: Quickstart, Project structure, Tutorial
- 이 노트는 개요 페이지의 내용을 한국어로 재구성한 것이다. 가격, SLA, 리전, 세부 인증 정책, 운영 제한은 이 페이지 자체에서 확정하지 않았다.