【Eve】AI 에이전트는 "디렉토리"가 된다 — Vercel에서 출시한 에이전트 프레임워크를 사용해 보다

서론

2026년 6월, Vercel이 오픈 소스 에이전트 프레임워크(agent framework)인 Eve를 공개했습니다.

Eve가 흥미로운 점은, 에이전트를 단순히 '작동하는 프로토타입'이 아니라 처음부터 '실제 서비스(production)에서 돌아가는 것'으로 설계했다는 점입니다.

구체적으로는, 에이전트에게 필요한 다음과 같은 요소들이 프레임워크에 처음부터 포함되어 있어, 매번 제로 베이스에서 에이전트를 조립할 필요가 없는 설계로 되어 있습니다.

durable execution (지속적 실행)

sandboxed compute (격리된 계산 환경)

human-in-the-loop approvals (인간을 개입시키는 승인 플로우)

• subagents (서브 에이전트)

evals (에이전트의 동작을 채점하는 평가)

에이전트 개발은 프레임워크 이전의 Web과 같은 상태

Vercel의 'Introducing eve' 블로그에는 다음과 같이 적혀 있습니다.

Agents today are where the web was before frameworks, with everyone hand-rolling the same plumbing and nothing carrying over to the next one.

Web의 태동기 시절, 모든 팀이 자신들의 서버를 직접 수작업으로 만들었던 것처럼, 에이전트 개발도 지금 모두가 똑같이 기본 부분을 처음부터 구축하고 있습니다.

실행 결과를 확실히 기록하는 메커니즘, 에이전트 생성 코드를 격리하는 Sandbox, 중요한 조작에 대한 사람의 승인, 여러 단계에 걸친 재개 가능한 실행 플로우 등 에이전트에 필요한 구성 요소들은 다음 에이전트를 만들 때 거의 계승되지 않습니다.

Eve는 Next.js가 Web에 대해 했던 일을, Eve는 에이전트에 대해 하려고 합니다.

이 기사에서 다룰 내용

이 기사에서는 공식 블로그의 내용을 해설하면서, 실제로 다음과 같은 소스를 사용하여 Eve의 소개 기사를 쓰는 집필 에이전트를 만들어 보았기에, 그 경험을 곁들여 해설합니다.

Eve란 — 디렉토리가 에이전트

Eve의 핵심 개념은 파일 시스템 퍼스트(file system-first) 설계입니다. 에이전트를 정의하기 위해 기존의 컨벤션(convention)을 따른 파일과 디렉토리를 사용합니다.

Next.js에서 app/ 아래에 파일을 두는 것만으로 라우트(route)가 생성되는 것과 마찬가지로, Eve에서는 agent/ 아래에 둔 파일과 디렉토리가 그대로 에이전트의 부품이 됩니다.

예를 들어, agent/tools/에 두면 툴(tool), agent/skills/에 두면 스킬(skill)이 되는 것처럼, 어디에 두느냐(규약 / convention)에 따라 역할이 결정되며, Eve가 이를 발견하여 자동으로 배선(wiring)합니다.

실제로 Eve가 보여주는 에이전트의 형태는 다음과 같습니다.

agent/
agent.ts # it runs on the model
instructions.md # who it is
...

각 파일이 에이전트의 하나의 부품을 나타냅니다.

즉, 디렉토리 구조를 보면 그 에이전트가 누구이며, 무엇을 할 수 있고, 어디에 있으며, 언제 동작하는지를 한눈에 알 수 있습니다. "파일 경로가 그대로 식별자가 된다"라는 생각이 Eve 설계 사상의 핵심입니다.

이 "디렉토리 = 에이전트"라는 발상을 Vercel CEO인 Guillermo Rauch 씨는 Next.js에 비유하고 있습니다.

그가 "Eve는 에이전트를 위한 Next.js다"라고 말하듯이, Eve에서는 Web에서 익숙했던 구도가 그대로 에이전트에 대응하도록 되어 있습니다.

React와 Next.js의 관계를 AI 라이브러리와 프레임워크에도 대입해 보면 이해하기 쉬울 것입니다.

React → ai-sdk: UI를 구성하는 '부품'이 React라면, 에이전트를 구성하는 부품이 AI SDK.

Next.js → Eve: React 위에 서는 프레임워크가 Next.js라면, AI SDK 위에 서는 것이 Eve.

AI SDK가 '부품'이고, Eve가 그 부품을 실제 서비스까지 운반하는 '프레임워크'라는 위치 선정입니다.

※ 이 역할 분담은 후반부의 'Eve와 Agent Stack'에서 다시 자세히 다룹니다.

최소 구성은 2개의 파일

Eve의 최소 구성은 agent.ts

과 instructions.md

두 개의 파일입니다.

이것만으로 에이전트를 구동할 수 있습니다.

이 파일들을 agent/ 디렉토리에 배치함으로써 에이전트를 구축합니다.

agent.ts에서는 모델과 실행 시 옵션을 정의합니다.

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

모델은 위와 같이 한 줄로 정의할 수 있으며, AI Gateway를 통해 provider fallback(모델 제공처(provider)가 다운되어도 다른 제공처로 자동 전환하여 계속 작동하는 메커니즘)도 지원됩니다.

compaction(대화 이력이 길어졌을 때의 자동 압축)이나 model options(temperature 등 모델 호출의 세부 설정) 등의 옵션은 필요할 때 추가하면 되는 설계입니다.

이번에 만든 기사 작성 에이전트에서는 비용과 속도의 균형을 고려하여 claude-haiku-4.5를 선택했습니다.

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

instructions.md에서는 에이전트의 행동을 정의합니다. 이 파일이 모델에 대한 시스템 프롬프트(System Prompt)가 되며, Eve는 모든 모델 호출 전에 이를 배치합니다.

You are a senior data analyst. You answer questions about the team's data.
- Prefer exact numbers to hand-waving. If you can compute it, compute it.
- State the assumptions behind any number you report (date range, filters, grain).
...

이번 프로젝트에서는 기사 라이터로서의 인격, 워크플로우, Notion 연동 절차를 instructions.md에 작성했습니다.

도구나 스킬을 추가할수록 instructions.md는 심플하게 유지할 수 있습니다. 이것이 Eve의 파일 트리(File Tree) 설계의 장점입니다.

그다음은 필요한 파일을 추가하기만 하면 됩니다. 새로운 도구를 추가하고 싶다면 agent/tools/에 TypeScript 파일을 만듭니다.

Eve가 기동 시 해당 파일을 자동으로 찾아 에이전트가 호출할 수 있도록 통합합니다. 도구를 어딘가 목록에 등록하거나 설정 파일을 수정하는 번거로움은 없습니다.

하나씩 파일을 추가하기

Eve에서는 "파일 1개 추가 = 기능 1개 추가"로 취급됩니다. 공식 블로그의 "Extend an agent one file at a time"에 따라 각 building block(구성 요소)을 살펴보겠습니다.

각 절에서는 공식 설명을 제시하면서, 이번 리포지토리에서의 처리 방식과 대조합니다.

agent/tools/*.ts (Tools)

Tools(Tool은 모델이 실행 중에 호출할 수 있는 타입 지정 액션(typed actions)입니다)입니다. 각 파일이 하나의 도구가 되며, 파일명이 도구 이름이 됩니다.

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

파일 경로가 Tool의 identity(식별자)입니다. 파일을 추가하는 것만으로 에이전트가 해당 도구를 호출할 수 있게 됩니다.

이번 프로젝트에서는 Zenn 형식의 markdown을 출력하는 emit_zenn_markdown Tool을 만들었습니다.

스키마 라이브러리는 Zod가 아닌 valibot을 사용하고 있습니다(개인적인 취향입니다).

따라서 toToolInputSchema라는 헬퍼 함수를 통해 valibot 스키마를 모델용 JSON Schema로 변환하고 있습니다.

import { defineTool } from "eve/tools";
import * as v from "valibot";
import { toToolInputSchema } from "#lib/schema.js";
...

import { toJsonSchema } from "@valibot/to-json-schema";
export function toToolInputSchema(
schema: Parameters<typeof toJsonSchema>[0],
...

needsApproval

Human-in-the-loop approval (위험한 조작이나 비용이 많이 드는 조작에는 사람의 승인을 거칠 수 있습니다).

공식 블로그에서는 SQL 쿼리의 스캔량에 따라 승인을 요구하는 예시가 제시되어 있습니다.

export default defineTool({
description: "Run a read-only SQL query against the warehouse.",
inputSchema: z.object({ sql: z.string() }),
...

needsApproval는 도구 정의(tool definition)의 한 필드이며, 이 필드를 통해 승인 요구를 정의합니다.

고액의 쿼리, 파괴적인 쓰기, 감독 없이 실행하고 싶지 않은 조작을 방어할 수 있습니다.

이번 emit_zenn_markdown에서는 동일한 기사(slug = 기사별 식별자)를 처음으로 작성할 때만 사람의 승인을 요구하도록 설정했습니다.

기사를 작성(emit)하는 것은 "공개를 위한 마지막 불가역적인 조작"임을 명시하고 싶었기 때문입니다.

import { defineState } from "eve/context";
const emittedMarkdown = defineState("article.emit_zenn_markdown", () => ({
bySlug: {} as Record<string, { markdown: string; path: string }>,
...

defineState를 통해 동일한 slug의 2회차 이후 작성을 억제하며, 한 번 승인된 markdown은 세션 내에서 재사용합니다.

CLI에서 y를 누르면 승인되며, 에이전트는 중단된 지점부터 재개합니다.

agent/skills/*.md

Skills (Skill은 온디맨드(on-demand)로 로드되는 거대한 프로시저("절차서" 및 "지식의 집합")입니다. 도메인 지식이나 복잡한 절차를 항상 켜져 있는 시스템 프롬프트(system prompt)에 넣는 대신, Skill의 형태로 준비해 둡니다).

공식 블로그에서는 revenue-definitions.md와 같은 비즈니스 도메인 지식의 예시가 제시되어 있습니다.

---
description: How this team defines revenue. Load before answering any revenue question.
---
...

마크다운(Markdown) 형식으로 되어 있으며, 에이전트가 load_skill을 통해 필요할 때만 읽어옵니다.

이번 프로젝트에서는 두 가지 Skill을 준비했습니다.

• article-structure.md — 기사의 섹션 구성 (문제 제기 → building blocks → 구현 예시 → 요약)
• zenn-style.md — 필자의 Zenn 문체 규칙 (데스·마스(です・ます) 체, emoji 제목, ## はじめに / ## まとめ 등)

복잡한 절차는 skills/에서 관리하고, instructions.md는 심플하게 유지함으로써 에이전트의 전체 구조를 파악하기 쉽게 만듭니다.

agent/subagents/

Subagents (Subagent는 부모 에이전트 내부에 있는 또 다른 에이전트(디렉토리)입니다. 각각은 고유한 instructions.md, tools/, sandbox를 가집니다).

부모(Main agent) 입장에서 Subagent를 호출하는 것은 일반적인 도구(Tool)를 하나 호출하는 것과 완전히 동일하며, 특별한 메커니즘은 필요하지 않습니다. 도구를 호출하는 느낌으로 업무를 통째로 맡길 수 있습니다.

import { defineAgent } from "eve";
export default defineAgent({
description: "분석가가 보고하기 전에 데이터의 이상 징후를 조사합니다.",
...

Subagent는 깨끗한 컨텍스트 윈도우 (Context Window)와 주어진 도구(Tool)만으로 작업하며, 결과를 부모(Main agent)에게 반환합니다.

이번에는 researcher (eve 공식 docs에서 사실, API, 인용구를 수집)와 reviewer (초안의 정확성과 Zenn 문체를 체크) 두 가지를 구현했습니다.

agent/subagents/
├── researcher/
│ ├── agent.ts
...

read_eve_docs 로직은 agent/lib/read-eve-docs.ts에 공유 구현하고, 각 Subagent의 tools/에는 얇은 래퍼 (Wrapper)를 두는 패턴을 채택하고 있습니다.

Eve는 Subagent의 Tool을 해당 디렉토리에서 해결(Resolve)하기 때문에, 파일 자체는 Subagent마다 필요합니다.

단, description, schema, handler의 실체는 lib 측에 모아두고, 각 래퍼는 그것을 import만 하도록 만들 수 있습니다.

예를 들어 researcher의 tools/read_eve_docs.ts는 공유 구현을 읽어오기만 하는 몇 줄의 코드뿐입니다.

import { defineTool } from "eve/tools";
import {
executeReadEveDocs,
...

researcher는 웹 검색을 사용하지 않고, 로컬의 node_modules/eve/docs만을 정보원으로 삼습니다.

docs가 부족한 경우에는 blocked를 반환하도록 하여, 추측해서 작성하지 않도록 의도적으로 설계했습니다.

agent/connections/*

Connections (Connections는 MCP 서버나 OpenAPI 문서 등을 통해 외부 API에 연결됩니다. 인증은 Eve의 런타임 (Runtime)이 대신 처리하므로, API 키나 인증 정보는 모델(에이전트의 두뇌인 LLM 본체)에는 전달되지 않으며, 모델이 받는 것은 호출 결과뿐입니다.)

이 사양은 외부 유출에 대한 대책이 됩니다.

모델에 전달한 프롬프트(Prompt)나 도구의 인자(Argument)·결과는 로그나 프롬프트 인젝션 (Prompt Injection, 외부에서 유입된 지시)을 통해 유출될 수 있으므로, 기밀 정보를 Eve 측에 머물게 하여 LLM의 눈에 닿지 않게 하는 설계입니다.

인증 정보를 안전하게 숨길 수 있는 것도 중요하지만, 여기서 주목하고 싶은 것은 그 이전의 이야기입니다.

"외부 서비스에 연결하는 것" 그 자체가 큰 수고라는 점에 초점을 맞추고자 합니다.

에이전트를 만드는 데 있어 가장 어려운 것은 에이전트 본체가 아니라 **데이터에 대한 액세스 (Access)**라고 Rauch 씨는 말합니다.

에이전트를 구축하는 가장 어려운 부분은 에이전트 그 자체를 구축하는 것이 아니다. 데이터다. 아이러니하게도 OAuth, 토큰, 인증 정보, 스코프(Scope) 등을 이해하는 것이다. Vercel Connect는 보안과 사용 편의성을 모두 해결한다.

이는 이번 프로젝트에서 몸소 경험했기에, 저 또한 "데이터에 대한 액세스"가 가장 어렵다고 느끼고 있습니다.

앞서 언급했듯이, 이번 에이전트 구축 과정에서 Notion 연동 기능을 구현했습니다.

처음에는 Notion의 MCP 서버에 연결하기 위해 OAuth 2.0을 직접 작성해 보았습니다.

PKCE 쌍 생성, Dynamic Client Registration, state, token endpoint로의 코드 교환, 취득한 토큰을 유지하는 KV 스토어. 이것만으로 agent/lib/에 약 300행이 쌓였습니다 [1].

이를 Vercel Connect로 교체하면, Connections의 정의는 다음과 같이 간단해집니다. API 키를 .env에 두는 방식이 아니라, OAuth로 사용자 인가를 수행하는 패턴입니다.

import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
...

auth: connect(...)

라는 단 몇 줄이, 직접 작성해야 했던 약 300줄의 코드를 통째로 대신해 줍니다.

수명이 짧고 스코프가 제한된 토큰을 Vercel이 발행 및 관리하며, 인증 정보는 .env 파일이나 모델에게도 전달되지 않습니다. Rauch 씨가 말한 "가장 어려운 것은 데이터"라는 말을, 고려해야 할 사항의 내용과 코드량의 차이로서 실감한 순간이었습니다.

agent/channels/*

Channels (Channels는 동일한 에이전트 실행으로 들어오는 입구입니다. HTTP, Slack, Discord, Teams, Telegram 등 여러 플랫폼을 통해 동일한 로직을 실행할 수 있습니다.)

공식적으로는 eve channels add slack 명령어 하나로 Slack 연동이 시작됩니다.

eve channels add slack

명령어가 channels/slack.ts를 생성하며, 배포된 에이전트가 Slack에서 응답하게 됩니다.

승인은 Slack 버튼으로 표시되고, 질문은 셀렉트 메뉴(Select Menu)로 표시됩니다.

Vercel Connect를 통해 인증 정보를 라우팅하면, bot token을 .env에 복사할 필요도 없습니다.

Channels는 에이전트의 UI이며, 세션은 채널 간에 이동할 수 있습니다. Slack에서 시작한 대화를 Web에서 이어가거나, HTTP webhook으로 받은 인시던트(Incident)를 Slack 스레드에서 완결 지을 수 있습니다.

이번 프로젝트에서는 기본 HTTP / dev 터미널 채널(eve.ts)만 사용했습니다. 저 혼자만 사용하는 CLI 도구이므로, 여러 사용자를 처리할 필요가 없어 이와 같이 구성했습니다.

import { type AuthFn, extractBearerToken, localDev, verifyVercelOidc } from "eve/channels/auth";
import { eveChannel } from "eve/channels/eve";
const operatorUser = {
...

보충하자면, channel auth는 조금 특수합니다.

Notion의 OAuth는 "사용자 단위"로 인가되므로, 인증이 통과된 액세스를 모두 동일한 한 명의 operator 사용자로 집약하여 Notion 인가가 한 번만 이루어지도록 하고 있습니다.

일반적인 멀티 유저 서비스라면 호출자마다 별도의 사용자로 취급하겠지만, 이번에는 저 혼자만 사용하는 도구이기 때문에 싱글 오퍼레이터(Single Operator)를 전제로 한 형식을 취하고 있습니다.

agent/schedules/*

Schedules (Schedules는 cron 잡(Job)처럼 에이전트를 정기적으로 실행시키는 슬롯(Slot)입니다. "월요일 매출 보고서를 누군가 물어보기를 기다리지 않고 자동으로 게시한다"와 같은 용도로 사용합니다.)

import { defineSchedule } from "eve/schedules";
import slack from "../channels/slack.js";
export default defineSchedule({
...

Vercel에 배포하면 Vercel Cron Job으로서 동작하며, 매주 월요일에 아무도 기억하지 못하더라도 보고서가 게시됩니다.

이번 기사 작성 에이전트에서는 schedules/는 미구현 상태입니다. 개념 설명에만 그치고 있습니다.

agent/hooks/* — 해설만

Hooks (Hooks는 에이전트의 런타임(Runtime)이 흘려보내는 이벤트 스트림(Event Stream)을 구독하고, 각 이벤트가 내구력 있게(Durable) 기록된 후에 사이드 이펙트(Side Effect)를 실행하는 슬롯입니다.)

쉽게 말하면, 특정 이벤트가 발생한 타이밍(세션이 시작되었을 때, 모델이 답변을 마쳤을 때 등)에 Hook에 정의한 코드를 실행하는 메커니즘입니다.

감사 로그(Audit logs), 메트릭스(Metrics) 및 알림(Alerts), 세션(Sessions)이나 메시지(Messages)를 자신의 DB에 저장하여 분석하는 등의 용도로 사용합니다. session.started나 message.completed와 같은 이벤트마다 핸들러(Handler)를 정의할 수 있습니다.

import { defineHook } from "eve/hooks";
export default defineHook({
events: {
...

Hooks는 observe-only(보기만 할 뿐, 모델의 판단이나 답변 자체를 수정하지는 않음) 방식으로 동작하며, 모델에 컨텍스트(Context)를 주입할 수는 없습니다.

Schedules가 '언제 실행될지'를 더하는 슬롯(Slot)이라면, Hooks는 '실행된 후에 무엇을 관측·기록할지'를 더하는 슬롯이라고 정리할 수 있습니다.

이 기능 또한 이번에는 미구현 상태이며, 개념 소개에 그칩니다.

Tool의 무효화

Eve에는 Tool을 무효화하는 함수가 제공됩니다.

이번 프로젝트에서는 의도적으로 web_search / web_fetch를 무효화하고 있습니다.

무효화는 disableTool()을 호출하는 것만으로 수행할 수 있습니다.

예를 들어, researcher Subagent의 web_fetch를 무효화하는 경우, tools 디렉토리에 파일명으로 web_fetch를 지정하고, disableTool()을 디폴트 익스포트(Default export)하기만 하면 무효화가 완료됩니다.

import { disableTool } from "eve/tools";
export default disableTool();

Durable sessions (지속적 세션)

에이전트는 사람을 기다리거나, 느린 시스템을 호출할 때 등 몇 시간, 몇 일, 혹은 몇 주 동안 계속 작동할 수 있습니다.

Eve에서는 모든 대화가 durable workflow(지속적 워크플로우)로 취급되며, 각 단계의 완료 시점이 매번 저장(체크포인트, Checkpoint)됩니다.

세션은 임의의 시점에서 중단할 수 있으며, 크래시(Crash)나 배포(Deploy)를 거치더라도 정확히 동일한 지점에서 재개할 수 있습니다.

이러한 durability(내구성)는 오픈 소스 Workflow SDK 상에 구축되어 있습니다.

이번 기사 작성 에이전트에서는 다음 두 곳에서 durable session의 혜택을 체감했습니다.

• Notion OAuth: 첫 번째 Notion 호출 시 브라우저 인가(Authorization)가 필요하며, 인가가 완료될 때까지 에이전트가 대기했다가 재개함
• emit 승인: emit_zenn_markdown의 needsApproval 설정에 따라 사람이 y를 누를 때까지 대기했다가, 승인 후에 계속 진행함

Sandboxed compute (샌드박스)

파일 쓰기, 코드 실행, 쉘 커맨드(Shell command) 실행은 모두 격리된 workspace(워크스페이스)에서 동작합니다.

샌드박스는 에이전트에게 제어된 환경을 제공하며, 호스트 시스템(Host system)을 노출하지 않습니다.

import { defineSandbox, defaultBackend } from "eve/sandbox";
export default defineSandbox({
backend: defaultBackend(),
...

샌드박스는 실제로 코드나 파일 조작을 수행할 '실행 장소(Backend)'를 필요로 합니다. defaultBackend()는 해당 실행 장소를 환경에 따라 자동으로 선택해 주는 헬퍼(Helper)입니다.

Vercel에 배포했을 때(hosted)는 클라우드 상의 격리 환경인 Vercel Sandbox를 사용하고, 로컬에서 eve dev를 실행할 때는 자신의 머신 환경을 사용합니다.

코드 한 줄만 작성하면 프로덕션(Production)에서도 로컬에서도 동일하게 동작합니다.

emit_zenn_markdown은 sandbox에 articles/<slug>.md를 작성합니다.

단, hosted 환경의 sandbox 파일은 ephemeral(휘발성)이어서 처리가 끝나면 삭제되며, 로컬 머신에서는 직접 읽을 수 없습니다.

따라서 툴은 완성된 markdown을 인라인(Inline)으로 반환하도록 하여, 이를 복사해서 사용할 수 있게 구성했습니다.

Evals (평가)

에이전트의 동작을 측정할 수단 없이 출시하는 것은 추측에 의존하는 것과 다를 바 없습니다. Eve에는 eval(평가) 메커니즘이 처음부터 내장되어 있어, 실제 HTTP를 통해 에이전트를 구동하고 돌아온 결과를 채점합니다.

import { defineEval } from "eve/evals";
import { includes } from "eve/evals/expect";
export default defineEval({
...

eval은 eve eval로 실행할 수 있으며,

체크(assertion)에는 gate와 soft 두 종류가 있습니다.

gate (필수 달성) 는, 충족하지 못하면 테스트가 실패로 처리되어 CI (지속적 통합)를 중단시키는 assertion입니다.

soft (경과 관측) 는, 실패시키지 않고 스코어만 기록하여 품질이 조금씩 저하되고 있는지(drift, 드리프트)를 추적하는 assertion입니다.

Eve와 Agent Stack — AI SDK와 무엇이 다른가

지금까지 살펴본 지속적 실행 (durable execution), 인간의 개입 (human-in-the-loop), 샌드박스 (sandbox), 평가 (evals)는 각각 따로 준비된 별개의 기능이 아닙니다.

모두 공통된 토대 위에 올라가 있습니다. Vercel은 에이전트에 필요한 요소들을 다음과 같이 분해하며, 그 토대를 통칭하여 Agent Stack이라고 부릅니다.

모든 에이전트에는 스트리밍 (streaming), 모델 (model), 내구성 (durability), 격리 (isolation), 채널 (channel), 통합 (integration)이 필요합니다.