用Vercel的Eve框架构建AI智能体：文件即智能体

Vercel近日发布了Eve，一个用于构建、运行和扩展智能体（agent）的开源框架。核心理念是：你不再需要每次都手动重复搭建智能体的基础设施，而是可以将智能体视为可以从磁盘读取的东西。

以下是关于Eve是什么、为什么重要以及实际构建流程的实用版本，内容源自我们刚刚为其构建的免费动手实验室。

下面是我（在Claude的辅助下）使用Eve一周后的一些思考。

如果你想零配置尝试Eve，我们构建了一个免费动手实验室，你可以在实时终端中驱动真实的eve CLI，无需自己的API密钥。你可以在“Introduction to Eve”中体验。

Eve的起源

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

> “今天的智能体就像框架出现之前的Web一样，每个人都在手动重复搭建同样的基础设施，而这些东西无法延续到下一个项目。” —— Eve团队，Vercel，《Introducing Eve》，2026年6月17日。

这正是其动机所在：持久化会话、运行代码的沙箱、审批、追踪、评估。每个团队在智能体做任何有用的事情之前都要重新构建这些，而且没有一个能转移到下一个项目。Eve将这些基础设施作为框架本身交付，因此从第一次运行起就内置了生产环境支持，而不是在最后才临时加上。

智能体就是一个文件目录

核心思想——也是实验室反复强调的——是智能体不是在代码中连接起来的图，而是一个文件夹。

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

智能体可以调用的工具、它掌握的技能、它委托的子智能体、它的调度规则以及评估，都以普通文件形式保存在磁盘上。你可以打开文件夹，准确看到你的智能体是什么，对比差异（diff），提交版本（commit），并交给队友。没有隐藏的运行时状态需要推理，因为文件树本身就是状态。

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

你组装的部分

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

工具是智能体的手。工具是一个智能体可以调用的带类型操作，定义在 agent/tools/ 目录下的文件中。实验室提供了 save_note.ts。

模型根据其描述决定何时调用工具。你的代码决定发生什么，并且它在你应用运行时中运行，拥有完全访问权，而不是在沙箱中。这种分离使得智能体既灵活又安全。

技能给智能体提供知识而不是操作。技能是 agent/skills/ 目录下的一个markdown文件，通过一行描述来宣传，并且仅在请求匹配时才加载到上下文中。实验室的 filing.md 只有几行。

让智能体“记录”一条笔记，它会加载这个技能，归档笔记，并签上你从未要求的“Filed with eve.”。这是渐进式披露（progressive disclosure）。一个支持智能体可以持有几十个剧本作为技能，只在工单需要时拉入相应的剧本，这样提示词就能保持简洁。

子智能体让一个智能体可以委托任务。每个智能体都有一个内置的agent工具，因此父智能体可以同时分发三个子任务并收集结果。这正是V扩展至Vercel的Eve智能体集群的方式。

人在回路（Human-in-the-loop）门控需要判断的操作。标记一个工具 needsApproval: always()，运行会在执行前暂停等待人工，不会消耗计算资源。

暂停是持久化的，因此一个任务可以等待人类几分钟或几天，然后从停止的地方精确恢复。这是draft0的模式：在低风险的事情上快速行动，在少数需要发布的操作上保持人为控制。

持久化会话是所有这一切能够在现实世界中存活的原因。每一次对话都是一个有检查点的工作流，因此它能在崩溃或部署后存活，并精确恢复到停止的地方。在实验室中，智能体只是记住你三条消息前给它的事实。在生产中，它是一个工作在Slack中启动，几天后在Web上继续的智能体，而你无需编写任何状态管理代码。

评估证明它仍然有效。一个评估驱动真实智能体通过一个会话，并对发生的事件进行断言。

更改提示词或工具，运行评估，你就能在用户遇到回归之前捕获它。它们可以在本地和CI中运行，就像单元测试一样。

连接是出口，频道是入口，每个都是一个单独的文件。连接将智能体指向一个外部服务，比如MCP服务器或OpenAPI风格的API，Eve代理认证，因此模型永远看不到URL或凭据。

频道将同一个智能体放入Slack、Discord、Teams或一个HTTP API后面。你在终端中构建的智能体就是部署到Slack的智能体。你通过添加文件来改变它所在的地方，而不是重写它。

模式始终如一：放入一个文件，智能体读取它，行为改变，然后你将文件与代码一起提交。

这在生产环境中是什么样子

这可不是玩具。下面的例子直接来自Vercel的Eve公告，团队描述了他们在内部运行的一百多个智能体集群。实验室使用这些相同的智能体作为每个概念的参考。

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

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

一个具体的初次会话

你不会从白页开始。在实验室中，你在一个真实的终端中启动一个工作智能体，并用英语与它对话。

你让它构建一些东西，比如一个小型的 welcome.html，然后看着它调用它的 write_file 工具并将结果保存到它的沙箱中，永远不会触及你的真实机器。然后你把上面的 save_note 工具交给它，让它归档一条笔记，看着它自动从描述中选取工具。从那里开始，实验室一层层添加技能、子智能体、审批门、评估和连接，一次一个文件，直到你完整走遍整个框架。

从你的笔记本到生产环境

这正是文件系统优先策略的价值所在。

> “同一个目录在生产环境中运行的完全就像在你的笔记本上运行的一样。”

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

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

你无需为生产重新实现任何东西。你部署目录，框架处理持久性、隔离性、模型和规模。

如何开始

1. 搭建项目。 运行 npx eve@latest init my-agent 来创建项目，安装依赖，并启动开发服务器。你在几秒钟内就能在终端中获得一个交互式智能体。用英语与它对话。
2. 给它一个工具。 添加一个 defineTool 文件，比如 save_note，让智能体使用它，然后看着它调用你的代码。
3. 教它一个技能。 编写一个简短的markdown文件，带有一个描述说明何时使用某个过程。这编码了知识，而无需编写逻辑。
4. 用子智能体委托。 通过内置的agent工具委托一个聚焦的任务，让你的主智能体保持简洁。
5. 用评估证明它，然后调度它。 添加一个 defineEval 文件和一个带有cron行的 defineSchedule 文件。现在你有了一个经过检查的、定期运行的智能体。
6. 连接并发布。 添加一个连接到真实服务，一个频道将智能体放入Slack，然后将同一个目录部署到Vercel。

以下是要点：Eve的赌注是，智能体应该是一组你可以读取的文件，而不是一个你必须信任的运行时。这使得智能体可检查、可版本控制、可移植，并将困难的生产问题移入框架中，放在它们应在的位置。

如果你发现任何错误或需要进一步澄清的地方，请随时联系。

---

（注：原文中“Other Useful References”部分已移除，因为属于非正文内容。）