#Deep Agents (Core capabilities)

#Planning capabilities

이 도구는 상담원이 구조화된 작업 목록을 관리하는 데 사용할 수 있는 write_todos 도구를 제공합니다.

#Virtual filesystem

다양한 플러그인 백엔드를 지원하는 구성 가능한 가상 파일 시스템을 제공합니다. 가상 파일 시스템은 스킬, 메모리, 코드 실행 및 컨텍스트 관리와 같은 여러 다른 하네스 기능에서 사용됩니다. 또한 Deep Agents용 사용자 지정 도구 및 미들웨어를 구축할 때 파일 시스템을 사용할 수도 있습니다.

다음과 같은 파일 시스템 작업을 지원합니다.

• ls: 디렉터리의 파일 목록을 메타데이터(크기, 수정 시간)와 함께 표시합니다.
• read_file: 파일 내용을 줄 번호와 함께 읽습니다. 대용량 파일의 경우 오프셋/제한을 지원합니다. 또한 텍스트가 아닌 파일(이미지, 비디오, 오디오, 문서)의 경우 멀티모달 콘텐츠 블록을 반환합니다. 지원되는 확장자는 아래를 참조하십시오.
• write_file: 새 파일을 생성합니다.
• edit_file: 파일에서 정확한 문자열 바꾸기를 수행합니다(전역 바꾸기 모드 사용).
• glob: 특정 패턴(예: */.py)과 일치하는 파일을 찾습니다.
• grep: 여러 출력 모드(파일만, 컨텍스트와 함께 내용, 개수)로 파일 내용을 검색합니다.
• execute: 환경에서 셸 명령을 실행합니다(샌드박스 백엔드에서만 사용 가능).

#Filesystem permissions

에이전트가 읽거나 쓸 수 있는 파일 및 디렉터리를 제어하는 ​​선언적 권한 규칙을 지원합니다. 권한은 위에 나열된 내장 파일 시스템 도구에 적용되며, 선언 순서대로 평가되고 먼저 일치하는 규칙이 우선합니다.

작동 방식:

• 에이전트를 생성할 때 permissions=에 규칙 목록을 전달합니다.
• 각 규칙은 작업("읽기", "쓰기"), 경로(글로브 패턴) 및 모드("허용" 또는 "거부")를 지정합니다.
• 먼저 일치하는 규칙이 우선합니다. 일치하는 규칙이 없으면 작업이 허용됩니다.

유용한 점:

• 에이전트의 접근 권한을 특정 디렉터리(예: /workspace/)로 제한합니다.
• 민감한 파일(예: .env, 자격 증명)을 보호합니다.
• 하위 에이전트에 상위 에이전트보다 더 좁은 접근 권한을 부여합니다.

권한은 execute 도구를 통해 임의의 명령 실행을 지원하는 샌드박스 백엔드에는 적용되지 않습니다.

#Task delegation (subagents)

이 기능을 통해 메인 에이전트는 격리된 다단계 작업을 위한 임시 "subagents"를 생성할 수 있습니다.

유용성:

• 컨텍스트 격리 - 서브에이전트의 작업이 메인 에이전트의 컨텍스트를 복잡하게 만들지 않습니다.
• 병렬 실행 - 여러 서브에이전트가 동시에 실행될 수 있습니다.
• 특화 - 서브에이전트는 서로 다른 도구/구성을 가질 수 있습니다.
• 토큰 효율성 - 대규모 하위 작업 컨텍스트가 단일 결과로 압축됩니다.

작동 방식:

• 메인 에이전트는 작업 도구를 가지고 있습니다.
• 호출되면 자체 컨텍스트를 가진 새로운 에이전트 인스턴스를 생성합니다.
• 서브에이전트는 완료될 때까지 자율적으로 실행됩니다.
• 메인 에이전트에 단일 최종 보고서를 반환합니다.
• 서브에이전트는 상태를 저장하지 않습니다(여러 메시지를 다시 보낼 수 없음).

기본 서브에이전트:

• "범용" 서브에이전트가 자동으로 제공됩니다.
• 기본적으로 파일 시스템 도구를 포함합니다.
• 추가 도구/미들웨어로 사용자 정의할 수 있습니다.

사용자 정의 서브에이전트:

• 특정 도구를 사용하는 특화된 서브에이전트를 정의합니다.
• 예: 코드 검토자, 웹 연구자, 테스트 실행자
• subagents 매개변수를 통해 구성합니다.

#Context and token management

심층 에이전트가 필요한 정보를 유지하면서 토큰 제한 내에서 장시간 실행되는 작업을 처리할 수 있도록 컨텍스트를 관리합니다.

작동 방식:

• 입력 컨텍스트 — 시스템 프롬프트, 메모리, 스킬 및 도구 프롬프트는 에이전트가 시작 시 알고 있는 정보를 구성합니다.
• 압축 — 내장된 오프로딩 및 요약 기능을 통해 작업 진행에 따라 컨텍스트를 윈도우 제한 내에 유지합니다.
• 격리 — 하위 에이전트는 무거운 작업을 격리하고 결과만 반환합니다(작업 위임 참조).
• 장기 메모리 — 가상 파일 시스템을 통해 스레드 간에 영구 저장소를 제공합니다.

유용성:

• 단일 컨텍스트 윈도우를 초과하는 다단계 작업을 지원합니다.
• 수동으로 다듬지 않고도 가장 관련성이 높은 정보를 범위 내에 유지합니다.
• 자동 요약 및 오프로딩을 통해 토큰 사용량을 줄입니다.

#Code execution

샌드박스 백엔드를 사용하면, 에이전트가 격리된 환경에서 셸 명령을 실행할 수 있도록 하는 실행 도구가 하네스에 노출됩니다. 이를 통해 에이전트는 작업의 일부로 종속성을 설치하고, 스크립트를 실행하고, 코드를 실행할 수 있습니다.

작동 방식:

• 샌드박스 백엔드는 SandboxBackendProtocolV2를 구현합니다. 샌드박스 백엔드가 감지되면 하네스는 에이전트가 사용할 수 있는 도구에 실행 도구를 추가합니다.
• 샌드박스 백엔드가 없으면 에이전트는 파일 시스템 도구(read_file, write_file 등)만 사용할 수 있으며 명령을 실행할 수 없습니다.
• 실행 도구는 표준 출력/표준 오류를 통합하여 반환하고, 종료 코드를 반환하며, 큰 출력은 잘라냅니다(에이전트가 점진적으로 읽을 수 있도록 파일에 저장).

유용한 이유:

• 보안 - 코드가 격리된 환경에서 실행되어 호스트 시스템을 에이전트 작업으로부터 보호합니다.
• 깔끔한 환경 - 로컬 설정 없이 특정 종속성 또는 OS 구성을 사용할 수 있습니다.
• 재현성 - 팀 전체에서 일관된 실행 환경을 제공합니다.
• 설정, 공급자 및 파일 전송 API에 대한 자세한 내용은 샌드박스를 참조하세요.

#Human-in-the-loop

지정된 도구 호출 시 에이전트 실행을 일시 중지하여 사용자의 승인 또는 수정을 요청할 수 있습니다. 이 기능은 interrupt_on 매개변수를 통해 선택적으로 사용할 수 있습니다.

구성:

• create_deep_agent 함수에 interrupt_on 매개변수를 전달하고 도구 이름과 인터럽트 구성을 매핑합니다.
• 예: interrupt_on={"edit_file": True}는 모든 편집 전에 에이전트 실행을 일시 중지합니다.
• 프롬프트가 표시될 때 승인 메시지를 제공하거나 도구 입력을 수정할 수 있습니다.

유용한 점:

• 파괴적인 작업에 대한 안전 장치
• 비용이 많이 드는 API 호출 전 사용자 확인
• 대화형 디버깅 및 안내

#Skills

에이전트에 특화된 워크플로와 도메인 지식을 제공하는 스킬을 지원합니다.

작동 방식:

• 스킬은 에이전트 스킬 표준을 따릅니다.
• 각 스킬은 지침과 메타데이터가 포함된 SKILL.md 파일이 있는 디렉터리입니다.
• 스킬에는 추가 스크립트, 참조 문서, 템플릿 및 기타 리소스가 포함될 수 있습니다.
• 스킬은 점진적 공개 방식을 사용합니다. 즉, 에이전트가 현재 작업에 유용하다고 판단할 때만 로드됩니다.
• 에이전트는 시작 시 각 SKILL.md 파일의 프런트매터를 읽은 다음 필요할 때 전체 스킬 콘텐츠를 검토합니다.

유용한 이유:

• 필요할 때만 관련 스킬을 로드하여 토큰 사용량을 줄입니다.
• 추가 컨텍스트와 함께 기능을 더 큰 작업으로 묶습니다.
• 시스템 프롬프트를 복잡하게 만들지 않고 전문적인 지식을 제공합니다.
• 모듈식으로 재사용 가능한 에이전트 기능을 구현할 수 있습니다.

#Memory

이 기능은 대화 전반에 걸쳐 딥 에이전트에 추가 컨텍스트를 제공하는 영구 메모리 파일을 지원합니다. 이러한 파일에는 일반적으로 코딩 스타일, 기본 설정, 규칙 및 지침이 포함되어 에이전트가 코드베이스를 이해하고 사용자의 기본 설정을 따르는 데 도움이 됩니다.

작동 방식:

• AGENTS.md 파일을 사용하여 영구 컨텍스트를 제공합니다.
• 메모리 파일은 항상 로드됩니다(점진적 공개를 사용하는 스킬과 다름).
• 에이전트를 생성할 때 메모리 매개변수에 하나 이상의 파일 경로를 전달합니다.
• 파일은 에이전트의 백엔드(StateBackend, StoreBackend 또는 FilesystemBackend)에 저장됩니다.
• 에이전트는 상호 작용, 피드백 및 식별된 패턴을 기반으로 메모리를 업데이트할 수 있습니다.

유용한 이유:

• 대화마다 다시 지정할 필요가 없는 영구 컨텍스트를 제공합니다.
• 사용자 기본 설정, 프로젝트 지침 또는 도메인 지식을 저장하는 데 유용합니다.
• 에이전트가 항상 사용할 수 있으므로 일관된 동작을 보장합니다.