Vercel 开源 eve：一个目录就是一个 Agent

Vercel 最近开源了 eve，一个文件系统优先的 TypeScript Agent 框架。它想解决一个越来越普遍的问题：现在人人都能用 AI 写出一个 agent，但每个团队都在重复造同一套基础设施——状态持久化、沙箱执行、审批流、接入 Slack、追踪和 eval。eve 把这些全部内建，目标是成为 "Agent 界的 Next.js"。

项目简介

eve 是 Vercel 开源的 agent 框架，用于构建、运行和扩展生产级 agent。它的核心设计思想是：一个 agent 应该是一个目录，里面每个文件描述 agent 的一个方面，框架负责把它们自动组装成可运行的系统。

和 Next.js 把路由约定变成文件系统一样，eve 把 agent 的能力也变成文件系统：

• agent.ts 定义模型
• instructions.md 定义身份和规则
• tools/ 定义它能做什么
• skills/ 定义它知道什么
• subagents/ 定义它委托给谁
• channels/ 定义它在哪里与用户交互
• schedules/ 定义它什么时候自动运行

核心特性

• 文件系统即定义：一个目录就是一个 agent，文件名和位置即能力声明
• 持久化执行：每个会话是 durable workflow，可断点续跑、 survive 部署和崩溃
• 沙箱隔离：agent 生成的代码在独立沙箱运行，不污染应用运行时
• 人工审批：任意工具调用可配置 needsApproval，agent 会暂停等待人工确认
• 子代理：一个 agent 可以调用 subagents/ 下的子 agent，各自有独立上下文和工具
• 多通道：同一个 agent 可同时服务 HTTP、Slack、Discord、Teams、Telegram、GitHub、Linear
• 追踪与 Eval：每次运行生成 OpenTelemetry trace，可用 Braintrust、Honeycomb、Datadog 等接收；eval 可本地运行或接入 CI
• MCP 连接：通过 connections/ 文件接入任何 MCP server 或 OpenAPI 服务
• Vercel 原生部署：vercel deploy 即可部署，生产环境和本地开发行为一致

技术栈

• 语言：TypeScript
• 运行时：Node.js（Vercel / Docker / microsandbox / just-bash 本地适配）
• 模型：通过 AI SDK 支持任意模型，默认示例使用 anthropic/claude-opus-4.8
• 持久化：基于 Vercel Workflow SDK 的 durable execution
• 认证连接：Vercel Connect（OAuth、token refresh）
• 可观测性：OpenTelemetry，兼容主流 tracing 服务
• 沙箱：本地 Docker / microsandbox / just-bash；生产 Vercel Sandbox

安装指南

前置要求

• Node.js 18+
• 一个 Vercel 账号（用于部署，可选）

创建第一个 agent

npx eve@latest init my-agent

这条命令会：

1. 创建项目目录
2. 安装依赖
3. 初始化 Git
4. 启动本地 dev server

初始化完成后，目录结构大致如下：

my-agent/
  agent/
    agent.ts
    instructions.md
  tools/
  skills/
  subagents/
  channels/
  schedules/

快速开始

1. 定义 agent

编辑 agent/agent.ts：

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
});

2. 编写系统提示

编辑 agent/instructions.md：

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.
- Use the tools available to you rather than guessing.

3. 添加第一个工具

创建 agent/tools/run_sql.ts：

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

export default defineTool({
  description: "Run a read-only SQL query.",
  inputSchema: z.object({
    sql: z.string().describe("A single read-only SELECT statement."),
  }),
  async execute({ sql }) {
    // 调用你的数据库查询逻辑
    return { rows: [] };
  },
});

4. 本地运行

eve dev

然后直接在终端 UI 里和 agent 对话：

> What was revenue last week?

⦿ load_skill revenue-definitions
⦿ run_sql
  SELECT date_trunc('week', created_at) ...

Revenue for the week of June 1 was $4.2M net of refunds, up 6% from the prior week.

使用示例

示例 1：为危险操作添加人工审批

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

export default defineTool({
  description: "Run a SQL query against the warehouse.",
  inputSchema: z.object({ sql: z.string() }),
  needsApproval: ({ toolInput }) => estimateScanGb(toolInput.sql) > 50,
  async execute({ sql }) {
    // 执行查询
  },
});

当扫描数据量超过 50GB 时，agent 会自动暂停并请求人工审批。

示例 2：让 agent 自己写代码并运行

> Break last week's revenue down by region and chart it

⦿ write_file analysis/by_region.py
⦿ bash
  python analysis/by_region.py

Revenue by region for the week of June 1. AMER $2.1M, EMEA $1.6M, APAC $0.5M.
Chart saved to analysis/by_region.png.

eve 给 agent 一个真实的沙箱环境，agent 可以写脚本、运行 bash、处理数据集。

示例 3：接入 Slack

eve channels add slack

生成 channels/slack.ts 后部署即可。同一个 agent 可以同时服务多个渠道，会话还能在不同渠道间转移。

示例 4：定时任务

创建 agent/schedules/monday-summary.ts：

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

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

API 参考

defineAgent(options)

定义一个 agent。

defineTool(options)

定义一个工具。

defineSchedule(options)

定义定时任务。

defineMcpClientConnection(options)

定义 MCP 连接。

Vercel 内部怎么用

Vercel 自己已经把 100 多个 agent 跑在 eve 上，包括：

• d0：数据分析师 agent，每月回答 30,000+ 问题
• Lead Agent：自主 SDR，每年成本约 $5,000，回报 32 倍
• Athena：销售驾驶舱，六周建成，pipeline coverage 几乎翻倍
• Vertex：客服 agent，独立解决 92% 工单
• draft0：内容 agent，预审文章并提炼核心主题
• V：路由 agent，把用户请求分发给合适的 agent

这些 agent 共享同一个 monorepo、同一套部署和观察方式。

注意事项

• eve 目前 public preview 已开放，生产部署默认到 Vercel，其他平台支持在路线图中。
• 沙箱后端是 adapter 模式，本地和生产可无缝切换。
• 模型通过 AI SDK 接入，不绑定单一供应商。
• 每个会话是 durable workflow，适合长时运行任务，但要留意任务设计，避免无限等待。
• 人工审批虽然安全，但会阻塞会话，需设计好审批流程。

项目链接

• 官方文档：https://eve.dev/docs
• GitHub 仓库：https://github.com/vercel/eve
• 博客原文：https://vercel.com/blog/introducing-eve
• 开始使用：npx eve@latest init my-agent