Deep Agents 개요

from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "anthropic:claude-sonnet-4-6",
    HarnessProfile(
        excluded_tools=frozenset(
            {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep"}
        ),
    ),
)

excluded_middleware를 통한 FilesystemMiddleware 자체 제거는 의도적으로 거부됩니다—이는 Deep Agents 스택에서 필수 스캐폴딩입니다. excluded_tools로 모델에 보이는 도구 표면만 숨기고 미들웨어는 그대로 두세요. task 도구를 제거하려면 서브에이전트 없이 실행하기를 참고하세요.

가상 파일 시스템은 스킬, 메모리, 코드 실행, 컨텍스트 관리 같은 여러 다른 하네스 기능에서 사용됩니다. Deep Agents용 커스텀 도구와 미들웨어를 구축할 때도 파일 시스템을 사용할 수 있습니다.

자세한 내용은 백엔드를 참고하세요. 에이전트가 파일 시스템에서 읽을 수 있는 지속적인 저장소 위키를 생성하려면 OpenWiki를 참고하세요.

파일 시스템 권한 (Filesystem permissions)

하네스는 에이전트가 읽거나 쓸 수 있는 파일과 디렉터리를 제어하는 선언적 권한 규칙을 지원합니다. 권한은 위에 나열된 내장 파일 시스템 도구에 적용되며, 선언 순서대로 첫 번째 일치 우선(first-match-wins) 의미론으로 평가됩니다.

에이전트를 만들 때 permissions=에 규칙 목록을 전달하여 권한을 정의하세요. 각 규칙은 다음을 포함합니다:

• operations: "read" 및/또는 "write"
• paths: 파일 또는 디렉터리에 대한 Glob 패턴
• mode: "allow" 또는 "deny"

규칙은 위에서 아래로 평가되며, 첫 번째로 일치하는 규칙이 우선합니다. 일치하는 규칙이 없으면 작업이 허용됩니다.

이 모델은 에이전트를 특정 디렉터리(예: /workspace/)로 제한하고, .env나 자격 증명 같은 민감한 파일을 보호하며, 부모 에이전트보다 서브에이전트에 더 좁은 접근 권한을 부여할 수 있게 해줍니다.

권한은 execute 도구를 통한 임의 명령 실행을 지원하는 샌드박스 백엔드에는 적용되지 않습니다. 커스텀 검증 로직은 백엔드 정책 훅을 사용하세요.

전체 규칙 구조, 예제, 서브에이전트 상속은 권한을 참고하세요.

코드 실행 (Code execution)

Deep Agents는 두 가지 방식으로 코드 실행을 지원합니다:

• 샌드박스 백엔드는 격리된 환경에서 셸 명령을 위한 execute 도구를 노출합니다.
• 인터프리터는 범위 지정된 QuickJS 런타임에서 JavaScript를 실행하는 eval 도구를 추가합니다.

에이전트가 의존성을 설치하고, 테스트를 실행하고, CLI를 호출하거나, 운영 체제 파일 시스템으로 작업해야 할 때 샌드박스 백엔드를 사용하세요. 샌드박스 백엔드는 SandboxBackendProtocolV2를 구현합니다; 감지되면 하네스가 에이전트의 사용 가능한 도구에 execute 도구를 추가합니다.

루프, 배치, 결정적 데이터 변환 또는 프로그래매틱 도구 호출을 위한 가벼운 프로그래밍 가능한 레이어가 필요할 때 인터프리터를 사용하세요. 인터프리터는 셸 접근, 패키지 설치, 파일 시스템 및 네트워크 접근을 제공하지 않습니다.

샌드박스 설정, 제공자, 파일 전송 API는 샌드박스를 참고하세요. QuickJS 런타임과 프로그래매틱 도구 호출은 인터프리터를 참고하세요.

스트리밍 (Streaming)

이벤트 스트리밍은 에이전트 실행을 메시지, 도구 호출, 값, 출력에 대한 타입 지정된 프로젝션으로 노출합니다. Deep Agents는 stream.subagents를 추가하므로 각 위임된 작업이 독립적인 메시지, 도구 호출, 중첩 subagent 스트림을 가진 자체 핸들을 얻습니다.

컨텍스트 관리 (Context management)

컨텍스트 관리 컴포넌트는 에이전트가 무엇을 아는지, 토큰 한도 내에서 얼마나 오래 동작할 수 있는지, 세션 간에 무엇을 유지하는지 제어합니다. 네 개의 레이어가 있습니다:

• 스킬: 스킬 파일에서 점진적으로 로드되는 주문형 도메인 지식
• 메모리: 시작 시 AGENTS.md 파일에서 로드되는 영구 지시와 선호도
• 요약 및 컨텍스트 오프로드: 대화 히스토리와 큰 도구 결과의 자동 압축
• 프롬프트 캐싱: 정적 프롬프트 섹션은 지원되는 모델에서 추론을 빠르게 하고 비용을 줄이기 위해 캐시 자격이 있음

스킬 (Skills)

스킬은 전문화된 워크플로우, 도메인 지식, deep agent를 위한 커스텀 지침을 패키징합니다.

각 스킬은 Agent Skills 표준을 따르며 SKILL.md 파일이 있는 디렉터리에 있습니다. 스킬에는 스크립트, 템플릿, 참조 문서, 기타 지원 리소스도 포함될 수 있습니다.

Deep Agents는 점진적 공개(progressive disclosure)로 스킬을 로드합니다: 에이전트는 시작 시 SKILL.md 프론트매터를 읽고, 작업이 필요할 때만 전체 스킬 콘텐츠를 읽습니다. 이렇게 하면 풍부한 기능을 주문형으로 제공하면서 시작 컨텍스트를 간결하게 유지합니다.

자세한 내용은 스킬을 참고하세요.

메모리 (Memory)

메모리는 코딩 스타일, 선호도, 관례, 프로젝트 가이드라인 같은 대화 간 영구 컨텍스트를 deep agent에 제공합니다.

메모리는 에이전트를 만들 때 memory 매개변수로 전달하는 AGENTS.md 파일을 사용합니다. 스킬과 달리 메모리 파일은 항상 로드되며, 콘텐츠는 구성된 백엔드(StateBackend, StoreBackend, 또는 FilesystemBackend)에 저장됩니다.

에이전트는 상호작용과 피드백에 기반해 메모리를 업데이트할 수도 있으므로, 각 스레드에서 다시 말할 필요 없이 선호도와 패턴이 이어질 수 있습니다.

구성 세부사항과 예제는 메모리를 참고하세요. 코딩 에이전트가 AGENTS.md를 통해 발견하는 저장소 위키를 생성하려면 OpenWiki를 참고하세요.

요약 및 컨텍스트 오프로드 (Summarization and context offloading)

하네스는 컨텍스트를 관리하여 deep agent가 토큰 한도 내에서 장기 실행 작업을 처리하면서 가장 관련 있는 정보를 범위 안에 유지하게 합니다.

이 컨텍스트 흐름은 네 부분으로 구성됩니다:

• 입력 컨텍스트: 시스템 프롬프트, 메모리, 스킬, 도구 프롬프트가 에이전트가 시작하는 내용을 정의합니다.
• 압축: 내장 오프로드와 요약이 대화 히스토리와 큰 중간 결과를 압축합니다.
• 격리: 서브에이전트가 무거운 하위 작업을 격리하고 최종 결과만 반환합니다(위임 참고).
• 장기 메모리: 가상 파일 시스템의 영구 저장소가 스레드 간 정보를 전달합니다.

이 메커니즘들은 함께 단일 컨텍스트 윈도우를 초과하는 다단계 작업을 지원하면서 수동 컨텍스트 정리와 토큰 사용을 줄입니다.

구성 세부사항은 컨텍스트 엔지니어링을 참고하세요. 멀티모달 입력과 도구 출력은 멀티모달을 참고하세요.

프롬프트 캐싱 (Prompt caching)

Anthropic 및 Amazon Bedrock 모델의 경우 create_deep_agent는 시스템 프롬프트의 정적 섹션—매 턴마다 반복되는 기본 에이전트 지침, 메모리, 스킬 콘텐츠—에 자동으로 프롬프트 캐싱을 적용합니다. 이는 호출 간 동일한 토큰을 다시 처리하지 않아 장기 실행 에이전트에서 지연 시간과 비용을 모두 줄입니다.

프롬프트 캐싱은 Anthropic 모델 또는 Bedrock 모델(Claude 또는 Nova)을 사용할 때 기본으로 활성화됩니다. 구성이 필요하지 않습니다.

다른 제공자는 미들웨어 통합에서 사용 가능한 제공자별 캐싱 미들웨어를 참고하세요.

위임 (Delegation)

위임 컴포넌트는 에이전트가 큰 문제를 더 작고 병렬화 가능한 작업 단위로 나눌 수 있게 해줍니다. 두 개의 레이어가 있습니다:

• 작업 계획: 구조화된 작업 추적을 위한 옵트인 write_todos 도구
• 서브에이전트: 격리된 하위 작업을 처리하는 임시 자식 에이전트

작업 계획 (Task planning)

작업 계획은 실행 중에 구조화된 작업 목록을 유지하도록 에이전트를 허용하는 옵트인 하네스 기능입니다.

v0.7부터 작업 계획은 옵트인만 가능합니다. 이전 버전에서는 작업 계획 미들웨어가 기본으로 포함되었습니다.

계획은 종종 다음에 유용합니다:

• 길거나 복잡한 다단계 작업
• 명시적 책임 도구의 이점을 얻는 역량이 낮은 모델
• 에이전트 상태에서 진행 상황을 스트리밍하는 UI(할 일 목록 참고)

실행 중에 구조화된 작업 목록을 유지하는 write_todos 도구를 에이전트에 제공하려면 TodoListMiddleware를 middleware 매개변수에 전달하세요.

```ts OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "openai:gpt-5.5",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  middleware: [todoListMiddleware()],
});

작업은 상태 추적('pending', 'in_progress', 'completed')을 지원하며 에이전트 상태에 유지됩니다. 이는 장기 실행 및 다단계 작업을 구성하기 위한 가벼운 계획 레이어를 에이전트에 제공합니다.

구성 옵션과 동작 세부사항은 할 일 목록을 참고하세요.

서브에이전트 (Subagents)

하네스는 메인 에이전트가 격리된, 장기 실행, 다단계 또는 병렬 작업을 위한 임시 서브에이전트를 만들 수 있는 내장 task 도구를 포함합니다.

서브에이전트 실행은 다음을 제공합니다:

• 새 컨텍스트: 각 호출은 자체 컨텍스트를 가진 새 에이전트 인스턴스를 만듭니다.
• 자율 실행: 서브에이전트는 완료될 때까지 독립적으로 실행됩니다.
• 단일 핸드오프: 메인 에이전트에 최종 리포트 하나를 반환합니다.
• 구성 가능한 전략: 기본 general-purpose 서브에이전트(기본 활성화)를 사용하거나 커스텀 서브에이전트를 정의하세요.
• 상태 없는 메시징: 서브에이전트는 상태가 없으며 여러 메시지를 다시 보낼 수 없습니다.
• 컨텍스트 및 토큰 효율성: 무거운 하위 작업 작업은 격리된 채로 유지되고 간결한 결과로 압축됩니다.

자세한 내용은 서브에이전트를 참고하세요.

조정 (Steering)

조정 컴포넌트는 런타임에 에이전트 동작에 대한 인간의 제어를 제공하고 에이전트 작업에 대한 파일 시스템 권한을 설정합니다.

인간 개입 (Human-in-the-loop)

Deep Agents는 LangGraph 인터럽트와 통합되므로 민감한 도구 호출에 대한 승인을 위해 일시 중지할 수 있습니다. create_deep_agent의 interrupt_on 매개변수로 이 동작을 활성화하세요.

interrupt_on은 도구 이름을 인터럽트 구성에 매핑한 것을 받아들입니다. 예를 들어 interrupt_on={"edit_file": True}는 모든 편집 전에 일시 중지하여 실행 전에 호출을 승인하고, 지침을 추가하거나 도구 입력을 수정할 수 있게 합니다.

이는 파괴적 작업, 비용이 큰 API 호출, 대화형 디버깅에 대한 런타임 안전 및 제어 레이어를 제공합니다.

자세한 내용은 인간 개입을 참고하세요.

시작하기 (Get started)

더 알아보기 (Learn more)

• 이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
• GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.