Mirage - AI 에이전트를 위한 통합 가상 파일시스템 완벽 가이드

Mirage — AI 에이전트를 위한 통합 가상 파일시스템

Mirage - AI 에이전트를 위한 통합 가상 파일시스템

AI 에이전트가 다양한 서비스를무하게 활용할 수 있는 시대가 열리고 있습니다. 지금까지 AI 에이전트가 S3에서 데이터를 읽고, Slack으로 메시지를 보내고, GitHub의 이슈를 확인하려면 각 서비스마다 별도의 SDK나 MCP 서버를 배워야 했습니다. Mirage는 이 문제를 완전히 새로운 관점에서 해결합니다. 모든 서비스를 하나의 파일시스템처럼 보이게 만드는 것, 바로 Mirage의 핵심 아이디어입니다.

왜 파일시스템인가

현대 AI 모델은 bash와 Unix 도구에 대해 놀라울 정도로 깊은 이해도를 가지고 있습니다. grep, cat, wc, cp 같은 명령어들은 수십 년간의 인터넷 텍스트로 훈련되어 있어 LLM은 이러한 도구들을 매우 자연스럽게 활용할 수 있습니다. Mirage는 이 점을 활용합니다. 에이전트가 새로운 API를 배울 필요 없이, 익숙한 bash 명령어만으로 S3, Gmail, Slack, GitHub, Redis 등 수십 개의 서비스를 모두 제어할 수 있게 됩니다.

기존 접근법의 한계를 생각해 보면 이 아이디어의 혁신이 더 명확해집니다. 에이전트가 Gmail에 접근하려면 Gmail API를 위한 별도 어댑터를 만들어야 했고, GitHub의_repoitory를 읽으려면 또 다른 어댑터가 필요했습니다. 서비스가 늘어나면 어댑터도 함께 증가하고, 각 어댑터마다 다른 방식으로 코딩해야 하니 에이전트의 복잡도가 기하급수적으로 올라갑니다. Mirage는 서비스 하나에 하나의 Resource만 마운트하면 되므로, 어떤 서비스든 동일한 파일시스템 의미론으로 접근할 수 있습니다.

지원하는 서비스들

Mirage는 현재 엄청난수 서비스를 지원합니다. 클라우드 스토리지부터 협업 도구, 데이터베이스, 메신저까지 다양한 백엔드를 단일 파일시스템 트리에 마운트할 수 있습니다. 마운트할 수 있는 서비스의 종류를 크게 나누어 보면 다음과 같습니다.

첫 번째로 클라우드 스토리지입니다. Amazon S3, Cloudflare R2, Oracle Cloud Infrastructure, Supabase, Google Cloud Storage 등이 모두 파일처럼 읽고 쓸 수 있습니다. 두 번째로 Google's ecosystem입니다. Gmail, Google Drive, Google Docs, Google Sheets, Google Slides 모두 마운트할 수 있어 에이전트가 이메일 확인, 문서 작성, 스프레드시트 분석 등을 모두 쉘 명령어 하나로 처리할 수 있습니다. 세 번째로 GitHub생태계통입니다. GitHub repoitory 콘텐츠뿐 아니라 Issues, Pull Requests, wiki 페이지도 파일로 탐색할 수 있습니다. 네 번째로 프로젝트 관리 도구입니다. Linear, Notion, Trello 같은 도구도 파일시스템처럼 접근할 수 있습니다. 다섯 번째로 메신저 및 커뮤니케이션 도구입니다. Slack, Discord, Telegram, 이메일 모두 마운트할 수 있어 에이전트가 채널 메시지 조회나 파일 전송을 자연스럽게 수행할 수 있습니다. 마지막으로 데이터베이스 및 기타 서비스입니다. MongoDB, Redis, SSH, 로컬 디스크 등도 동일하게 지원합니다.

이 모든 서비스가 단일 루트 트리 아래 나란히 배치됩니다. 예를 들어 /s3 버킷, /gmail 받은편지함, /slack 채널, /github repositor가 모두 같은 레벨에서 ls나 cat 같은 표준 유닉스 도구로 탐색할 수 있습니다.

핵심 아키텍처

Mirage의 내부 구조는 크게 네 가지 핵심 컴포넌트로 구성됩니다. Workspace가 전체적인 가상 파일시스템을 관리하고, Resource가 각 백엔드 서비스와의 통신을 담당하며, Cache가 성능 최적화를, Command Extension이 사용자 정의 bash 명령어 등록을 가능하게 합니다.

Workspace는 가상 파일시스템의 루트 역할을 합니다. 사용자가 다양한 Resource를 등록하면, Workspace가 이를 단일 디렉터리 트리로 구성합니다. 에이전트는 이 트리 전체를 하나의 로컬 파일시스템처럼 인식하고 ls, cd, cat, cp, grep 등 표준 bash 도구를 사용해 탐색할 수 있습니다. 각 Resource는 마운트 지점과 1대1로 매핑됩니다.

Resource는 각 외부 서비스의 어댑터 역할을 합니다. RAMResource는 메모리 내 파일시스템이고, S3Resource는 Amazon S3 버킷에, SlackResource는 Slack 워크스페이스에, GitHubResource는 GitHub repoository에 각각 연결됩니다. Resource는 파일시스템 의미론을 각 서비스의 API 호출로 변환하는 번역기라고 볼 수 있습니다.

Cache는 성능 향상을 위한 2계층 구조로 설계되어 있습니다. Index Cache는 디렉터리 목록과 메타데이터를 관리합니다. 첫 번째 탐색은 API를 호출하지만, 이후에는 TTL이 만료될 때까지 인덱스에서 응답합니다. File Cache는 오브젝트 바이트를 캐싱합니다. 첫 번째 읽기는 원본을 스트리밍하지만, 이후의 읽기는 캐시에서 수행됩니다. 이 구조 덕분에 반복적인 API 호출을 줄이면서 응답 속도를 크게 높일 수 있습니다.

Cache 백엔드는 선택적으로 RAM 또는 Redis를 사용할 수 있습니다. RAM 모드는 기본값으로 프로세스 내 인메모리 캐시를 사용하며 512MB 파일 캐시와 10분 인덱스 TTL을 제공합니다. Redis 모드는 워커, 프로세스, 머신 간 캐시를 공유할 수 있어 재시작 후에도 캐시가 유지됩니다.

설치하고 시작하기

Mirage는 Python과 TypeScript 모두에서 사용할 수 있으며 CLI도 함께 제공됩니다. 먼저 전제 조건을 확인합니다. Python 버전은 3.12 이상이 필요하고, TypeScript SDK의 경우 Node.js 20 이상이 필요합니다. macOS 또는 Linux에서 FUSE 기반 마운트를 사용하려면 해당 플랫폼 지원도 필요합니다.

Python 환경이라면 uv를 사용해 설치합니다.

uv add mirage-ai

TypeScript 환경이라면 목적에 맞는 패키지를 선택해 설치합니다. Node.js 서버나 CLI라면 @struktoai/mirage-node를, 브라우저나 edge 런타임이라면 @struktoai/mirage-browser를, 런타임에 무관한 기본 기능만 필요하다면 @struktoai/mirage-core를 선택하면 됩니다.

npm install @struktoai/mirage-nodenpm install @struktoai/mirage-browsernpm install @struktoai/mirage-core

CLI를 선호한다면 설치 스크립트를 실행하거나 패키지 매니저를 이용할 수 있습니다.

curl -fsSL https://strukto.ai/mirage/install.sh | shnpm install -g @struktoai/mirage-cli

실전 사용 예시

Python으로 Mirage를 사용하는 기본 패턴은 매우 직관적입니다. Workspace 객체를 생성하고, 원하는 Resource를 마운트한 후, execute 메서드로 bash 명령어를 전달하면 됩니다.

from mirage import Workspacefrom mirage.resource.s3 import S3Config, S3Resourcefrom mirage.resource.slack import SlackConfig, SlackResourcefrom mirage.resource.ram import RAMResourcews = Workspace({"/data": RAMResource(),"/s3": S3Resource(S3Config(bucket="my-bucket")),"/slack": SlackResource(SlackConfig()),})# S3에서 파일을 로컬 RAM으로 복사await ws.execute("cp /s3/report.csv /data/report.csv")# 로그 파일에서 특정 패턴 개수 세기alert_count = await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

TypeScript도 동일한 패턴을 지원합니다.

import { Workspace, RAMResource, S3Resource, SlackResource } from '@struktoai/mirage-browser'const ws = new Workspace({'/data': new RAMResource(),'/s3': new S3Resource({ bucket: 'my-bucket' }),'/slack': new SlackResource({}),})await ws.execute('cp /s3/report.csv /data/report.csv')const alertCount = await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

커맨드 확장 기능

Mirage의 또 다른 강력한 기능은 커맨드 확장입니다. 기본 bash 명령어 외에 에이전트가 사용할 사용자 정의 명령어를 등록할 수 있습니다. 등록된 명령어는 모든 마운트에서 동일하게 사용할 수 있습니다.

ws.command('summarize', ...)

특정 Resource나 파일 타입에 대해 명령어를 오버라이드할 수도 있습니다. 예를 들어 S3의 Parquet 파일에 cat을 실행하면 원시 바이트 대신 JSON 행으로 출력되도록 설정할 수 있습니다.

ws.command('cat', {resource: 's3',filetype: 'parquet'}, ...)

이 기능을 활용하면 에이전트가 복잡한 파일 포맷도 자연스럽게 처리할 수 있습니다. Parquet 파일을 cat으로 읽으면 사람이 읽을 수 있는 JSON으로 변환해주는 것이죠.

에이전트 프레임워크 연동

Mirage는 현재적주류 에이전트 프레임워크 대부분과 연동됩니다. OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, OpenHands, Mastra 등이 모두 지원됩니다. 프레임워크마다 연동 방식이 조금씩 다르지만, 공통점은 에이전트가 Mirage Workspace를 동일한 환경에서 활용할 수 있다는 점입니다.

OpenAI Agents SDK와 연동하면 MirageSandboxClient를 통해 Workspace를 샌드박스로 등록할 수 있습니다. 에이전트가 실행하는 bash 명령어가 사용자가 마운트한 리소스에 대해 작동하므로, 모델이나 런타임을 바꿔도 코드 변경이 필요 없습니다.

from agents import Runnerfrom agents.run import RunConfigfrom agents.sandbox import SandboxAgent, SandboxRunConfigfrom mirage.agents.openai_agents import MirageSandboxClientclient = MirageSandboxClient(ws)agent = SandboxAgent(name="Mirage Sandbox Agent",model="gpt-5.4-nano",instructions=ws.file_prompt,)result = await Runner.run(agent,"Summarize /s3/data/report.parquet into /report.txt.",run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),)

Vercel AI SDK와는 mirageTools를 통해 연동됩니다. mirageTools가 Workspace를 AI SDK 도구 세트로 노출해주므로, 어떤 모델이든 마운트된 리소스를 읽고 쓸 수 있습니다.

import { generateText } from 'ai'import { openai } from '@ai-sdk/openai'import { mirageTools } from '@struktoai/mirage-agents/vercel'import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'const { text } = await generateText({model: openai('gpt-5.4-nano'),system: buildSystemPrompt({mountInfo: { '/': 'In-memory filesystem' }}),prompt: "Use readFile to read /docs/paper.pdf, then describe what's in it.",tools: mirageTools(ws),})

이식 가능한 워크스페이스

Mirage는 환경 자체를 스냅샷하고 복제할 수 있는 기능을 제공합니다. 에이전트 실행을 다른 머신으로 옮길 때 재시작이나 재구성이 필요 없습니다. 현재 워크스페이스 상태를 tar 파일로 스냅샷하고, 필요할 때 다시 로드할 수 있습니다.

ws.snapshot("demo.tar")

CLI에서도 동일한 작업을 수행할 수 있습니다.

mirage workspace snapshot demo demo.tarmirage workspace load demo.tar --id demo-restored

이 기능은 에이전트 워크로드를 분산 환경에서 실행할 때 특히 유용합니다. 하나의 환경을 여러 머신에서 재현 가능하므로 실험적 setting을 공유하거나 대규모 처리를 위한 스케일링이 가능합니다.

정리하며

Mirage는 AI 에이전트의 서비스를 통합하는 접근법에 새로운 방향을 제시합니다. 새로운 API를 배우는 대신 익숙한 bash 도구를 사용하는 것이 핵심입니다. 수십 개의 서비스를 단일 파일시스템으로 통합하고, 에이전트가 별도 설정 없이 다양한 백엔드를 탐색하고 조작할 수 있게 합니다.

현재 Apache-2.0 라이선스로 공개되어 있으며 GitHub에서 2.5k 이상의 스타어를 받고 있습니다. Python과 TypeScript SDK 모두 제공되므로 다양한 환경에서 활용할 수 있습니다. AI 에이전트 개발에 관심 있다면 Mirage를 직접시해볼 것을 권장합니다.

---

📚 출처

• https://news.hada.io/topic?id=29681