AgentFS 소개
AgentFS는 AI 에이전트를 위해 특별히 설계된 파일 시스템이자 상태 관리 SDK입니다. Turso(SQLite 기반의 Edge DB) 팀이 개발한 이 프로젝트는 AI 에이전트가 실행되는 동안 생성하는 파일, 상태(State), 도구 호출 기록(Tool Call Logs) 등을 단 하나의 이식 가능한 데이터베이스 파일(sqlite)로 통합하여 관리할 수 있게 해줍니다.
기존의 AI 에이전트 개발 환경에서는 에이전트의 '기억(Memory)'과 '파일 조작'을 처리하기 위해 복잡한 인프라가 필요했습니다. 예를 들어, 대화 기록은 데이터베이스에, 생성된 이미지는 클라우드 스토리지에, 설정값은 별도의 키-값 저장소(Key-Value Store)에 저장해야 했습니다. 이는 에이전트의 상태를 완벽하게 복제하거나, 특정 시점으로 되돌리는(Rollback) 디버깅 작업을 어렵게 만들었습니다.
AgentFS는 이러한 문제를 해결하기 위해 "모든 것을 하나의 파일에 담는다"는 접근 방식을 취합니다. POSIX 호환 파일 시스템 인터페이스, 키-값 저장소, 그리고 실행 로그를 모두 하나의 SQLite 파일 안에 저장함으로써, 개발자는 cp agent.db snapshot.db 명령 하나만으로 에이전트의 전체 상태를 스냅샷 뜨거나 다른 머신으로 이동시킬 수 있습니다.
AgentFS는 현재 알파(Alpha) 단계로, 프로덕션 환경보다는 개발 및 테스트 목적으로 사용이 권장됩니다.
AgentFS와 일반 파일 시스템 (OS Filesystem)을 비교하면, 일반적인 운영체제 파일 시스템(ext4, NTFS 등)은 파일 저장에는 최적화되어 있지만, 메타데이터 관리나 상태 추적 기능은 부족합니다. 반면, AgentFS는 파일 저장뿐만 아니라 에이전트의 내부 변수(Key-Value)와 행동 로그(Tool Calls)를 함께 저장하며, 모든 변경 사항이 트랜잭션으로 관리되어 데이터 무결성을 보장합니다.
AgentFS와 벡터 데이터베이스 (Vector DB)를 비교하면, 벡터 DB는 텍스트의 의미론적 검색(Semantic Search)에 특화되어 있어 RAG(검색 증강 생성) 구현에 필수적입니다. AgentFS는 벡터 검색을 대체하는 것이 아니라, 에이전트의 "구조적인 상태(State)"와 "작업 파일(Work Files)" 을 관리하는 데 초점을 맞춥니다. 따라서 실제 구축 시에는 벡터 DB(지식 검색용)와 AgentFS(상태 및 작업 관리용)를 함께 사용하는 것이 일반적입니다.
AgentFS의 주요 기능
AgentFS는 에이전트 개발자가 겪는 복잡한 상태 관리 문제를 단순화하기 위해 다음과 같은 핵심 기능을 제공합니다.
통합된 저장소 구조 (Unified Storage)
AgentFS의 가장 큰 특징은 에이전트의 모든 활동 데이터를 단일 SQLite 데이터베이스 파일에 저장한다는 점입니다. 이를 통해 다음과 같은 이점을 얻을 수 있습니다.
-
감사 가능성 (Auditability): 에이전트가 어떤 파일을 수정했고, 어떤 도구를 호출했는지 SQL 쿼리로 즉시 조회할 수 있습니다.
-
이동성 (Portability): 데이터베이스 파일 하나만 복사하면 로컬 개발 환경에서 클라우드나 엣지 디바이스로 에이전트의 전체 문맥을 이동할 수 있습니다.
-
재현성 (Reproducibility): 특정 시점의 DB 파일을 백업해두면, 에이전트가 오류를 일으킨 시점의 상태를 완벽하게 복원하여 디버깅할 수 있습니다.
세 가지 핵심 인터페이스
AgentFS는 SDK를 통해 다음 세 가지 추상화 계층을 제공합니다.
-
Filesystem (FS): POSIX 표준과 유사한 파일 및 디렉터리 조작 기능을 제공합니다.
-
Key-Value (KV): 에이전트의 설정이나 단기 기억을 저장하기 위한 고속 키-값 저장소입니다.
-
Toolcall: 에이전트가 외부 도구를 호출한 내역(입력 파라미터 및 결과)을 자동으로 기록하고 추적합니다.
FUSE 마운트 및 샌드박스 (실험적 기능)
AgentFS는 단순한 라이브러리 형태를 넘어, 실제로 리눅스 파일 시스템처럼 마운트하여 사용할 수 있는 FUSE Mount 기능을 제공합니다. 또한, 신뢰할 수 없는 코드를 실행할 때 파일 시스템 접근을 제어하고 모니터링할 수 있는 샌드박스(Sandbox) 환경도 실험적으로 지원하고 있습니다.
FUSE(Filesystem in Userspace)는 커널 코드를 수정하지 않고 사용자 공간에서 파일 시스템을 생성할 수 있게 해주는 유닉스 계열 OS의 기능입니다. AgentFS w/ FUSE와 관련한 더 상세한 내용은 다음 블로그를 참고해주세요:
AgentFS 설치 및 사용 예시
AgentFS는 TypeScript/Javascript 및 Rust를 지원합니다. 다음과 같은 명령어로 각 언어별 SDK를 설치할 수 있습니다:
TypeScript/Javascript는 npm을 사용하여 설치합니다:
npm install agentfs-sdk
Rust는 다음과 같이 설치할 수 있습니다:
cargo add agentfs-sdk
AgentFS SDK 사용 예시: TypeScript
다음은 AgentFS의 TypeScript SDK를 사용하여 에이전트 파일 시스템을 초기화하고, 설정값과 파일을 저장하는 간단한 예제입니다.
import { AgentFS } from 'agentfs-sdk';
// 1. 에이전트 파일 시스템 열기 (식별자 지정)
// .agentfs/my-agent.db 파일이 생성됩니다.
const agent = await AgentFS.open({ id: 'my-agent' });
// 2. Key-Value 저장소 사용 (설정 저장)
await agent.kv.set('user:preferences', { theme: 'dark' });
const prefs = await agent.kv.get('user:preferences');
// 3. 파일 시스템 조작 (파일 쓰기 및 목록 조회)
await agent.fs.writeFile('/output/report.txt', 'Analysis Result...');
const files = await agent.fs.readdir('/output');
// 4. 도구 호출 기록 (감사 로그)
await agent.tools.record(
'web_search',
Date.now() / 1000,
Date.now() / 1000 + 1.5,
{ query: 'AI Trends' },
{ results: ['...'] }
);
CLI 사용 예시
터미널에서 직접 에이전트의 파일 시스템을 관리할 수도 있습니다.
# 에이전트 생성
$ agentfs init my-agent
# 파일 시스템 내 파일 목록 조회
$ agentfs fs ls my-agent
# 파일 내용 확인
$ agentfs fs cat my-agent hello.txt
라이선스
AgentFS 프로젝트는 MIT License 로 공개 및 배포되고 있습니다.
Turso 공식 홈페이지
AgentFS 소개 문서: Turso Docs
AgentFS 프로젝트 GitHub 저장소
https://github.com/tursodatabase/agentfs
더 읽어보기
-
SQLite: AgentFS가 기반으로 하고 있는 경량 관계형 데이터베이스 엔진입니다.
-
Turso: SQLite를 기반으로 엣지 컴퓨팅 및 분산 환경에 최적화된 데이터베이스 서비스입니다.
-
FUSE (Filesystem in Userspace): 커널 코드를 수정하지 않고 사용자 공간에서 파일 시스템을 생성할 수 있게 해주는 유닉스 계열 OS의 기능입니다.
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 