{"slug": "agent-with-vercel-s-eve-framework", "title": "Agent with Vercel's Eve Framework", "summary": "Vercel open-sourced Eve, a framework for building durable AI agents with a filesystem-first approach. A developer tested it by building a shopping assistant that can search catalogs, check inventory, compare prices, read reviews, and place orders. Eve separates agent logic from communication channels, allowing the same agent to serve multiple platforms like Slack, Discord, and custom webhooks without code changes.", "body_md": "Vercel recently open-sourced [Eve](https://github.com/vercel/eve), a framework for building durable AI agents. It takes an opinionated, filesystem-first approach: instead of wiring up model loops, tool dispatch, and session persistence yourself, you author a directory of files and Eve handles the rest.\n\nI took it for a spin by building a shopping assistant — an agent that can search a product catalog, check inventory, compare prices, read reviews, and place orders. Here's what I found.\n\nEve draws a hard line between what the agent *is* and how it *communicates*. The agent is the reasoning core — model, tools, instructions. It doesn't know or care how users reach it. A channel is just comms — it handles inbound transport, auth, message format, and delivery for a specific platform.\n\nThis means the same agent can simultaneously serve a browser chat widget, a Slack bot, a CLI, and a custom webhook — without any conditional logic in the agent itself. You add surfaces by adding channel files, not by changing agent code.\n\nIn Eve, a **channel** is the edge adapter between a platform and your agent. It normalizes inbound messages, owns the conversation resume handle (`continuationToken`\n\n), and decides how responses get delivered back.\n\nThe default channel is `eve.ts`\n\n— the HTTP session API that the dev TUI, browser clients, and `curl`\n\nall talk to. But channels aren't limited to HTTP. Eve ships integrations for Slack, Discord, Teams, Telegram, Twilio (SMS/voice), GitHub, and Linear. You can also write custom channels for any surface (webhooks, WebSockets, internal systems).\n\nEach channel is a file under `agent/channels/`\n\n:\n\n```\nagent/channels/\n├── eve.ts      # HTTP API (always present, even without a file)\n├── slack.ts    # Slack DMs, mentions, buttons\n└── intake.ts   # Your custom webhook channel\n```\n\nThe key insight: your agent logic (instructions + tools) stays the same regardless of channel. You write the agent once, then expose it through multiple surfaces by adding channel files. The channel handles platform-specific concerns (auth, message format, delivery) while the agent handles reasoning.\n\nThe `eve.ts`\n\nchannel is always present — it provides a session-based HTTP API that the dev TUI, browser clients (`useEveAgent`\n\n), and `curl`\n\nall use. The key concept is **durable sessions**: you `POST`\n\nto create a session, stream events from it via NDJSON, and continue it with a `continuationToken`\n\n. Sessions survive server restarts and support reconnection at any event index (`?startIndex=N`\n\n). This is fundamentally different from stateless request/response — Eve owns the conversation state server-side.\n\nEve sessions aren't just \"kept in memory\" — they're backed by a workflow engine. Under the hood, every turn runs as a durable workflow built on the open-source [Workflow SDK](https://workflow-sdk.dev/). Eve checkpoints progress at each **step** boundary (one model call + its tool calls = one step). If the process crashes mid-turn, it resumes from the last completed step rather than replaying everything.\n\nLocally, this is just files on disk. Run your agent and you'll find a `.workflow-data/`\n\ndirectory:\n\n```\n.workflow-data/\n├── runs/       # one JSON file per session (workflow state)\n├── steps/      # checkpoint per completed step\n├── streams/    # event streams (what clients read via /stream)\n├── hooks/      # parked continuation tokens (waiting for input)\n└── events/     # workflow lifecycle events\n```\n\nThis means you can:\n\n`Ctrl+C`\n\n)`sessionId`\n\nand `continuationToken`\n\nThe session picks up exactly where it left off — including mid-turn recovery if a step was already completed before the crash.\n\nObviously, local files aren't scalable for production. Eve's durability is pluggable via the [Workflow SDK](https://workflow-sdk.dev/)'s \"World\" abstraction — the storage/queue/streaming backend. You pick a world package and Eve uses it for all session persistence:\n\n| World | Backend | Use case |\n|---|---|---|\n`@workflow/world-local` |\nFilesystem (`.workflow-data/` ) |\nLocal dev (default) |\n`@workflow/world-postgres` |\nPostgreSQL + graphile-worker | Self-hosted production |\n`@workflow/world-vercel` |\nVercel Workflow (managed) | Vercel deployments |\n`@workflow-worlds/redis` |\nRedis + BullMQ | Self-hosted, high throughput |\n`@workflow-worlds/mongodb` |\nMongoDB | Self-hosted |\n`@workflow-worlds/turso` |\nTurso/libSQL (embedded SQLite) | Edge/embedded |\n\nTo switch, you set it in `agent.ts`\n\n:\n\n```\nexport default defineAgent({\n  model: openai(\"gpt-4o\"),\n  modelContextWindowTokens: 128_000,\n  experimental: {\n    workflow: {\n      world: \"@workflow/world-postgres\",\n    },\n  },\n});\n```\n\nThe World interface has three responsibilities: **Storage** (persisting runs, steps, hooks via an append-only event log), **Queue** (dispatching workflow/step invocations with at-least-once delivery), and **Streams** (real-time event delivery to clients). You can also [build your own](https://workflow-sdk.dev/docs/deploying/building-a-world) if none of the existing options fit.\n\nTo make this concrete — I built a custom channel that exposes the Eve agent over the [AG-UI protocol](https://github.com/ag-ui-protocol/ag-ui) (SSE-based, used by CopilotKit and similar frameworks). The channel translates Eve's internal event stream into AG-UI's event vocabulary:\n\n``` js\n// agent/channels/agui.ts\nimport { defineChannel, POST, type Session } from \"eve/channels\";\nimport { EventEncoder } from \"@ag-ui/encoder\";\nimport { EventType, type BaseEvent, type RunAgentInput } from \"@ag-ui/core\";\n\nexport default defineChannel({\n  routes: [\n    POST(\"/agui\", async (req, { send }) => {\n      const body = (await req.json()) as RunAgentInput;\n      if (!body.threadId) {\n        return Response.json({ error: \"Missing 'threadId'.\" }, { status: 400 });\n      }\n\n      const { threadId } = body;\n      const runId = body.runId ?? randomUUID();\n      const messages = body.messages ?? [];\n\n      // AG-UI is stateless per request — clients send full message history.\n      // Pass prior messages as context so Eve's agent sees the conversation.\n      const lastUserIdx = messages.findLastIndex((m) => m.role === \"user\");\n      const context = messages.slice(0, lastUserIdx).map((m) =>\n        `[${m.role}]: ${typeof m.content === \"string\" ? m.content : JSON.stringify(m.content)}`\n      );\n\n      const session: Session = await send(\n        { message: messages[lastUserIdx]?.content ?? \"\", context },\n        { auth: null, continuationToken: `agui:${threadId}:${randomUUID()}` },\n      );\n\n      // Read Eve's event stream and translate to AG-UI SSE\n      const eveStream = await session.getEventStream();\n      const encoder = new EventEncoder();\n      // ... event mapping loop (see full source)\n    }),\n  ],\n});\n```\n\nThe event mapping is mostly mechanical — `actions.requested`\n\n→ `TOOL_CALL_START`\n\n/`ARGS`\n\n/`END`\n\n, `action.result`\n\n→ `TOOL_CALL_RESULT`\n\n, `message.appended`\n\n→ `TEXT_MESSAGE_CONTENT`\n\n, `turn.completed`\n\n→ `RUN_FINISHED`\n\n. But there were a few non-obvious gotchas:\n\n**1. Eve sessions are durable; AG-UI runs are not.** Eve's event stream never closes after a turn — it waits for the next message. You must close the response stream yourself after emitting `RUN_FINISHED`\n\n. If you don't, the client hangs forever waiting for more data.\n\n**2. Eve emits both turn.completed and session.waiting at turn boundaries.** If you naively emit\n\n`RUN_FINISHED`\n\nfor both, the AG-UI client throws: **3. AG-UI is stateless; Eve is stateful.** Each AG-UI request carries the full message history. Since Eve's `send()`\n\ncreates/continues sessions via `continuationToken`\n\n, you need a fresh token per request (otherwise Eve tries to continue a stale session). The conversation history goes through `context`\n\nso the agent sees prior turns.\n\n**4. Eve actions are typed unions.** `actions.requested`\n\ncontains a `RuntimeActionRequest[]`\n\nthat can be `tool-call`\n\n, `subagent-call`\n\n, or `load-skill`\n\n. You need to filter for `action.kind === \"tool-call\"`\n\nand use `action.toolName`\n\n/ `action.callId`\n\n(not `.name`\n\n/ `.id`\n\nwhich don't exist on the type).\n\nSame agent, same tools, same instructions — but now it speaks AG-UI over SSE at `POST /agui`\n\n. You could have the Eve HTTP channel, a Slack channel, and this AG-UI channel all running simultaneously, each talking to the same underlying agent.\n\nRun `pnpm dev`\n\n(or `npx eve dev`\n\n) and you get an interactive terminal UI that speaks the eve channel protocol locally:\n\n```\n☰eve  shopping-agent-orchestrator\n\n> show me laptops under $1000\n\n✓ search_products  query=\"laptop\" maxPrice=1000 → 1 result\n✓ get_pricing  product=\"Dell XPS 13\" → $899.10 (Summer Sale)\n✓ check_stock  product=\"Dell XPS 13\" → 12 units\n\nI found the Dell XPS 13 for $899.10 (10% off with the Summer Sale).\nIt's in stock with 12 units available. Would you like to place an order?\n```\n\nThe TUI shows:\n\n`/model`\n\nto switch models, `/new`\n\nfor a fresh session)File changes trigger a hot rebuild — edit a tool, and it's live on the next message.\n\n`modelContextWindowTokens`\n\nIf you're using a non-gateway model (custom `baseURL`\n\n, direct provider), Eve's build will fail with a cryptic error about compaction metadata. You need to explicitly tell it the context window size:\n\n``` js\n// agent/agent.ts\nimport { createOpenAI } from \"@ai-sdk/openai\";\nimport { defineAgent } from \"eve\";\n\nconst openai = createOpenAI({\n  apiKey: process.env.OPENAI_API_KEY!,\n  baseURL: process.env.OPENAI_BASE_URL, // custom endpoint\n});\n\nexport default defineAgent({\n  model: openai(\"gpt-4o\"),\n  modelContextWindowTokens: 128_000, // required for direct providers\n});\n```\n\n**What is modelContextWindowTokens?** Eve has a built-in \"compaction\" system that prevents long conversations from overflowing the model's context window. When the conversation reaches ~90% of the window, Eve automatically summarizes older turns into a compressed form so the session can keep going indefinitely. To do this, Eve needs to know how big the window is. Gateway models (like\n\n`\"openai/gpt-4o\"`\n\n) have this metadata in Vercel's catalog. But when you bring your own provider via `createOpenAI()`\n\n, Eve has no way to look it up — so you tell it explicitly.Without this field, the build fails at compile time rather than silently skipping compaction at runtime. The error message (`\"does not have known AI Gateway context window metadata\"`\n\n) doesn't make the fix obvious.\n\nPlease feel free to reach out on twitter [@roamingcode](https://twitter.com/roamingcode)", "url": "https://wpnews.pro/news/agent-with-vercel-s-eve-framework", "canonical_source": "https://dev.to/stormhub/agent-with-vercels-eve-framework-3c2l", "published_at": "2026-06-22 04:51:54+00:00", "updated_at": "2026-06-22 05:09:43.167942+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models", "ai-infrastructure"], "entities": ["Vercel", "Eve", "Workflow SDK", "Slack", "Discord", "Teams", "Telegram", "Twilio"], "alternates": {"html": "https://wpnews.pro/news/agent-with-vercel-s-eve-framework", "markdown": "https://wpnews.pro/news/agent-with-vercel-s-eve-framework.md", "text": "https://wpnews.pro/news/agent-with-vercel-s-eve-framework.txt", "jsonld": "https://wpnews.pro/news/agent-with-vercel-s-eve-framework.jsonld"}}