vercel/eve: The Filesystem-First Framework That Treats AI Agents Like Real Software
A deep dive into how `eve` uses directories, tools, channels, approvals, schedules, and sandboxes to turn agent behavior into something you can ship and operate.
- `eve` argues that an agent should be defined by files on disk, not by a prompt blob or a hidden orchestration layer.
- Its real novelty is operational, because tools, approvals, channels, and schedules make agent behavior inspectable and durable.
- The framework treats safety and identity as first-class concerns, which is what makes it feel closer to software infrastructure than a chatbot demo.
- Vercel’s bet is that agents become easier to ship when they inherit the same conventions developers already use to manage codebases.
An agent is a directory
The simplest way to understand `eve` is to stop thinking about prompts. In this model, the agent lives in a folder, and the folder is the interface. `instructions.md` is always present, `tools/` defines executable capabilities, and `skills/` adds on-demand procedures the agent can load when the task calls for it.
That is a cleaner mental model than a pile of prompt templates and glue code. The developer edits files, reviews diffs, and reasons about behavior the same way they would in any other codebase.
Why this beats prompt spaghetti
`eve` is interesting because it makes agent behavior legible. If capability lives in a file, then capability can be searched, reviewed, versioned, and deleted. That is a big step up from prompt spaghetti, where the real logic often hides inside long strings and informal conventions.
| Question | Prompt-heavy agent stack | eve |
|---|---|---|
| Where does behavior live? | Scattered across prompts and glue code | In conventional files and directories |
| How do you review changes? | By reading long prompt diffs | By reading normal code and markdown diffs |
| How do you extend it? | Add more orchestration around the prompt | Add a tool, skill, or instruction file |
| How easy is it to operate? | Hard to inspect after the fact | Designed to be inspectable and composable |
Core agent capabilities live in conventional locations, so projects are easier to inspect, extend, and operate.
import { defineTool } from 'eve/tools'
import { z } from 'zod'
export const getWeather = defineTool({
name: 'get_weather',
description: 'Fetch current weather for a city',
inputSchema: z.object({ city: z.string() }),
needsApproval: true,
async run({ city }) {
return { city, forecast: 'sunny' }
},
})How defineTool and approvals keep agents safe
The tool layer is where `eve` stops being cute. Tools are typed, schema-validated, and can require human approval before they run. That matters because an agent that can call functions is useful, but an agent that can call functions safely is shippable.
The fixture code in the repo shows the shape clearly: a tool is not a free-form message to a model, it is an explicit contract with validation and a permission boundary. The model can request action, but it does not get to skip the gate.
The channel layer turns an agent into a service
Channels are the other half of the product story. `eveChannel` maps the agent to a real entry point, then ties that entry point to auth and principal identity. In plain terms, the agent knows who it is talking to, and that identity can travel through the workflow.
That is a different promise from a local CLI agent or a notebook demo. It means the agent can sit inside a web app, respond as a service, and keep its operational context aligned with the user session that triggered it.
| Capability | Local agent script | eve channel layer |
|---|---|---|
| Identity | Implicit or manual | Mapped from auth into principal context |
| Surface | Terminal or notebook | Web app or product surface |
| Access control | Ad hoc | Built into the channel boundary |
| Operational role | One-off runner | Persistent service endpoint |
The filesystem is the authoring interface A typical eve agent has this structure: Read the documentation for the full project layout and guides.
Durability is the actual differentiator
This is the section where `eve` earns its claim. The repo does not just point at tool calling. It points at schedules, subagents, sandbox metadata, and lifecycle state that suggest an agent can pause, resume, and coordinate across time.
That matters more than raw model cleverness. A durable agent is not a single response. It is a process that can wake up from a schedule, recover context, re-enter a channel, and continue with the same identity and constraints it had before.
Where `eve` sits in the agent framework landscape
The comparison that matters is not feature bingo. It is the organizing principle. LangGraph is graph-first. AutoGen is conversation-first. OpenAI Assistants is service-first. Vercel AI SDK is library-first. `eve` is filesystem-first.
| Project | Primary abstraction | Best fit | Operational posture |
|---|---|---|---|
| LangGraph | Graph of states and transitions | Complex orchestration | Flexible, but graph-centric |
| Vercel AI SDK | Library for building AI apps | Web app developers | Lean and code-first |
| AutoGen | Multi-agent conversation | Research and collaboration | Agent-centric and experimental |
| OpenAI Assistants | Managed assistant service | Teams that want hosted persistence | Platform-dependent |
| eve | Directory of agent files | Developers shipping durable agents | Deployable, inspectable, operational |
That makes `eve` unusual, but also legible. If you already think in folders, modules, and deployable services, the abstraction lands immediately.
What the repo says about Vercel’s bet
The monorepo layout matters. Turborepo, framework adapters, fixtures, docs, linting via the modern `oxc` toolchain, and E2E evaluation all point to a serious platform bet. This is not a toy package dropped into the ecosystem for novelty.
The larger message is that agents are being treated as a first-class app primitive. Vercel seems to be asking a simple question: what if the thing you ship is not a prompt chain, but a software artifact with files, identity, permissions, and runtime hooks?