入门
用 Vercel Eve 以目录结构搭 AI 智能体（面向 Agent 的 Next.js）
你如果写过 Next.js，一定会觉得「配置文件满天飞、约定优于配置」很香。Vercel 在 2026 年 7 月发布的开源框架 Eve，就把这套思路搬到了 AI 智能体上——它被称为「面向 Agent 的 Next.js」：一个目录 = 一个智能体，目录里的几个文件就定义了这个 Agent 用哪个模型、听什么指令、会什么工具。本教程带你从零搭一个能跑、能接工具、还能一键部署的 Eve 智能体。
📁 本教程适合：会一点前端/Node、想把「写代码」和「写 Agent」统一起来的人；也适合厌倦了在可视化界面里拖拽、想要「文件即配置」的开发者。Eve 已开源（Apache 2.0），免费可玩。
先搞懂：Eve 把 Agent 拆成了哪几个文件？
核心思想就一句：智能体不是一段 prompt，而是一整个目录。你在一个文件夹里放几类文件，Eve 会把它「编译」成一个可运行的 Agent。
| 文件 | 作用 | 怎么写 |
|---|---|---|
| 模型文件 | 指定用哪个大模型 | 由 Vercel AI 网关负责厂商故障切换 |
| 系统提示词 | Agent 的人设与规则 | 一个 Markdown 文件 |
| 工具文件 | Agent 会调用的能力 | 每个工具一个 TypeScript 文件，文件名即工具名，免注册 |
| skill.md | 可复用技能包 | 类似其它框架的 Skill |
| MCP 配置 | 连接外部服务 | 通过 MCP 服务器接入 |
工具不用「注册」：在其它框架里，你通常要写一段注册代码把工具告诉 Agent；Eve 里文件名就是工具名，放进去就被识别。少了一层样板代码，这是它最大的清爽点。
Step 1：装好环境并初始化一个 Agent 目录
1 一个目录就是一个 Agent
# 前置：Node 22+ 与 Vercel CLI
node -v # 确认 >= 22
npm i -g vercel # 装 Vercel CLI
# 新建工程目录
mkdir my-support-agent && cd my-support-agent
# Eve 会把当前目录直接当作一个 Agent 来编译💡 Eve 没有「new project」脚手架命令那么重——你只需准备一个目录和几类文件，它就能识别。这跟 Next.js「app 目录即路由」是一个哲学。
Step 2：指定模型（接 Vercel AI 网关）
2 写一行，定模型
在目录里放一个模型文件，告诉 Eve 用哪个模型。背后由 Vercel AI Gateway 接管——如果主厂商挂了，会自动切到备用厂商，你的 Agent 不会因为一家模型抖动就崩。
# model.txt（或框架约定的模型配置文件）
model: openai/gpt-4o # 也可用 anthropic/claude、google/gemini 等
gateway: true # 开启 AI 网关故障切换别把 API Key 硬编码进仓库：用环境变量（如 OPENAI_API_KEY）注入，Eve 在本地和部署时都会读取。密钥提交到 Git 是新手最容易踩的坑。
Step 3：写系统提示词（Markdown）
3 人设与规则，写进 .md
系统提示词就是一个 Markdown 文件。这里写得越清楚，Agent 越稳：
# system.md
你是「龙虾科技」的售前支持 Agent。
【职责】
- 只回答产品功能、价格、接入方式相关问题
- 语气专业、简洁，多用「您」
- 不确定的，引导用户留下邮箱
【红线】
- 不编造不存在的功能或报价
- 涉及合同/退款，先安抚再给步骤🔑 提示词三件套：它是谁、该做什么、不能做什么。这和本中心《零基础 Dify 搭建》里讲的人设写法完全一致，只是换成了文件形式。
Step 4：加工具（每个工具一个 TS 文件）
4 文件名即工具名，免注册
在目录里放一个 TypeScript 文件，文件名就是工具名。比如做一个「查订单」工具：
// tools/checkOrder.ts
export async function checkOrder(orderId: string) {
// 这里调你自己的订单 API
const res = await fetch(`https://api.example.com/orders/${orderId}`);
return res.json();
}安全默认：每个工具都能设为「执行前需人工审批」。涉及写操作（发消息、改数据）的工具，务必打开审批，别让 Agent 自作主张。
Step 5：本地运行 + 接 MCP / 多渠道
5 一条命令跑起来
# 本地启动，终端里直接对话
vercel dev # 或 Eve 提供的本地运行命令
# 接 MCP 服务器（连数据库 / 日历 / 搜索引擎等）
# 在配置里声明 mcp server，Agent 自动获得对应能力
# 多渠道：通过配置让 Agent 出现在
# Slack / Discord / Teams / Telegram / GitHub / Linear 等💡 Eve 每次会话都是「持久化工作流」：每个步骤都会打检查点，能暂停、崩溃后从断点恢复。这意味着长任务不会因为断网就前功尽弃——这正是生产环境最看重的韧性。
Step 6：一键部署上线
6 像部署网站一样部署 Agent
# 直接部署，和部署普通 Vercel 项目一模一样
vercel deploy
# 细节：若部署时旧版 Agent 正在执行会话，
# 该会话会在旧版本上跑完，不会被打断🎉 恭喜！你已经有了一个「目录即 Agent、文件即配置、可接工具、可观测、可部署」的 Eve 智能体。配合 Vercel 可观测面板的「Agent Runs」视图，你能看到每次执行的 OpenTelemetry 追踪，也能导出到 Datadog / Honeycomb 做深度分析。
常见问题速查
| 你遇到的现象 | 大概率原因 & 解决 |
|---|---|
| 工具没被 Agent 调用 | 文件名/导出格式不对，确认是默认导出且参数有类型 |
| 模型报错「无权限」 | API Key 没注入环境变量，或 AI 网关未开启 |
| Agent 乱改数据 | 写类工具没开「人工审批」，去配置里打开 |
| 部署后旧会话中断 | 正常现象不会发生——Eve 让在跑的会话跑完旧版本 |