Introduction

How an eve agent is laid out as files, what runs when a message arrives, and the building blocks you add as it grows.

eve is a framework for building durable agents as ordinary files in a TypeScript project.

Instead of one large configuration object, each part of your agent gets a clear home. Instructions go in one file, tools in one folder, channels in another. eve discovers that structure and turns it into an agent that runs locally, serves HTTP, connects to other platforms, and keeps working across many turns.

eve is currently in beta and subject to the Vercel beta terms; the framework, APIs, documentation, and behavior may change before general availability.

An eve project at a glance

A small eve app looks like this:

my-agent/
├── package.json
└── agent/
    ├── agent.ts
    ├── instructions.md
    ├── tools/
    │   └── get_weather.ts
    ├── skills/
    │   └── plan_a_trip.md
    └── channels/
        └── slack.ts

You can understand most eve projects by reading that tree:

instructions.md tells the agent who it is and how it should behave.
agent.ts chooses the model and configures runtime options.
tools/ holds typed functions the model can call.
skills/ holds longer procedures the model loads only when they are useful.
channels/ connect the agent to HTTP clients, Slack, Discord, and the other places people talk to it.

Start with only instructions.md and agent.ts. Add the other folders when the agent needs them.

The files are the interface

eve is filesystem-first. A file's location says what it does, and its path usually gives it a name. For example, this file:

agent/tools/get_weather.ts

defines a tool named get_weather:

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

export default defineTool({
  description: "Get the weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  async execute({ city }) {
    return { city, condition: "Sunny" };
  },
});

There is no separate registry to keep in sync. Add the file and eve discovers it; move or rename it and its identity moves with it. See Tools for the complete API.

What happens when a message arrives

The same flow runs whether a message comes from a web app, the terminal, or Slack. eve turns the platform input into a message, gives the model its instructions, skills, tools, and conversation history, runs the work (calling tools and subagents as needed), saves the session and streams events, then delivers the result back in the form the platform expects.

That keeps agent behavior portable. Your weather tool does not need to know whether the question came from a browser or from Slack.

Durable by default

An eve session is more than one request and one response. It can:

Stream progress while work is happening
Call tools and subagents
Pause for approval or a human answer
Resume after that answer arrives
Keep durable state across turns

Under the hood, eve uses the open-source Workflow SDK to make sessions durable, resumable, and crash-safe. eve handles that machinery so your tools focus on the work itself.

Grow the project by adding capabilities

As the agent grows, each concern still has a predictable home:

Path	Add it when you need...
`connections/`	Tools from external MCP servers
`hooks/`	Code that reacts to lifecycle and stream events
`sandbox/`	A controlled workspace for files and commands
`subagents/`	Specialist agents the root agent can delegate to
`schedules/`	Recurring or scheduled work
`lib/`	Shared code imported by the other agent files

The result stays readable before it runs. The directory tells you what the agent can do.