Vercel의 파일 시스템 우선 AI 에이전트 프레임워크 「eve」

본 기사에서는 vercel/eve를 소개합니다. Vercel이 개발 중인 오픈 소스 프레임워크 「eve」는 파일 시스템을 중심으로 한 내구성 있는 AI 에이전트 구축 기반입니다.

eve란 무엇인가

eve는 「filesystem-first」라는 설계 사상을 내세우는 AI 에이전트 프레임워크입니다. 에이전트의 핵심 기능을 정해진 디렉터리 구조에 배치함으로써, 프로젝트의 검사·확장·운용이 용이하도록 설계되었습니다.

기존의 AI 에이전트 구현에서는 모델에 대한 지시·도구 정의·스케줄러 설정 등이 코드 내에 산재하기 쉬웠습니다. eve는 이것들을 「관습적인 위치 (conventional locations)」에 배치함으로써, 팀이 구조를 한눈에 파악할 수 있도록 하고 있습니다. 현재는 베타 버전으로 공개되어 있으며, API나 사양은 정식 출시 전까지 변경될 가능성이 있습니다.

디렉터리 구조

eve 에이전트의 전형적인 구조는 다음과 같습니다.

my-agent/
└── agent/
├── agent.ts # Optional: model and runtime config
...

각 디렉터리의 역할은 다음과 같습니다.

agent.ts

— 모델 및 런타임 설정을 기술한다 (옵션) -
instructions.md

— 상시 유효한 시스템 프롬프트. 유일한 필수 파일 -
tools/

— 모델이 호출할 수 있는 타입 지정 함수를 배치한다 (옵션) -
skills/

— 온디맨드(On-demand)로 로드되는 절차서를 배치한다 (옵션) -
channels/

— HTTP·Slack·Discord 등의 메시지 채널을 정의한다 (옵션) -
schedules/

— 정기 실행하는 cron 잡을 배치한다 (옵션)

필수인 것은 instructions.md 뿐이며, 나머지는 모두 옵션이라는 설계는 소규모 유스케이스부터 시작하여 점진적으로 기능을 추가해 나가는 접근 방식에 적합합니다.

퀵 스타트 (Quick Start)

신규 프로젝트 생성은 한 번의 명령어로 완료됩니다.

npx eve@latest init my-agent

이 명령어는 my-agent 디렉터리를 생성하고, 의존성 설치·Git 초기화·인터랙티브 터미널 UI 실행까지 일괄적으로 수행합니다.

기존 프로젝트에 eve를 추가하고 싶다면, 경로를 지정하여 실행해 주세요.

cd myapp
npx eve@latest init .

또한, eve 패키지에는 문서가 동봉되어 있으므로, 코딩 에이전트는 node_modules/eve/docs에서 로컬로 문서를 참조할 수 있습니다.

미니멀한 구현 예시

스캐폴드(Scaffold)로 생성된 프로젝트에는 agent 디렉터리가 포함됩니다. 먼저 agent/instructions.md를 다음 내용으로 바꿔 써 주세요.

You are a concise weather demo assistant. Tell users that the weather data is mocked.

다음으로, 모의(Mock) 날씨 도구를 agent/tools/get_weather.ts에 추가합니다.

import { defineTool } from "eve/tools";
import { z } from "zod";
export default defineTool({
...

도구 정의에는 defineTool 함수를 사용하며, 입력 스키마에는 zod를 이용합니다. 타입 안전한(Type-safe) 인터페이스가 표준으로 제공되는 것이 특징입니다.

이어서, 사용할 모델을 agent/agent.ts에서 지정합니다.

import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-sonnet-4.6",
...

마지막으로 dev server를 실행하면 에이전트가 동작 상태가 됩니다.

npm run dev

이 3개의 파일만으로 작동하는 에이전트가 완성됩니다. 필요에 따라 human-in-the-loop 프롬프트·서브 에이전트·스케줄을 추가해 나가는 형태입니다.

설계 사상의 배경

eve의 「filesystem-first (파일 시스템 우선)」 접근 방식에는 몇 가지 실질적인 장점이 있습니다.

가독성 향상 — 프로젝트를 처음 보는 개발자라도 디렉토리 구조를 살펴보는 것만으로 에이전트의 능력과 구성을 파악할 수 있습니다.

차분 관리(diff management)의 용이성 — instructions.md와 같은 자연어 파일도 Git으로 차분 관리가 가능하므로, 프롬프트의 변경 이력을 추적할 수 있습니다.

확장성 — 기능 추가가 「파일을 배치하는」 작업에 대응하므로, 코드의 복잡도를 높이지 않고도 에이전트의 능력을 단계적으로 확장할 수 있습니다.

코딩 에이전트와의 친화성 — 문서가 node_modules/eve/docs에 로컬로 배치되므로, Cursor나 GitHub Copilot과 같은 코딩 에이전트가 API를 참조하기 쉬운 구조로 되어 있습니다.

커뮤니티와 기여

eve의 커뮤니티는 GitHub Discussions를 중심으로 활동하고 있습니다. 질문, 아이디어 공유, 제작물 발표 등은 그곳에서 이루어집니다.

기여(Contribution) 또한 환영받고 있으며, 로컬 환경 설정 절차나 변경 사항을 전달하는 방법은 CONTRIBUTING.md에 기재되어 있습니다. Issues와 Discussions를 통한 협업도 권장됩니다.

보안 정책

보안 취약점에 대해서는 공개 Issue에 게시하는 것을 피하도록 요청하고 있습니다. SECURITY.md의 절차에 따라 responsible.disclosure@vercel.com으로 책임 있는 공개(responsible disclosure)를 수행해야 합니다.

베타 버전 주의사항

eve는 현재 베타 버전이며, Vercel의 베타 이용 약관이 적용됩니다. 프레임워크, API, 문서, 동작은 GA(General Availability) 전까지 변경될 가능성이 있으므로, 프로덕션 환경 도입은 신중하게 판단해야 합니다.

파일 시스템을 설계의 핵심으로 삼아 AI 에이전트의 구조를 코드베이스로 자연스럽게 표현하는 eve의 접근 방식은, 에이전트 개발의 복잡성을 정리하는 유력한 방향성 중 하나라고 할 수 있습니다. 공식 문서는 eve.dev/docs 에서 참조할 수 있습니다.

출처: