15分钟入门 Eve 框架：搭建首个 AI Agent

15分钟入门 Eve 框架：搭建首个 AI Agent

给内部业务系统接入 AI 助手是近期开发团队的常见需求。每次从零编写 Prompt 管理、工具调用与会话状态维护代码，不仅冗长且难以调试。Vercel 开源的 eve 框架提供了一套全新的解决方案：将 Agent 所有配置收敛至文件系统。目录结构即配置面板，修改保存即生效。

本文将带你从零搭建一个支持自定义工具的 AI Agent。完成本教程后，你将掌握 eve 的核心工作流：项目初始化、系统指令编写、自定义工具注册与交互调试。适合后端开发者与全栈工程师快速将 AI 能力嵌入实际服务。

环境准备

运行本教程需满足以下基础条件：

• Node.js 18+（eve 底层基于 TypeScript 与原生 ESM 模块构建）
• API 凭证（如 OpenAI API Key 或兼容的模型网关地址）
• 终端操作基础，熟悉常规 npm 命令即可

eve 采用“文件系统即创作界面”的设计理念，熟悉目录操作即可快速上手。无需配置复杂的图形面板或外部数据库。

步骤一：初始化项目

打开终端，执行以下命令创建项目脚手架：

npx eve@latest init my-first-agent

该命令在后台自动完成四项关键操作：

1. 生成 my-first-agent 工作目录
2. 安装 eve 核心运行时、依赖库及 Zod 校验工具
3. 自动初始化本地 Git 仓库，便于版本控制
4. 拉起交互式配置终端，引导基础设置

若需指定特定模型提供商，可追加 --model 参数：

npx eve@latest init my-first-agent --model openai/gpt-5.6-terra

这种设计将所有 Agent 资产统一收口至 agent/ 目录。无需在分散的配置文件与业务代码间反复跳转，直接修改文件即可驱动配置热更新。

步骤二：解析项目结构

初始化完成后，核心目录布局如下：

my-first-agent/
└── agent/
    ├── agent.ts            # 模型标识与运行时参数
    ├── instructions.md     # 系统提示词（Agent 启动必读）
    ├── tools/              # Agent 可调用的外部能力集合
    │   └── get_weather.ts
    └── ...                 # skills/ channels/ schedules/ 按需扩展

核心文件职责明确：

• agent.ts：定义底层模型路由与基础运行策略
• instructions.md：充当 System Prompt，设定 Agent 行为边界与回复风格
• tools/ 下的 .ts 文件：封装 Agent 对外调用的具体业务函数

步骤三：编写指令与注册工具

3.1 配置系统提示词

打开 agent/instructions.md，写入清晰的行为约束：

你是一个简洁的天气演示助手。回答用户时，先说明提供的天气数据为模拟结果，再输出具体信息。保持回答简短，避免冗长段落。

使用 Markdown 格式管理提示词，便于后续添加排版、列表与对话示例。相比硬编码在 JSON 字符串中，纯文本格式更利于版本对比与语义调试。eve 会在每次会话初始化时将其完整注入上下文。

3.2 定义自定义工具

在 agent/tools/ 目录下创建 get_weather.ts，编写工具逻辑：

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

export default defineTool({
  description: "返回指定城市的模拟天气数据。",
  inputSchema: z.object({ 
    city: z.string().min(1, "城市名不能为空") 
  }),
  async execute({ city }) {
    // 生产环境可替换为 fetch 调用真实气象 API
    return { 
      city, 
      condition: "晴", 
      temperatureC: 22,
      humidity: 65
    };
  },
});

代码结构包含三个核心环节：

• defineTool：框架提供的标准注册器，将普通异步函数包装为 Agent 可识别的 Function Calling 单元
• inputSchema（Zod）：定义严格的参数校验规则。eve 在模型发起调用前自动执行预检，拦截字段缺失或类型错误的数据，保障执行环境稳定性
• async execute：实际业务逻辑入口。当前返回固定模拟数据，接入生产服务时替换为 HTTP 请求或数据库查询即可

理解底层运行机制：Agent 调用工具的本质是 LLM 输出结构化 JSON → 框架路由匹配 → 执行对应函数 → 将执行结果作为新 Token 回填模型继续推理。Zod 在此链路中充当类型安全网关，有效降低模型幻觉导致的参数错误。

3.3 校验模型配置

打开 agent/agent.ts，确认模型标识符合预期环境：

import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-5.6-luna-fast",
});

若接入其他模型供应商，通过统一 AI Gateway 路由时仅需替换 model 字符串，并在 .env 文件中补充对应认证变量。

步骤四：启动运行与交互测试

进入项目根目录执行开发模式启动命令：

npm run dev

终端加载交互式调试界面后，直接输入自然语言指令，例如：

北京今天天气怎么样？

Agent 将按序触发完整工作流：

1. 载入 instructions.md 设定回复边界
2. 语义分析识别查询意图，自动匹配到 get_weather 工具名
3. 依据 Zod Schema 校验并提取参数 { city: "北京" }
4. 执行 execute 函数获取模拟响应
5. 结合工具返回数据与系统指令，生成符合约束的最终回复

全程无需手动编写 HTTP 路由、会话状态持久化或 Prompt 拼接逻辑。文件驱动架构确保了修改配置即热重载，开发调试效率显著提升。

避坑指南

1. 环境变量缺失：eve 运行依赖对应模型凭证（如 OPENAI_API_KEY）。启动报 Unauthorized 错误时，优先检查项目根目录 .env 文件格式或终端全局变量注入情况。
2. 工具未注册生效：工具文件必须严格位于 agent/tools/ 目录，且必须使用 export default defineTool(...) 语法。路径偏离或遗漏默认导出会导致 Agent 无法在工具列表中感知该能力。
3. Zod 校验拦截：模型生成的参数若不符合 inputSchema 定义，eve 会直接拦截并返回错误。调试阶段建议在 execute 函数首行添加 console.log 打印实际入参，快速定位 Schema 定义偏差。
4. Beta 阶段特性：官方仓库已标注当前为 Beta 版本。核心 API 保持稳定，但部分底层接口可能随版本迭代微调。建议生产环境部署前锁定依赖版本并定期查阅 Release Notes。

后续扩展方向

本教程已跑通 eve 的最小使用闭环。掌握基础流程后，可尝试以下进阶配置以适配复杂业务场景：

• 在 agent/skills/ 添加按需加载的流程文档，控制 Agent 在特定触发条件下的上下文读取范围，优化 Token 消耗
• 通过 agent/channels/ 接入 HTTP API、Slack 或 Discord 机器人，将本地 Agent 暴露至外部通信渠道
• 利用 agent/schedules/ 编写 Cron 定时任务，实现数据巡检、自动报表等周期性工作流

适应文件系统驱动模式后，Agent 的开发体验将与常规后端工程保持一致。将现有微服务 API 封装至 tools/ 目录，即可让 AI 接管复杂多步交互逻辑。

项目仓库：https://github.com/vercel/eve
官方文档：https://eve.dev/docs