---
title: "Introduction"
description: "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.

## An eve project at a glance

A small eve app looks like this:

```text
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`](./agent-config) chooses the model and configures runtime options.
- [`tools/`](./tools) holds typed functions the model can call.
- [`skills/`](./skills) holds longer procedures the model loads only when they are useful.
- [`channels/`](./channels/overview) 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](./reference/project-layout). A file's location says what it does, and its path usually gives it a name. For example, this file:

```text
agent/tools/get_weather.ts
```

defines a tool named `get_weather`:

```ts
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](./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](./tools)
- Resume after that answer arrives
- Keep durable state across turns

Under the hood, eve uses the open-source [Workflow SDK](https://workflow-sdk.dev) 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/`](./connections) | Tools from external MCP or OpenAPI services      |
| [`hooks/`](./guides/hooks)      | Code that reacts to lifecycle and stream events  |
| [`sandbox/`](./sandbox)         | A controlled workspace for files and commands    |
| [`subagents/`](./subagents)     | Specialist agents the root agent can delegate to |
| [`schedules/`](./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.

## What to read next

- [Getting started](./getting-started): scaffold and run your first agent
- [Tools](./tools): the typed actions your agent calls
- [Instructions](./instructions): the always-on system prompt that shapes behavior
- [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI
- [Connections](./connections): pull in tools from external services
- [Project layout](./reference/project-layout): every authored slot under `agent/`
