eve：Vercel 用文件系统重新定义 AI Agent 开发

四天前，Vercel 开源了 eve —— 一个「文件系统优先」的 AI Agent 框架。1700+ 星标、37 个 PR、26 个 Issue，社区讨论热度直接拉满。它不写一个巨大的配置对象，而是把 Agent 的每一个能力都变成文件系统里的一个文件：instructions.md 是系统提示词，tools/ 放工具函数，skills/ 放按需加载的技能，channels/ 接入 Slack 和 Discord。你往目录里丢一个 .ts 文件，eve 自动发现并注册它。

这不是又一个「封装 LLM 调用」的玩具。eve 把持久化会话、沙箱隔离、子代理编排、定时任务这些生产级能力全部内建，底层用 Workflow SDK 保证崩溃后能恢复。如果你正在考虑给自己的产品加一个 Agent 后端，eve 可能是目前最值得试的选项。

一、为什么 Vercel 要做一个 Agent 框架

Vercel 在前端部署领域已经是事实标准，但 AI Agent 的兴起让它看到了新的增长点。过去一年，LangGraph、CrewAI、AutoGen 等框架层出不穷，但它们大多是 Python 生态，且普遍存在几个痛点：

• 配置散落在代码各处，新成员看一个 Agent 项目要翻半天
• 会话持久化需要自己搭 Redis/Postgres，崩溃恢复更是 DIY
• 没有内置的沙箱隔离，Agent 执行 shell 命令时安全性全靠自觉
• 渠道接入（Slack、Discord、Web）每个都要从头写

eve 的出现，本质上是 Vercel 把自己在「部署 + 运行时」领域的积累，打包成了一个 Agent 框架。它用 TypeScript 写，天然适配前端生态；用文件系统约定替代配置注册，降低认知负担；用 Workflow SDK 做持久化，让开发者不用关心状态管理。

二、文件系统优先：目录结构即架构

eve 最大的设计哲学是「文件系统即接口」。一个典型的 eve Agent 项目长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

my-agent/
├── package.json
└── agent/
    ├── agent.ts            # 运行时配置（模型选择）
    ├── instructions.md     # 系统提示词（Required）
    ├── tools/              # 工具函数
    │   └── get_weather.ts
    ├── skills/             # 按需加载的技能
    │   └── plan_a_trip.md
    ├── channels/           # 消息通道
    │   └── slack.ts
    ├── subagents/          # 子代理
    │   └── researcher/
    ├── schedules/          # 定时任务
    │   └── weekly_recap.ts
    └── connections/        # 外部 MCP 服务
        └── github.ts

每个目录的名称就是它的功能，文件名就是注册名。你不需要在任何地方声明「我有一个叫 get_weather 的工具」——只要在 tools/ 下创建 get_weather.ts 并 export default defineTool(…)，eve 就会自动发现它。

这种设计有几个实际好处：

1. 看目录就能理解 Agent 能做什么。新人接手项目，扫一眼 agent/ 目录就够了
2. 添加能力 = 添加文件。不需要修改任何注册表或配置文件
3. 删除能力 = 删除文件。不会有残留的注册代码导致运行时报错
4. Git diff 天然清晰。每个能力的变更都是独立的文件变更

三、核心概念拆解

3.1 Instructions：永远在线的系统提示词

agent/instructions.md 是唯一必须存在的文件。它的内容就是 Agent 的系统提示词，每次对话都会被注入：

1

你是一个简洁的天气助手。告诉用户天气数据是模拟的。

你可以用 Markdown 写，也可以用 TypeScript 写（instructions.ts），后者可以在运行时动态生成提示词。

3.2 Tools：模型可以调用的函数

工具是 Agent 与外部世界交互的桥梁。eve 的工具定义非常简洁：

1
2
3
4
5
6
7
8
9
10

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "获取城市的天气数据。",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "晴", temperatureF: 72 };
  },
});

文件名 get_weather.ts 就是工具名。eve 还支持 Human-in-the-Loop（HITL）：你可以给工具加上 needsApproval，让每次调用都需要人工确认。

3.3 Skills：按需加载的技能包

技能是 eve 的渐进式上下文管理机制。和工具不同，技能不会每次都出现在模型的上下文里——它只在需要时才被加载：

1
2
3
4
5
6

---
description: 当用户需要旅行规划时使用此技能。
---

在回答旅行相关问题前，先用天气工具查询目的地天气，
再根据天气推荐合适的活动。

eve 会把技能的 description 暴露给模型，模型判断需要时调用 load_skill，eve 才把完整的 Markdown 内容注入上下文。这种「渐进式披露」设计可以有效控制上下文长度。

技能还支持打包目录（SKILL.md + references/ + assets/），适合复杂的多步骤流程。

3.4 Channels：多渠道接入

eve 内置了 HTTP 通道（每个应用都有），还支持 Slack、Discord 等平台。添加一个 Slack 通道只需要：

1

npx eve channels add slack

你的 Agent 工具不需要知道消息来自浏览器还是 Slack——eve 把所有平台输入统一转换为消息格式，工具逻辑完全解耦。

3.5 Sandbox：隔离的执行环境

eve 内置了四种沙箱后端：

模型通过内置的 bash、read_file、write_file、glob、grep 工具操作沙箱。你也可以在自定义工具里通过 ctx.getSandbox() 获取沙箱句柄，执行更复杂的操作。

沙箱还支持网络策略（allow-all / deny-all / 域名白名单）和凭证代理（secrets 不进入沙箱，而是在防火墙层注入），这对生产环境的安全性至关重要。

3.6 Subagents：子代理编排

eve 支持两种子代理：

内置 agent 工具：每个 Agent 默认都有一个 agent 工具，模型可以调用它把子任务委托给自身的副本。副本共享父代理的沙箱和工具，适合并行处理多个文件。

声明式子代理：在 agent/subagents/ 下创建独立目录，每个子代理有自己的 instructions、tools、skills、sandbox。适合需要不同角色或工具表面的场景。

1
2
3
4
5

agent/subagents/researcher/
├── agent.ts            # 必须包含 description
├── instructions.md     # 子代理的系统提示词
├── tools/              # 子代理专属工具
└── sandbox/            # 子代理专属沙箱

声明式子代理与父代理完全隔离——不继承任何东西。如果两个子代理需要相同的技能，需要在各自的 skills/ 目录下各放一份。

3.7 Schedules：定时任务

eve 支持 cron 风格的定时任务，放在 agent/schedules/ 下。适合每日报告、定期数据采集等场景。定时任务只能在根代理中定义，子代理不支持。

3.8 Durable Sessions：持久化会话

eve 底层用 Workflow SDK 做会话持久化。这意味着：

• 会话可以在模型调用之间暂停和恢复
• 支持 Human-in-the-Loop：模型可以暂停等待人工输入
• 崩溃后可以从断点恢复，不会丢失上下文
• 每个会话的文件系统状态在 turn 之间保持不变

四、快速上手

1
2
3
4
5
6
7
8

# 创建新 Agent
npx eve@latest init my-agent

# 进入项目目录
cd my-agent

# 启动开发服务器（带交互式终端 UI）
npm run dev

eve init 会自动创建目录结构、安装依赖、初始化 Git。开发终端 UI 支持直接输入消息测试 Agent。

HTTP API

eve 暴露统一的 HTTP 接口：

1
2
3
4
5
6
7
8
9
10
11
12

# 创建会话
curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"北京今天天气怎么样？"}'

# 流式监听会话事件
curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream

# 发送后续消息
curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
  -H 'content-type: application/json' \
  -d '{"continuationToken":"<token>","message":"那上海呢？"}'

流式响应是 NDJSON 格式，包含 session.started、actions.requested、action.result、message.completed、session.completed 等事件。

五、与其他框架的对比

eve 和 LangGraph、CrewAI 的最大区别在于设计理念：

• LangGraph 用图（Graph）编排 Agent 流程，灵活但学习曲线陡峭
• CrewAI 用角色（Crew）组织 Agent 协作，适合多角色场景
• eve 用文件系统组织 Agent 能力，强调「看目录就懂」

在工程化能力上，eve 的优势比较明显：内置持久化（不需要自己搭 Redis）、内置沙箱（不需要自己管 Docker）、内置多渠道（不需要自己写 Webhook）。这些都是 LangGraph 和 CrewAI 需要开发者自己实现的。

但 eve 也有局限：它目前只支持 TypeScript，Python 生态的丰富工具链（PyTorch、LangChain 等）无法直接使用。而且它还处于 beta 阶段，API 可能变化。

六、eve 与 Vercel 生态的整合

eve 天然适配 Vercel 的部署体系：

• 沙箱后端默认在 Vercel 上使用 Vercel Sandbox（云端 VM）
• 模型路由默认通过 Vercel AI Gateway
• 部署就是 git push，Vercel 自动构建

但 eve 也可以完全脱离 Vercel 运行——它是一个开源 npm 包，可以在任何 Node.js 环境中使用。沙箱后端支持 Docker、microsandbox，甚至纯 JS 的 just-bash 回退。

七、局限性与注意事项

1. Beta 阶段：eve 目前是 beta 版本，API 和行为可能在 GA 前变化
2. TypeScript only：不支持 Python，无法直接使用 PyTorch 等 ML 工具链
3. Node 24+：需要较新的 Node.js 版本，部分 CI/CD 环境可能不支持
4. 文档自包含：eve 把完整文档打包在 npm 包里（node_modules/eve/docs/），方便 coding agent 本地读取，但也意味着文档更新需要升级包版本
5. Vercel 倾向：虽然可以脱离 Vercel 运行，但最佳体验（沙箱、AI Gateway、部署）还是在 Vercel 生态内

八、写在最后

eve 不是又一个「封装 LLM API」的框架。它试图解决的是 AI Agent 从原型到生产的工程化问题：怎么管理越来越多的工具和技能？怎么做会话持久化和崩溃恢复？怎么安全地执行代码？怎么接入多个消息平台？

文件系统优先的设计哲学虽然简单，但非常有效——它让 Agent 项目的结构一目了然，降低了团队协作的认知成本。如果你是 TypeScript 生态的开发者，正在寻找一个生产级的 Agent 框架，eve 值得认真考虑。

目前 eve 刚开源四天，社区还在快速成长。如果你对 Agent 开发感兴趣，现在正是参与的好时机。

相关链接：

• eve GitHub 仓库
• eve 官方文档
• npm 包
• Vercel AI Gateway
• Workflow SDK