Execution Model and Durability

Purpose and Scope

This page explains how eve keeps agent work durable while preserving a simple authoring model for developers. In eve, a session is not just an in-memory chat transcript. It is a long-lived durable conversation or task that can continue across multiple user requests, process restarts, timeouts, and redeploys. The practical result is that agent authors can focus on capabilities such as instructions, tools, channels, sandbox access, and subagents while eve owns the runtime loop that persists and resumes work.

Sources: docs/concepts/execution-model-and-durability.md

The most important mental model is that eve separates what you author from how execution is made reliable. You do not write workflow orchestration code for normal agents. Instead, each user interaction becomes durable runtime work managed by eve. Tools, sandbox operations, and subagent calls can feel synchronous to your code, but they run inside a workflow-backed session that records progress at boundaries. This makes the same agent easier to operate locally, in self-hosted processes, and on Vercel.

Sources: docs/concepts/execution-model-and-durability.md

Relevant Source Files

• docs/concepts/execution-model-and-durability.md — Defines the public durability model: sessions, turns, steps, workflow-backed checkpointing, local and Vercel workflow worlds, restart behavior, and advanced world selection.

Sessions, Turns, and Steps

eve describes work with three nested units: session, turn, and step. A session is the whole durable conversation or task. It may span days or weeks and may receive many user or channel messages over its lifetime. A turn is one inbound user message and all work triggered by that message until the agent produces its response. A step is a durable checkpoint within a turn, covering one model call and the tool calls that model call makes.

Sources: docs/concepts/execution-model-and-durability.md

This nesting matters because it explains where persistence happens and what gets retried. A session preserves the long-running conversation and authored state. A turn gives each user message a unit of work that can be observed, streamed, and resumed. A step is the checkpoint boundary that lets eve avoid rerunning completed work after an interruption. When you reason about side effects, streaming, approvals, or deployment changes, identify which session, turn, and step the behavior belongs to first.

Sources: docs/concepts/execution-model-and-durability.md

Workflow-Backed Durable Execution

Every turn runs as a durable workflow. The first-party docs state that eve builds on the open-source Workflow SDK and uses Vercel Workflow when deployed on Vercel. At each step boundary, eve checkpoints progress and serializes durable state. That checkpointing is what allows a process crash, timeout, or redeploy to resume from the last completed step instead of beginning the whole turn again. Completed steps are replayed from recorded results, not executed again.

Sources: docs/concepts/execution-model-and-durability.md

The Workflow SDK layer is intentionally an implementation detail for ordinary eve authors. Channels, tools, and hooks do not call workflow primitives such as start or resume hooks directly. This is a design constraint as much as a convenience: eve wants authored capabilities to remain filesystem-first and agent-oriented, while the runtime handles workflow lifecycle, dispatch, state serialization, queues, hooks, and stream behavior underneath.

Sources: docs/concepts/execution-model-and-durability.md

Local, Self-Hosted, and Vercel Runtime Worlds

The same durable model applies across environments, but the backing workflow world changes. In local development and in a self-deployed eve start process, eve uses the Workflow SDK local world by default. That local world persists workflow runs on disk, normally under .workflow-data, and dispatches through Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow, which adds platform behavior such as latest production deployment routing and dashboard run metadata.

Sources: docs/concepts/execution-model-and-durability.md

Nitro is part of the HTTP and workflow entrypoint hosting story, but it is not the workflow state store and it is not the sandbox runtime. The docs draw a clear boundary: Workflow uses the active world implementation, and Sandbox uses the backend selected by agent/sandbox or defaultBackend(). Treat these as separate adapter choices when planning production architecture, because changing request hosting, durable state, and execution isolation are different decisions.

Sources: docs/concepts/execution-model-and-durability.md

Restartability and Side Effects

When a run is interrupted, eve resumes from the last completed step. That gives you strong restart behavior for normal model and tool execution, but it also creates a specific responsibility for non-idempotent side effects. If a step is interrupted mid-execution, that step may run again. Operations such as charging a card, sending an email, issuing a refund, or committing an external mutation should therefore be idempotent or protected behind an approval flow.

Sources: docs/concepts/execution-model-and-durability.md

This retry boundary is the main durability rule agent authors need to internalize. Completed steps never re-run, because eve replays their recorded result. Incomplete steps can re-run, because the durable workflow cannot assume the interrupted side effect completed safely. Use external idempotency keys, durable state, or human-in-the-loop approval for actions where duplicate execution would be harmful. You do not need to configure durability itself; sessions are durable by default.

Sources: docs/concepts/execution-model-and-durability.md

Deployment Updates and Existing Sessions

A durable session can outlive a single deployment. The docs state that when a Vercel production deployment changes, the next model turn in an existing session uses the current instructions, model, and tools from that deployment. The session keeps its conversation history and authored state, so identity-based channels such as Telegram private chats or Twilio phone-number conversations can adopt agent updates without requiring users to start over.

Sources: docs/concepts/execution-model-and-durability.md

This behavior is useful for long-running agents, but it also means deployment changes should be compatible with existing conversation history. If you rename tools, change required schemas, or alter state assumptions, think about what an in-progress or returning session will see on its next turn. The durable session gives continuity; your deployment process should preserve enough compatibility that the new agent version can interpret older context safely.

Sources: docs/concepts/execution-model-and-durability.md

Advanced Workflow World Configuration

Most projects do not need to configure the workflow world. For advanced self-hosted deployments, the root agent.ts can select an installed Workflow world package through experimental.workflow.world. The selected package backs workflow state, queues, hooks, and streams. Secrets and deployment-specific options should stay in runtime environment variables read by that package rather than being embedded in agent.ts.

Sources: docs/concepts/execution-model-and-durability.md

import { defineAgent } from "eve";
 
export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  experimental: {
    workflow: {
      world: "@workflow/world-postgres",
    },
  },
});

The version relationship is part of the contract. The selected world must match eve's bundled @workflow/* line, described in the docs as the 5.0.0-beta line. Pin the world explicitly for self-hosted deployments. A mismatched world can fail during run replay with a ZodError: invalid_union, which is exactly the kind of failure durable execution is designed to avoid during normal operation.

Sources: docs/concepts/execution-model-and-durability.md

System-to-Code Mapping

Practical Next Steps

When building an eve agent, design tools as if a partially completed step can be retried. Use idempotency for external writes, approval gates for sensitive actions, and stable schemas for state that may be read by future deployments. You can then rely on eve's default durable session lifecycle for crashes, redeploys, and long-running conversations instead of building your own workflow orchestration. Next, read the sessions and streaming documentation to understand the handles and events exposed to clients, then review the security model before giving tools access to external systems.