使用 Vercel 的 Eve 框架构建智能体

Vercel 最近发布了 Eve，一个用于构建、运行和扩展智能体的开源框架。其核心理念是：你不再需要每次从头搭建智能体的底层基础设施，而是将智能体视为可以从磁盘读取的东西。接下来是基于我们刚刚为此构建的免费动手实验，介绍 Eve 的实际含义、为何重要以及实际构建的样子。下面你读到的是我在用 Eve 工作一周后（借助 Claude 撰写）的一些思考。如果你想无需任何配置直接试用 Eve，我们提供了一个免费的动手实验，你可以在实时终端中驱动真实的 eve CLI，无需自己的 API 密钥。你可以在这里尝试：Eve 入门指南。

Eve 从何而来

Eve 来自 Vercel 的一个团队，采用 Apache 2.0 许可证开源。官方 Vercel 文档将其描述为一种面向文件系统的持久化后端 AI 智能体框架，目前处于 Beta 阶段，因此 API 在正式发布前仍可能发生变化。

“如今的智能体就像框架出现之前的 Web，每个人都重复搭建同样的底层基础设施，却没有任何东西能延续到下一个项目。” —— Eve 团队，Vercel。介绍 Eve，2026 年 6 月 17 日。

这就是全部动机。持久化会话、运行代码的沙箱、审批、追踪、评估。每个团队在智能体做任何有用的事情之前都要重建这些，而且没有一个能转移到下一个项目。Eve 将这些基础设施作为框架提供，因此生产级能力从第一次运行就已内置，而不是在最后才拼凑上去。

智能体就是一个文件目录

核心理念——实验中也反复强调——是智能体并非你在代码中拼接的图形。它就是一个文件夹。

“智能体就是一个目录。文件的名称及其在目录树中的位置就是它的定义。”

智能体可以调用的工具、它掌握的技能、它委派的子智能体、它的调度计划以及它的评估，所有这些都作为纯文本文件存在于磁盘上。你可以打开文件夹，准确看到你的智能体是什么，进行 diff、提交并与队友分享。没有需要推理的隐藏运行时状态，因为文件树就是状态。

根目录下的两个文件定义了智能体本身。agent/instructions.md 保存了始终在线的系统提示，可选的 agent/agent.ts 设置运行时配置，例如使用哪个模型。它们之下的每个能力——工具、技能、子智能体、连接、频道和沙箱——都是一个目录，Eve 会根据名称自动发现，因此添加一个能力通常只需添加一个文件。

你需要组装的部分

在实验中，每个能力都是一个放入项目中的文件，Eve 无需任何注册步骤就能自动连接。以下是这些文件的实际样子。

工具（Tools） 是智能体的双手。工具是智能体可以调用的类型化动作，定义在 agent/tools/ 下的文件中。实验提供了 save_note.ts。

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

export default defineTool({
  description: "将简短笔记保存到项目的 notes/ 文件夹中。",
  inputSchema: z.object({
    title: z.string(),
    body: z.string()
  }),
  async execute({ title, body }) {
    // 写入 notes/<title>.md 并返回保存位置
  },
});

模型根据工具的描述决定何时调用。你的代码决定具体做什么，并且在你的应用运行时中运行，拥有完全访问权限，而不是在沙箱中。这种分离保持了智能体的灵活性和安全性。

技能（Skills） 赋予智能体知识而非动作。技能是位于 agent/skills/ 下的 Markdown 文件，通过一行描述来通告，仅在请求匹配时加载到上下文中。实验中的 filing.md 只有几行。

---
description: 当学习者要求保存、记录、归档或保留笔记时使用。
---

当学习者要求你保存笔记时，调用 save_note 工具。始终在笔记正文末尾单独一行加上：
Filed with eve.

让智能体“记录”一条笔记，它会加载这个技能，归档笔记，并附上你从未要求的“Filed with eve.”。这就是渐进式揭示。一个支持智能体可以拥有数十个技能作为剧本，仅拉取当前工单所需的一个，从而保持提示简洁。

子智能体（Subagents） 允许一个智能体进行委派。每个智能体都内置了一个 agent 工具，因此父智能体可以同时分发三个子任务并收集结果。这正是 V 在 Vercel 的 Eve 智能体集群中路由工作的方式。

人工介入（Human-in-the-loop） 对需要判断的操作进行把关。标记一个工具 needsApproval: always()，运行会在执行前暂停等待人工批准，期间不消耗计算资源。

export default defineTool({
  description: "发布已保存的笔记，使其上线。",
  inputSchema: z.object({
    slug: z.string()
  }),
  needsApproval: always(),
  async execute({ slug }) {
    /* 将 notes/<slug>.md 复制到 published/ */
  },
});

暂停是持久化的，因此一个任务可以等待人工几分钟或几天，然后从停止的地方准确恢复。这就是 draft0 模式：在低风险操作上快速行动，而对少数可能产生后果的操作保持控制。

持久化会话（Durable Sessions） 使得所有这些在现实世界中存活。每次对话都是一个带检查点的工作流，因此即使发生崩溃或部署也能幸存，并从停止的地方准确恢复。在实验中，智能体仅记住你三个消息前给出的一个事实。在生产中，它是一个从 Slack 开始工作、几天后在 Web 上继续的智能体，无需你编写任何状态管理代码。

评估（Evals） 证明它仍然有效。评估驱动真实智能体完成一个会话，然后对发生的情况进行断言。

import { defineEval } from "eve/evals";

export default defineEval({
  async test(t) {
    await t.send("保存一条启动笔记。");
    t.completed();
    t.calledTool("save_note");
  },
});

更改一个提示或工具，运行评估，你就能在用户发现问题之前捕获回归。它们像单元测试一样在本地和 CI 中运行。

连接（Connections） 是向外的方式，频道（Channels） 是向内的方式，每个都是一个文件。连接将智能体指向外部服务——MCP 服务器或 OpenAPI 风格的 API——Eve 代理认证，因此模型永远不会看到 URL 或凭据。

import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "http://127.0.0.1:3939/mcp",
  description: "本地天气服务。",
});

频道将该智能体放入 Slack、Discord、Teams 或 HTTP API 后面。你在终端中构建的智能体就是部署到 Slack 的智能体。通过添加一个文件来改变它的位置，而不是重写它。模式始终相同：放入一个文件，智能体读取它，行为改变，你将文件随代码一起提交。

这在实际生产中是什么样子

这不是一个玩具。以下示例直接来自 Vercel 的 Eve 发布公告，其中团队描述了他们内部运行的超过一百个智能体的集群。实验中使用这些相同的智能体作为你学习的每个概念的参考。

• d0，一个内部数据智能体，通过一个针对数据仓库的只读 SQL 工具，每月回答约三万次查询。
• Vertex，一个支持智能体，通过连接帮助中心和内部工具，自行解决了约 92% 的工单。
• Athena，一个与 Salesforce 和 Snowflake 连接的销售智能体，由非工程师在六周内构建完成。
• draft0 起草和审阅内容，但任何发布前都需人工签字。
• V 位于 Slack 中，读取每个传入任务，并将其路由到最适合回答的智能体。

这些中的每一个都与你在实验中构建的形状相同。你终端中的智能体与解决真实支持工单的智能体之间的区别，主要是目录中的文件不同。

一个具体的初次会话

你不是从空白页面开始的。在实验中，你在一个真实终端中启动一个工作智能体，并用纯英语与它交谈。

eve dev
# 启动一个在你的终端中的交互式智能体

你让它构建一些东西，比如一个小的 welcome.html，观察它调用自己的 write_file 工具并将结果保存到其沙箱中，永远不会触及你的真实机器。然后你交给它上面的 save_note 工具，让它归档一条笔记，看到它根据描述自动选择该工具。从那里起，实验依次添加一个技能、一个子智能体、一个审批门、一个评估和一个连接，每次一个文件，直到你遍历了整个框架。

从你的笔记本电脑到生产环境

这就是文件系统优先策略带来回报的地方。

“同一个目录在生产环境中运行的方式与在你的笔记本电脑上运行的方式完全相同。”

它是一个普通的 Vercel 项目。Eve 将 agent/ 目录编译成一个运行在 Vercel Functions 上的应用，因此你在本地构建和测试的智能体就是部署的智能体。变化的不是你的代码，而是其下的基础设施，每个部分都映射到一个有文档的 Vercel 服务。

• 沙箱升级。 本地运行在隔离的、类似 bash 的沙箱中。在生产中，每个智能体获得一个真正的隔离 Vercel 沙箱，因此它可以运行 shell 命令和写入文件，而永远不会触及你的应用运行时。
• 会话变为持久化工作流。 Eve 在 Vercel Workflows 上持久化会话状态，因此运行可以在部署后幸存，从冷启动恢复，并可以在等待人工审批时暂停数分钟或数天，然后从停止的地方准确恢复。文档说得很清楚：会话“在冷启动、部署或长时间暂停后恢复”。
• 调度和频道上线。 你的 defineSchedule 文件开始按 cron 触发，你添加的频道将同一个智能体放入 Slack、Discord、Teams 或 HTTP API 后面。
• 每次运行都被追踪。 Vercel Observability 会展示每个智能体运行的会话、轮次、工具、推理、时间和令牌使用情况，无需任何设置。
• 模型和认证得到处理。 模型字符串通过 AI Gateway 和 OIDC 路由，因此你无需管理提供商密钥；Vercel Connect 为你的连接代理 OAuth 和 API 密钥。
• 一个智能体变成一个集群。 同样的形状可以水平扩展，这就是 Vercel 同时运行超过一百个这样的智能体的方式，每个只是一个目录。

你无需为生产环境重新实现任何东西。你部署这个目录，框架处理持久化、隔离、模型和扩展。

如何开始

• 初始化项目。 运行 npx eve@latest init my-agent 创建项目，安装依赖，启动开发服务器。你将在几秒钟内得到一个终端中的交互式智能体。用纯英语与它交谈。
• 给它一个工具。 添加一个如 save_note 的 defineTool 文件，让智能体使用它，观察它调用你的代码。
• 教它一个技能。 编写一个简短的 Markdown 文件，包含一个描述何时使用某个程序的描述。这在不编写逻辑的情况下编码了知识。
• 用子智能体委派任务。 通过内置的 agent 工具转交一个聚焦的任务，使你的主智能体保持简洁。
• 用评估证明它，然后安排它。 添加一个 defineEval 文件和一个包含 cron 行的 defineSchedule 文件。现在你有了一个经过检查的、定期运行的智能体。
• 连接并发布。 添加一个连接以访问真实服务，添加一个频道将智能体放入 Slack，然后将同一目录部署到 Vercel。

要点如下。Eve 的信念是：智能体应该是一组你可以读取的文件，而不是你必须信任的一个运行环境。这使得智能体具备可检查性、可版本控制和可移植性，并将棘手的生产问题转移到它们所属的框架中。如果你发现任何错误或需要进一步澄清的内容，请随时联系我们。

其他有用参考

• Eve 文档，官方文档
• Eve 概念，智能体、会话、工具、技能、连接和沙箱如何配合
• 介绍 Eve，Vercel 公告
• vercel/eve，GitHub 上的开源框架
• Eve 入门指南，我们的免费动手实验