mcpField
V
vercel-eve

vercel-eve

github.com/magnus919Agent 工作流15359 次安装今天更新
代码仓库

关于 vercel-eve

Vercel Eve 是一种以文件系统为核心的框架，用于构建可持久运行的后端 Agent，并以 agent 目录划定应用边界。它面向需要类型化能力、可配置执行层，以及明确工作流、安全和部署验证的开发者。

主要功能

  1. 01按生成的文件结构组织 Agent 行为
  2. 02定义类型化工具和外部连接
  3. 03分设技能、子 Agent、入口和计划任务
  4. 04配置沙箱与运行时层
  5. 05部署到 Vercel 或自托管 Node
  6. 06验证授权会话和持久工作流

适用场景

  1. 01构建带类型化操作和集成的后端 Agent
  2. 02组织 Agent 指令、能力和入口
  3. 03将 Agent 部署到 Vercel 或 Node 服务
  4. 04验证授权会话及工作流恢复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/magnus919/agent-skills --skill vercel-eve

安装后在 Claude Code 中输入/vercel-eve确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
evals/
evals.json
references/
deployment-and-self-hosting.md
development-and-architecture.md
source-index.md

详细介绍

Vercel Eve

Eve 是一个以文件系统为先的持久化后端 Agent 框架。将 agent/ 目录视为应用边界，并将部署视为由可独立替换的 HTTP、工作流、沙箱、模型、凭据和可观测性层组合而成。

运行约定

  1. 从生成的项目结构开始。将 Agent 行为放在 agent/instructions.md 中，将运行时选项放在 agent/agent.ts 中，并在相应目录下为每项类型化能力单独创建一个文件。
  2. 将权限控制放在模型提示词之外。使用类型化工具、连接、沙箱边界和路由身份验证，而不是在指令中放入凭据或策略。
  3. 将持久化会话视为工作流，而不是内存中的聊天。在依赖长时间运行或有副作用的任务之前，先定义持久化、幂等性、回调可达性和恢复机制。
  4. 在可自托管部署中，有意替换每项 Vercel 服务。Node 进程能够启动，并不代表工作流回调、持久化状态、计划任务、沙箱隔离、身份验证和遥测都能正常工作。
  5. 使用健康检查请求和经过身份验证的真实会话进行验证，并确保会话实际执行工作流路径。切勿仅凭 HTTP 200 就认定已满足生产就绪条件。

不适用场景

不要将此用于独立的 ai 包中的 ToolLoopAgent、WorkflowAgent 或 HarnessAgent API。不要将其用于没有 Eve Agent 的通用 Next.js 部署。对于供应商中立的工作流编排，请改用相关的工作流或 Agent 框架技能。

遇到此类请求时，请说明 Eve 不适用，并转向当前的 AI SDK 文档或 AI SDK 专用技能。不要根据此技能编写 AI SDK API 代码、模型配置或部署指南。

项目模型

需求默认位置
始终运行的行为agent/instructions.md
模型和运行时选项agent/agent.ts
类型化操作agent/tools/*.ts
按需执行的流程agent/skills/
范围更窄的子 Agentagent/subagents/
HTTP、Slack 或其他入口点agent/channels/
类型化外部集成agent/connections/
隔离计算agent/sandbox/
OpenTelemetry 设置agent/instrumentation.ts
周期性任务agent/schedules/

创建或重组 Agent 之前，请阅读开发与架构。

快速开始

npx eve@latest init my-agent
cd my-agent
npm run dev

使用生成的 README 和包脚本作为本地事实来源。最简运行时配置会选择一个模型：

import { defineAgent } from "eve";

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

在 Vercel 上，字符串模型 ID 会通过 AI Gateway 路由，并可使用项目 OIDC。在 Vercel 之外，可以配置 AI_GATEWAY_API_KEY，也可以使用 AI SDK Provider 对象和该 Provider 通常使用的凭据。不要假设 BYOK 意味着绕过 Gateway。

有意构建能力

工具

工具是连接模型推理与外部操作的类型化边界。为它定义范围精简的架构，并提供清晰说明，明确其授权和副作用边界。工具声明类型化输入、输出和副作用。它不持有凭据，也不授予权限：将集成凭据保留在连接中，并在产生效果之前于服务端执行授权检查。

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

export default defineTool({
  description: "Look up a city’s current weather.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny" };
  },
});

对于只应在相关时加载的较大流程，请使用技能。如果任务需要全新的历史记录、更精简的工具集或隔离的中间状态，请使用子 Agent。

凭据与执行

使用 agent/connections/ 进行类型化服务集成。使用 agent/sandbox/ 执行生成的代码或 Shell 操作。切勿将 Provider 密钥、OAuth 令牌或路由身份验证密钥放入指令、工具源代码、生成的产物或日志中。

有关沙箱设计和生命周期选项，请阅读开发与架构。有关自托管后端和路由，请阅读部署与自托管。

部署

Vercel

使用与 Git 连接的项目或 vercel deploy。Eve 会生成 Vercel Build Output，使用 Vercel Workflows 管理持久会话，并且通常会选择 Vercel Sandbox。在公开面向浏览器的路由之前，请替换脚手架生成的占位身份验证。

自托管 Node 服务
eve build
PORT=3000 eve start --host 0.0.0.0

此方式使用 .output/ 下的常规 Nitro Node 输出。在接收生产流量之前，请阅读部署和自托管，并明确验证持久化工作流存储、沙箱后端、模型凭据路径、身份验证、/eve/ 和 /.well-known/workflow/ 代理前缀、计划任务执行以及遥测。

将主机路径、反向代理产品配置、存储产品和计划任务实现视为目标特定的依据。如果未提供或检查目标拓扑，请指出所需的约定和缺失的依据，不要凭空编造配置。

安全性与可观测性

  • 在任何生产环境浏览器请求之前，请将占位身份验证替换为真实的策略。在 Vercel 之外，不要依赖 vercelOidc() 作为唯一的身份验证方式。
  • 为沙箱配置满足需求的最低网络和凭据访问权限。沙箱无法保护有意注入其中的机密信息。
  • Vercel Agent Runs 使用起来很方便，但应将 OpenTelemetry 视为可移植的运维依据路径。如果跟踪记录会包含敏感数据，请将 recordInputs 或 recordOutputs 设为 false。
  • 对于个人、敏感或受监管的数据，请评估会保留哪些模型输入、工具参数、输出和跟踪记录，并在需要时披露数据收集情况。

验证关卡

  1. 构建已部署的构件。
  2. 确认健康检查端点：GET /eve/v1/health。
  3. 启动一个经过身份验证的会话：POST /eve/v1/session。
  4. 连接到会话流，并验证一轮实际交互已完成。
  5. 对于自托管部署，测试持久化工作流回调或恢复路径，而不只是无状态回复。
  6. 检查跟踪记录，确保其中不包含机密信息和敏感载荷，或已按预期进行脱敏。

完成标准

仅当所请求的 Agent 能力已实现、其路由和授权边界已明确，并且已通过证据测试相关的本地或已部署会话路径时，任务才算完成。验证与版本相关的行为时，请参阅源索引。

评论

支持 Markdown