The Open Framework for Building Agents
docs: reorganize information architecture (#1236)
Colton Padden6c314fa7e6a2
diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.tsindex 94f726095..d17ba528f 100644--- a/apps/docs/next.config.ts+++ b/apps/docs/next.config.ts@@ -56,12 +56,22 @@ const config: NextConfig = {return [{source: "/docs",- destination: "/docs/introduction",+ destination: "/docs/getting-started",permanent: true,},{source: "/:lang/docs",- destination: "/:lang/docs/introduction",+ destination: "/:lang/docs/getting-started",+ permanent: true,+ },+ {+ source: "/docs/introduction",+ destination: "/docs/getting-started",+ permanent: true,+ },+ {+ source: "/:lang/docs/introduction",+ destination: "/:lang/docs/getting-started",permanent: true,},// Evals moved from a single Advanced page to a top-level section.diff --git a/docs/README.md b/docs/README.mdindex 2273dc354..0ca1ef89c 100644--- a/docs/README.md+++ b/docs/README.md@@ -33,26 +33,27 @@ Casing convention:Read in this order:-1. [Introduction](./introduction.md)-2. [Getting Started](./getting-started.mdx)-3. [Project Layout](./reference/project-layout.md)-4. [`agent.ts`](./agent-config.md)-5. [TypeScript API](./reference/typescript-api.md)-6. [Context Control](./concepts/context-control.md)-7. [Skills](./skills.mdx)-8. [Tools](./tools/overview.mdx)-9. [Connections](./connections/overview.mdx)-10. [Sandboxes](./sandbox.mdx)-11. [Channels](./channels/overview.mdx)-12. [Session Context](./reference/typescript-api.md)-13. [Sessions And Streaming](./concepts/sessions-runs-and-streaming.md)-14. [TypeScript SDK](./clients/typescript-sdk/overview.mdx)-15. [Subagents](./subagents.mdx)-16. [Schedules](./schedules.mdx)-17. [Evals](./evals/overview.mdx)-18. [Auth And Route Protection](./develop/auth-and-route-protection.md)-19. [Vercel Deployment](./develop/deployment.md)-20. [CLI, Build, And Debugging](./reference/cli.md)+1. [Getting Started](./getting-started.mdx)+2. [Installation](./installation.mdx)+3. [Project Structure](./project-structure.mdx)+4. [Project Layout](./reference/project-layout.md)+5. [`agent.ts`](./agent-config.md)+6. [TypeScript API](./reference/typescript-api.md)+7. [Context Control](./concepts/context-control.md)+8. [Skills](./skills.mdx)+9. [Tools](./tools/overview.mdx)+10. [Connections](./connections/overview.mdx)+11. [Sandboxes](./sandbox.mdx)+12. [Channels](./channels/overview.mdx)+13. [Session Context](./reference/typescript-api.md)+14. [Sessions And Streaming](./concepts/sessions-runs-and-streaming.md)+15. [TypeScript SDK](./clients/typescript-sdk/overview.mdx)+16. [Subagents](./subagents.mdx)+17. [Schedules](./schedules.mdx)+18. [Evals](./evals/overview.mdx)+19. [Auth And Route Protection](./develop/auth-and-route-protection.md)+20. [Vercel Deployment](./develop/deployment.md)+21. [CLI, Build, And Debugging](./reference/cli.md)## The public mental modeldiff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdxindex 04c6fdf47..40acac37b 100644--- a/docs/channels/overview.mdx+++ b/docs/channels/overview.mdx@@ -11,6 +11,8 @@ A channel is the edge adapter between a platform and your agent. It does three teve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery.+After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.+Each channel has its own provider terms, data flow, auth model, and user-consent expectations. Before sending non-public, sensitive, regulated, or production data through a channel, confirm that the channel provider and your configured scopes, signature checks, route auth, and delivery behavior are appropriate for your use case.## Where channels livediff --git a/docs/getting-started.mdx b/docs/getting-started.mdxindex 7cb35355d..4f3c2390c 100644--- a/docs/getting-started.mdx+++ b/docs/getting-started.mdx@@ -1,206 +1,23 @@---title: "Getting Started"-description: "Install eve, scaffold your first agent, give it a tool, and run it locally."+description: "Create an eve project, learn its filesystem layout, and start adding capabilities."+contentType: "Landing"----eve is a filesystem-first framework for durable agents. You write capabilities under `agent/`, and eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. You'll scaffold an app, add a tool, run it locally, then create, stream, and continue a session over HTTP.+eve agents are TypeScript projects. You describe an agent with files under `agent/`, then eve runs it as a durable service.-## Prerequisites+## Start in order-- Node 24 or newer-- npm (bundled with Node)-- A model credential (see below)+1. [Install eve](/docs/installation): create a project, configure a model credential, and run it locally+2. [Learn the project structure](/docs/project-structure): see which files eve discovers and where each capability belongs+3. [Build your first agent](/docs/tutorial/first-agent): add tools, state, and an interface for a useful workflow-The scaffold's default model is `anthropic/claude-sonnet-5`, which routes through the Vercel AI Gateway. Set one of these before you run the agent:+## What you need-- A gateway model id needs `AI_GATEWAY_API_KEY`, or a `VERCEL_OIDC_TOKEN` pulled with `vercel link`.-- A direct provider model uses that provider's AI SDK package and API key. For example, `anthropic("claude-...")` from `@ai-sdk/anthropic` needs `ANTHROPIC_API_KEY`.+- Node.js 24 or newer+- npm, which Node.js includes+- A model credential for the model your agent uses-You are responsible for selecting a model, provider, and channel appropriate for your data and use case, and for complying with each provider's terms (as listed per model) and data-processing requirements.+## Choose your next step-If you skip this, the dev TUI flags the missing credential and its `/model` command walks you through pasting a key or linking a project.--## Quick start--`npx` runs `eve init` without installing eve first:--```bash-npx eve@latest init my-agent-```--The command:--- Creates a child directory using the current workspace or launcher package manager, and uses eve's default model-- Installs dependencies and initializes Git-- When a supported coding-agent REPL (Claude Code, Codex, Cursor, Droid, Gemini CLI, opencode, or Pi) is on `PATH`, asks whether to open an available REPL or start the development server; otherwise starts the server and opens the interactive [terminal UI](./guides/dev-tui)--Type a message and watch the model loop run. Pass `--channel-web-nextjs` to add the Web Chat application. Every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless.--When you choose one of those REPLs, eve starts it with a project-specific-prompt that guides the setup. The prompt distinguishes `eve dev`, which starts-eve's HMR server and the agent's terminal REPL, from `eve dev --no-ui`, which is-the controllable background mode for verification.--`eve init` holds the terminal, so stop it with Ctrl+C to get your shell back before editing the generated agent. The command does not create a Vercel project or deploy.--To add eve to an existing project, run `eve init .` from a directory that already has a `package.json` and no `agent/` files yet. eve adds the missing `eve`, `ai`, and `zod` dependencies without touching anything else the project owns. The eve dependency and the Node engine come from the same release. eve pins `engines.node` to the lowest major that release supports (for example `24.x`). It keeps an existing range only when every version that range allows stays within that major; otherwise it replaces the range and prints a warning.--## Manual installation--To wire eve into an existing app by hand instead of using `eve init`, first declare a compatible Node runtime in `package.json`:--```json-{- "engines": {- "node": "24.x"- }-}-```--Then install the dependencies and author the two files the runtime needs. The `eve init` scaffold adds `ai` and `zod` for you; by hand you install all three:--```bash-npm install eve@latest ai zod-```--### Project files--A minimal agent is two files; you add tools as you need them.--`agent/instructions.md` is the always-on system prompt:--```md-You are a concise assistant. Use tools when they are available.-```--`agent/agent.ts` holds runtime config:--```ts-import { defineAgent } from "eve";--export default defineAgent({- model: "anthropic/claude-sonnet-5",-});-```--Before using real customer data, confirm the selected model provider's terms, routing path, and retention settings are appropriate for that data.--Even at this size the agent can already do real work. The default harness gives it file, shell, web, and delegation tools out of the box. See [Default harness](./concepts/default-harness) for the full set and how to override or disable any of them.--### Add your first tool--The filename becomes the tool name the model sees, and it must be snake_case ASCII. Create `agent/tools/get_weather.ts`:--```ts-import { defineTool } from "eve/tools";-import { z } from "zod";--// The model sees this tool as `get_weather`, from the filename.-export default defineTool({- description: "Get the current weather for a city.",- inputSchema: z.object({ city: z.string().min(1) }),- async execute({ city }) {- return { city, condition: "Sunny", temperatureF: 72 };- },-});-```--Tools run in your app runtime with full `process.env`, not inside the [sandbox](./sandbox). More in [Tools](./tools).--## Run the app--A scaffolded app has a `dev` script, so from the app root run:--```bash-npm run dev-```--The manual path authors no `dev` script. Run the binary through `npx` instead:--```bash-npx eve dev-```--Other commands the eve binary provides (prefix each with `npx`, or add a matching package.json script):--- `eve info`: show the active routes and compiled artifacts-- `eve build`: compile the agent into `.eve/` and build the host output-- `eve start`: serve the built output-- `eve dev`: start the local runtime and open the interactive [terminal UI](./guides/dev-tui)--In the dev TUI, type a message and watch it happen in order. First the `get_weather` call, then its result, then the reply.--The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment/overview).--## Send a message--Every eve app exposes the same stable HTTP API. Start a durable session:--```bash-curl -X POST http://127.0.0.1:2000/eve/v1/session \- -H 'content-type: application/json' \- -d '{"message":"What is the weather in Brooklyn?"}'-```--The response comes back with two things you'll reuse:--- a `continuationToken` in the JSON body, to resume this conversation-- an `x-eve-session-id` header that identifies the run to stream--## Stream the session--Attach to the session stream:--```bash-curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream-```--The stream is NDJSON, served as `application/x-ndjson; charset=utf-8`. For this run you'll see a handful of lifecycle events:--- `session.started`-- `actions.requested` (the `get_weather` call)-- `action.result`-- `message.completed` (the reply)-- `session.completed`--`reasoning.appended` and `message.appended` are optional live-streaming events. Clients that can't surface incremental output can ignore them and rely on `reasoning.completed` and `message.completed`.--Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning events in your application.--The full set covers more lifecycle, human-in-the-loop, and authorization events, including `input.requested`, `turn.failed`, `authorization.required`, and `authorization.completed`. See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for every event and its data shape.--## Send a follow-up message--When the session is waiting for the next user message, post a follow-up with the token:--```bash-curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \- -H 'content-type: application/json' \- -d '{"continuationToken":"<token>","message":"Now do Queens."}'-```--See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for the full contract.--## Setting up with a coding agent--If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:--<CopyPrompt text="Set up an eve agent for the user. eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/docs; before eve is installed, read the published Introduction and Getting Started pages. If the project has no eve app, scaffold one with `npx eve@latest init <name>`; add `--channel-web-nextjs` only when the user wants Web Chat. In a coding-agent launch, init installs dependencies and prints the project-specific dev command instead of starting the interactive terminal UI. A fresh project also initializes Git; an existing app keeps its repository and scripts. To add eve to an existing app, run `eve init .`, or install the dependencies by hand with `npm install eve@latest ai zod` (init adds ai and zod; the by-hand path needs all three). Make sure agent/agent.ts and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Start eve in a controllable background process with `npx eve dev --no-ui`, wait for the server URL, then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Stop the dev process after verification. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">- Set up an eve agent: read the eve docs (bundled at node_modules/eve/docs once eve is- installed), scaffold with `npx eve@latest init <name>` (or `npm install eve@latest ai zod` in an existing app), add- a typed tool at agent/tools/get_weather.ts, run it with `npx eve dev --no-ui`, then create a session, stream- it, and send a follow-up.-</CopyPrompt>--Once `eve` is a dependency, the package bundles the full docs, so the agent can read them locally at `node_modules/eve/docs/` without fetching anything.--To add a platform channel after setup, run `eve channels add slack` from an interactive terminal. The init flags are covered in [Quick start](#quick-start).--## What to read next--- [Instructions](./instructions) and [Tools](./tools): the core building blocks-- [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI-- [Frontend](./guides/frontend/overview): browser chat with `useEveAgent`-- [TypeScript SDK](./guides/client/overview): call the agent from scripts or server-side code-- [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming): the durable session model-- [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough+Start with [Installation](/docs/installation) when you need a new project. Read [Project structure](/docs/project-structure) when you already have an eve project or want to add a capability.diff --git a/docs/installation.mdx b/docs/installation.mdxnew file mode 100644index 000000000..3c9ce4f3d--- /dev/null+++ b/docs/installation.mdx@@ -0,0 +1,60 @@+---+title: "Installation"+description: "Create an eve project, configure a model credential, and run it locally."+contentType: "How-to"+---++Create an eve project with `eve init`. The scaffold installs dependencies, creates the agent files, and starts the local development server.++## Configure a model credential++The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`.++You can also use a direct provider model. Install its AI SDK provider package and set that provider's API key before you run the agent.++Choose a model, provider, and channel that meet your data-processing and compliance requirements.++## Create a project++Run `eve init` with a project name:++```bash+npx eve@latest init my-agent+```++The command creates `my-agent/`, installs dependencies, initializes Git, and starts eve's development server. If a supported coding-agent REPL is available, eve offers to open it instead.++## Run the agent++From the project root, run the generated development command:++```bash+cd my-agent+npm run dev+```++The terminal UI sends messages to your agent. Stop the server with Ctrl+C when you need your shell for another command.++## Add eve to an existing project++Run `eve init .` from a project with a `package.json` and no existing `agent/` files:++```bash+npx eve@latest init .+```++eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.++## Install manually++Install the runtime dependencies when you do not want to use the scaffold:++```bash+npm install eve@latest ai zod+```++Declare Node.js 24 in `package.json`, then create `agent/agent.ts` and `agent/instructions.md`. [Project structure](/docs/project-structure) shows the required layout, and [`agent.ts`](./agent-config) documents the runtime configuration.++## Continue building++Read [Project structure](/docs/project-structure) before adding instructions, tools, connections, or channels.diff --git a/docs/introduction.mdx b/docs/introduction.mdxdeleted file mode 100644index a96c05446..000000000--- a/docs/introduction.mdx+++ /dev/null@@ -1,103 +0,0 @@-----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/`diff --git a/docs/meta.json b/docs/meta.jsonindex a2183e93a..1a5385750 100644--- a/docs/meta.json+++ b/docs/meta.json@@ -1,8 +1,10 @@{"pages": [- "introduction",+ "---Getting Started---","getting-started",- "---",+ "installation",+ "project-structure",+ "---Build Your Agent---","agent-config","instructions","tools",@@ -14,12 +16,11 @@"subagents","schedules","evals",- "---",+ "---Learn More---",+ "tutorial","guides","concepts","patterns",- "---",- "reference",- "tutorial"+ "reference"]}diff --git a/docs/project-structure.mdx b/docs/project-structure.mdxnew file mode 100644index 000000000..e7f73d185--- /dev/null+++ b/docs/project-structure.mdx@@ -0,0 +1,53 @@+---+title: "Project Structure"+description: "Learn the files eve discovers and how their paths define agent capabilities."+contentType: "Conceptual"+---++eve builds an agent from files under `agent/`. A file's location determines what eve loads, and most paths also determine the capability's name.++## Start with two files++A minimal agent needs an instructions file and optional runtime configuration:++```text+my-agent/+├── package.json+├── agent/+│ ├── agent.ts+│ └── instructions.md+└── evals/+```++`agent/instructions.md` is the agent's always-on system prompt. `agent/agent.ts` selects the model and configures runtime behavior. Omit `agent.ts` when the defaults are sufficient.++## Add capabilities as directories++Add a directory when the agent needs that capability:++| Path | Purpose |+| ----------------------------------- | --------------------------------------------- |+| [`tools/`](./tools) | Typed functions the model can call |+| [`skills/`](./skills) | Procedures the model loads when useful |+| [`channels/`](./channels/overview) | HTTP and messaging entry points |+| [`connections/`](/docs/connections) | MCP and OpenAPI services |+| [`sandbox/`](./sandbox) | Controlled workspace files and commands |+| [`subagents/`](./subagents) | Specialist agents the root agent delegates to |+| [`schedules/`](./schedules) | Recurring work |+| `lib/` | Shared code imported by agent files |++The `evals/` directory sits beside `agent/`. It holds the checks that measure whether the agent completes its tasks. See [Evals](./evals/overview).++## Let paths name capabilities++The path supplies the name. This tool file becomes the `get_weather` tool:++```text+agent/tools/get_weather.ts+```++The same rule applies to connections, skills, and subagents. You do not add a duplicate `name` or `id` field to the definition.++## Use the full layout reference++[Project layout](./reference/project-layout) lists every supported slot, the root and subagent boundaries, and the file-discovery rules.diff --git a/docs/tutorial/meta.json b/docs/tutorial/meta.jsonindex fa3b554ce..4d874fb0f 100644--- a/docs/tutorial/meta.json+++ b/docs/tutorial/meta.json@@ -1,5 +1,5 @@{- "title": "Build an Agent",+ "title": "Tutorial","pages": ["first-agent","how-it-runs",