Introduction

Purpose and Scope

eve is a filesystem-first framework for building durable agents in a TypeScript project. The core idea is that an agent should be understandable from ordinary files and folders rather than from one large, opaque configuration object. The introduction page frames eve as a way to place each concern in a predictable home: instructions in one file, tools in a folder, channels in another folder, and optional capabilities added only when the agent needs them. This gives new readers a mental model they can apply before learning the full API surface.

Sources: docs/introduction.mdx

The page is also the first documentation entry point for understanding what runs when a user sends a message. It explains that the same agent can run locally, serve HTTP, connect to external communication platforms, and keep working across many turns. That combination matters because eve is not only a prompt wrapper. It is a runtime model for long-lived agent work, where discovery, message normalization, capability loading, streaming, and durable session state are part of the framework’s default behavior.

Sources: docs/introduction.mdx

Relevant Source Files

• docs/introduction.mdx - Defines the official introduction content, including the filesystem-first model, the starter project tree, the message-arrival flow, durable session framing, and the capability folders that developers add as agents grow.

Core Mental Model

The most important concept is that the filesystem is the authoring interface. In an eve project, a file location communicates what the file contributes to the agent. A tool file under the tools folder defines a model-callable function, a skill file under the skills folder defines a reusable procedure, and a channel file under the channels folder connects the same agent behavior to a delivery surface such as HTTP or Slack. This reduces the need for a separate registry because the path and filename carry identity.

Sources: docs/introduction.mdx

A minimal project starts with just the always-on instructions and the agent configuration. The introduction recommends beginning with instructions.md and agent.ts, then adding folders as the agent needs more capabilities. That sequencing is part of the developer experience: a small agent should remain small, while a larger agent can gain tools, skills, channels, connections, hooks, sandbox behavior, subagents, schedules, and shared library code without losing a predictable layout. The shape of the project remains readable as it expands.

Sources: docs/introduction.mdx

Project Layout at a Glance

The introductory project tree shows an agent directory containing the main configuration file, standing instructions, and optional capability folders. The instructions file tells the agent who it is and how it should behave. The agent configuration chooses the model and runtime options. The tools folder contains typed functions the model can call. The skills folder contains longer procedures that can be loaded when useful. The channels folder connects the agent to the places where users talk to it, including HTTP clients and chat platforms.

Sources: docs/introduction.mdx

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

The introduction’s weather example demonstrates how path-based discovery becomes a public authoring contract. A file at agent/tools/get_weather.ts defines a tool named get_weather. The exported definition supplies a description, an input schema, and an execute function. The important point is not the weather response itself; it is that adding the file is enough for eve to discover the capability. Moving or renaming the file changes its identity with the filesystem, so the source layout and runtime capability graph stay aligned.

Sources: docs/introduction.mdx

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" };
  },
});

What Runs When a Message Arrives

When a message arrives, eve follows the same conceptual flow regardless of where the message came from. A web app, the terminal, and Slack all provide platform-specific input, but eve turns that input into an agent message. The runtime then gives the model its instructions, available skills, callable tools, and conversation history. During the turn, the agent can call tools and subagents as needed. The session is saved, events are streamed, and the final response is delivered back in the format expected by the originating platform.

Sources: docs/introduction.mdx

This portability is a key motivation for separating channels from tools. A weather tool should not need to know whether the user asked from a browser, a terminal session, or Slack. Channels handle platform integration and delivery details, while tools remain focused on domain work. That boundary makes agent behavior easier to reuse and easier to test: the same capability can serve multiple front doors without duplicating business logic or embedding platform-specific assumptions inside the tool implementation.

Sources: docs/introduction.mdx

Durability and Long-Lived Work

The introduction defines an eve session as more than a single request and response. A session can stream progress, call tools and subagents, pause for an approval or a human answer, resume after that answer arrives, and keep durable state across turns. This framing is important for developers coming from stateless HTTP handlers. In eve, an agent conversation can include parked work, delayed human decisions, and multiple turns while still presenting a coherent session to clients and channels.

Sources: docs/introduction.mdx

Under the hood, eve uses the open-source Workflow SDK to make sessions durable, resumable, and crash-safe. The introduction deliberately keeps that machinery behind the framework boundary: developers write instructions, tools, channels, and related capabilities, while eve handles the workflow mechanics that let the session continue reliably. The practical result is that tool authors can write code around the work itself instead of manually implementing checkpointing, replay protection, resume behavior, and platform-specific streaming coordination.

Sources: docs/introduction.mdx

Growing an Agent

As an agent grows, eve keeps each new concern in a predictable place. The introduction names connections for external MCP or OpenAPI services, hooks for lifecycle and stream reactions, sandbox configuration for controlled files and commands, subagents for specialist delegation, schedules for recurring work, and lib for shared code imported by other agent files. These are not required for the first agent, but they show how the initial filesystem model scales into a larger backend agent application without abandoning the same conventions.

Sources: docs/introduction.mdx

For new projects, the recommended next step is to keep the starting surface small. Read the agent tree, identify the always-on instructions, inspect the model and runtime options, and add one capability folder only when a real need appears. If the agent needs to do domain work, start with tools. If it needs reusable procedures, add skills. If it needs to meet users somewhere besides the default surface, add a channel. If it needs external systems, use connections rather than hard-coding service access everywhere.

Sources: docs/introduction.mdx

Next Reading

Use this introduction as the orientation page before moving into task-specific docs. The project layout reference expands the filesystem conventions. Agent Config explains the top-level configuration file. Tools and Approvals cover typed capabilities and human-in-the-loop pauses. Skills, Channels Overview, Connections Overview, Sandbox, Subagents, and Schedules each explain one optional growth area from the introductory table. If you want a guided path rather than a concept map, start with the First Agent tutorial and build up the same model through a working agent.

Sources: docs/introduction.mdx