Vercel Eve：文件系统优先的持久化 Agent 框架

Vercel 最近开源了 eve，一个用于构建、运行和扩展 Agent 的框架。项目在 GitHub 上已经获得了超过 2,800 个 star，是近期 Agent 基础设施领域最受关注的项目之一。

核心理念：文件系统即接口

eve 的设计哲学可以用一句话概括：Agent 的能力通过文件系统的约定位置自描述，无需显式注册。

一个典型的 eve Agent 目录结构如下：

my-agent/
└── agent/
    ├── agent.ts            # 模型和运行时配置
    ├── instructions.md     # 常驻系统提示词
    ├── tools/              # 模型可调用的类型化函数
    │   └── get_weather.ts
    ├── skills/             # 按需加载的知识/流程
    │   └── plan_a_trip.md
    ├── channels/           # 消息通道（HTTP、Slack、Discord）
    │   └── slack.ts
    ├── subagents/          # 子 Agent 委托
    │   └── researcher/
    ├── connections/        # 外部 MCP/OpenAPI 服务
    │   └── linear.ts
    ├── schedules/          # 定时任务
    │   └── weekly_recap.ts
    └── sandbox/            # 沙箱配置
        └── sandbox.ts

文件的位置即定义。agent/tools/get_weather.ts 自动注册为 get_weather 工具，无需额外配置。这种「约定优于配置」的设计让 Agent 项目天然可读——看一眼目录树就知道这个 Agent 能做什么、住在哪里、什么时候自主行动。

持久化执行：会话即工作流

eve 的会话是持久化工作流，基于开源的 Workflow SDK 构建：

• Step 级检查点：每个模型调用和工具调用都是一个 durable checkpoint
• 崩溃恢复：进程重启或重新部署后，会话从最后一个完成的 step 恢复，而非重放整个 turn
• Park 机制：等待人工审批、OAuth 回调或子 Agent 完成时，工作流挂起且不消耗计算资源
• 跨部署连续性：生产部署更新后，现有会话的下一个 turn 使用新版本的指令和工具，但保留对话历史

这意味着一个 Agent 会话可以运行数天甚至数周，无需担心进程崩溃或部署中断。

沙箱：Agent 的隔离执行环境

每个 Agent 都有一个独立的沙箱，文件系统根目录为 /workspace：

沙箱与 Agent 的运行时完全隔离，Agent 生成的代码不会触及应用运行时。支持四种后端：

人机循环：审批即暂停

eve 内置了人机循环（Human-in-the-loop）机制：

export default defineTool({
  description: "Refund a charge.",
  inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
  approval: always(), // 或 once() / never() / 自定义策略
  async execute(input) {
    return refund(input);
  },
});

任何工具都可以配置审批策略。当触发审批时，会话暂停，等待人工确认后从断点恢复。这在处理敏感操作（退款、数据删除、大额查询）时至关重要。

子 Agent：两种委托模式

1. 内置 agent 工具

每个 Agent 默认获得一个 agent 工具，可以委托子任务给自身的副本：

• 共享父 Agent 的沙箱和工具
• 独立的对话历史和状态
• 支持并行调用：一次响应中发出多个 agent 调用，并发执行

2. 声明式子 Agent

在 agent/subagents/<id>/ 下定义独立的子 Agent：

• 独立的指令、工具、连接、技能和沙箱
• 完全隔离，不继承父 Agent 的任何配置
• 通过目录名注册为工具（如 researcher）

技能：按需加载的知识

Skills 遵循 SKILL.md 约定，是模型按需加载的指令：

---
description: Research unfamiliar topics before answering with confidence.
---

When the task is novel or ambiguous, gather evidence first...

• eve 扫描 agent/skills/ 下的文件，将描述暴露给模型
• 模型通过 load_skill 工具按需加载
• 支持纯 Markdown 和 TypeScript 定义的 defineSkill
• 遵循 Agent Skills 标准，可跨框架移植

通道：同一 Agent，多平台服务

eve 支持将同一 Agent 部署到多个平台通道：

每个通道是一个小型适配器文件，Agent 的行为在所有通道上保持一致。

定时任务：Agent 自主行动

export default defineSchedule({
  cron: "0 9 * * 1",
  async run({ receive, waitUntil, appAuth }) {
    waitUntil(
      receive(slack, {
        message: "Summarize last week's revenue and post it.",
        target: { channelId: "C0123ABC" },
        auth: appAuth,
      }),
    );
  },
});

• 标准 5 字段 cron 表达式
• 支持 fire-and-forget（Markdown 形式）和 handler 形式
• Vercel 上自动转化为 Vercel Cron Job
• 自托管时通过 Nitro 调度任务运行

评估：测试即代码

eve 提供 defineEval 定义可重复的评分检查：

export default defineEval({
  description: "Basic message and tool-usage coverage.",
  async test(t) {
    await t.send("What is the weather in Brooklyn?");
    t.succeeded();
    t.calledTool("get_weather");
    t.check(t.reply, includes("Sunny"));
  },
});

• 三种断言面：确定性断言、t.check()、LLM-as-judge
• 支持 mockModel 用于确定性测试
• 可集成 Braintrust 等第三方评估平台
• CI 中运行 eve eval --strict 作为部署门禁

部署：同一代码，多环境运行

# 本地开发
eve dev

# 构建
eve build

# Vercel 部署
vercel deploy

# 自托管
eve build && PORT=3000 eve start --host 0.0.0.0

• 本地、Vercel 和自托管环境运行方式一致
• Workflow SDK 的 local world 默认将状态持久化到 .workflow-data
• 支持自定义 Workflow world（如 PostgreSQL 后端）
• 反向代理需转发 /eve/ 和 /.well-known/workflow/ 两个前缀

Vercel 的生产实践

Vercel 内部运行了超过 100 个 eve Agent，包括：

快速开始

npx eve@latest init my-agent
cd my-agent
npm run dev

完整的文档内置于 npm 包中：node_modules/eve/docs/。

相关资源

• GitHub: https://github.com/vercel/eve
• 文档: https://eve.dev/docs
• 博客: https://vercel.com/blog/introducing-eve
• npm: npm install eve@latest