Concepts

eve turns a filesystem project into a durable backend AI agent. You author the agent under an agent/ directory, and eve discovers those files, validates them, compiles a manifest, and serves the runtime as a deployable app.

An eve agent is a set of named files and directories under agent/. Directories are auto-discovered by name, so adding a capability is usually as simple as adding a file:

• agent/instructions.md: the always-on system prompt.
• agent/agent.ts: runtime config, such as model and options, through defineAgent.
• agent/tools/*.ts: one typed tool per file; the filename becomes the runtime tool name.
• agent/skills/*: optional, on-demand procedures the model loads only when relevant.
• agent/subagents/*: optional child agents the model delegates focused subtasks to.
• agent/channels/*: platform entry points such as HTTP and Slack.
• agent/connections/*: typed integrations with external services.
• agent/sandbox/*: the agent's isolated compute environment.
• agent/instrumentation.ts: optional OpenTelemetry setup for AI SDK spans.

The agent/agent.ts file defines the agent runtime. The most important setting is the model:

import { defineAgent } from 'eve';
 
export default defineAgent({
  model: 'openai/gpt-5.4-mini',
});

Model strings resolve through AI Gateway on Vercel, so deployed agents can use Vercel OIDC instead of managing provider API keys directly.

A session is the durable conversation or task started by a channel or HTTP request. Each user message or external event creates a turn. During a turn, the agent can call tools, load skills, read or write sandbox files, delegate to subagents, and stream lifecycle events back to the client.

eve exposes HTTP routes for creating a session and attaching to its stream:

curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Summarize this repository"}'

The response includes an x-eve-session-id header. Use that id to reattach to the stream:

curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream

eve sessions run on top of Vercel Workflows. Workflows persist progress as an event log and deterministically replay it to reconstruct state, so a session can survive cold starts, redeploys, and long pauses while it waits for the next message or a tool result.

On Vercel, the compiled agent runs from Vercel Functions. Because agent turns are long-running and stream incrementally, eve benefits from Fluid Compute, which is enabled by default for new projects.

Channels are entry points into the same agent runtime. A channel can start sessions, route platform events into turns, and apply platform-specific authentication or formatting. eve agents can expose HTTP routes and can add channel files for platforms such as Slack.

Route-auth secrets, preview-protection bypass secrets, and other channel-specific configuration live in project environment variables.

Tools are typed actions the model can call during a turn. Each file in agent/tools/ defines one tool, and the filename becomes the tool name the model sees. Learn more about adding tools to your eve agent.

You can use Jev to review proposed tool calls against your approval criteria before they run. Calls classified as clear run automatically, while caution calls pause for human approval. Follow Automatically approve tool calls in eve with Jev to configure the policy and test its failure paths.

Skills are larger procedures or reference material that the model loads on demand. Use skills for repeatable workflows, multi-step instructions, or domain knowledge that should not be part of the always-on prompt. Keeping skills separate helps the model use the right context only when it is relevant.

Install skills into agent/skills/ with the skills CLI from your eve project directory.

A subagent is a child agent that the model delegates a focused subtask to. Use one to run work in parallel, give a child a narrower set of tools, or give a specialist its own identity. Unlike a skill, which adds instructions to the running agent, a subagent runs as a separate agent with fresh conversation history and state. eve offers two kinds: the built-in agent tool delegates to a copy of the current agent, and declared subagents live under agent/subagents/* with their own config.

Learn more about using subagents with eve.

Connections describe typed integrations with external services. Use them to keep provider-specific configuration and credential access outside the model prompt and tool implementation details.

For delegated user or team credentials, authorize eve connections with Vercel Connect. For model access, use AI Gateway model strings in the agent config.

Every eve agent has one sandbox: an isolated, bash-style compute environment with its own filesystem. Framework tools such as bash, read_file, and write_file target it, and authored tools can target it too.

On Vercel, the sandbox can run on Vercel Sandbox, using ephemeral microVMs for untrusted or model-generated commands.

Every eve project gets Agent Runs in the Vercel dashboard. Agent Runs shows sessions, turns, tool calls, reasoning, timing, and token usage without an instrumentation file.

New eve deployments automatically configure tracing to sample at 100%. Existing deployments must configure sampling. See Agent Runs for setup, pricing, retention, and trace-content controls.

See eve observability for process-wide OpenTelemetry settings, built-in exports, and third-party destinations.

• Getting started: create your first eve project.
• Pricing and Limits: understand the Vercel resources eve uses.
• Agent Runs: inspect agent sessions and configure trace collection.
• Observability: configure OpenTelemetry exports and policies.