How to Build Production AI Agents with Vercel Eve: A Step-by-Step Guide
Vercel Eve lets you define agents as folders of markdown and TypeScript, then deploy them to production with durable sessions and human-in-the-loop.
What Vercel Eve Actually Is (And Why It’s Worth Learning)
Building production AI agents used to mean choosing between two bad options: a framework that was easy to prototype with but couldn’t handle real traffic, or a custom infrastructure setup that took weeks to get right. Vercel Eve takes a different approach.
Eve is Vercel’s agent runtime that lets you define agents as plain folders containing markdown and TypeScript files. You write the logic, describe the behavior, and deploy to Vercel’s infrastructure — complete with durable sessions, human-in-the-loop checkpoints, and multi-agent coordination. No separate backend needed, no custom state management bolted on.
This guide covers everything you need to go from zero to a production-ready agent: project structure, agent definitions, deployment, durable sessions, and how to wire in human oversight. By the end, you’ll have a working agent running on Vercel infrastructure with proper session handling.
Prerequisites Before You Start
Getting set up takes about 10 minutes. You’ll need:
- Node.js 18 or later — Eve uses modern Node APIs throughout
- Vercel CLI — Install with
npm i -g verceland authenticate withvercel login - A Vercel account — Free tier works fine for development; Pro is recommended for production workloads
- Basic TypeScript familiarity — You don’t need to be an expert, but you should understand interfaces and async/await
- An LLM API key — Eve supports OpenAI, Anthropic, and other providers via environment variables
Once you have those, initialize a new project:
npx create-eve-app my-agent
cd my-agent
npm installThis scaffolds the directory structure and installs dependencies. The folder you end up with is the core mental model for everything that follows.
Understanding the File-Based Agent Structure
The fundamental idea behind Eve is that each agent is a folder. That folder contains two things: a markdown file that describes the agent’s purpose and behavior, and TypeScript files that implement its logic.
Here’s what a basic project looks like:
my-agent/
├── agents/
│ ├── support-agent/
│ │ ├── agent.md
│ │ ├── tools.ts
│ │ └── index.ts
│ └── triage-agent/
│ ├── agent.md
│ └── index.ts
├── eve.config.ts
└── package.jsonThis structure matters for a few reasons. First, it makes agents self-contained — you can move, duplicate, or archive an agent by moving its folder. Second, the markdown file serves as both documentation and runtime configuration, which keeps behavior and code in sync. Third, the TypeScript files handle tool definitions, business logic, and API calls, keeping executable code separate from behavioral descriptions.
The agent.md File
The agent.md file is how you define an agent’s identity, goals, and constraints in plain language. Eve parses this file at runtime and uses it to initialize the agent’s system context.
A minimal agent.md looks like this:
# Support Agent
## Purpose
Handle incoming customer support requests by diagnosing issues, suggesting solutions, and escalating when needed.
## Behavior
- Always ask clarifying questions before diagnosing
- Escalate to human review if the issue involves billing or account security
- Keep responses under 150 words unless the user explicitly asks for detail
## Tools Available
- search_knowledge_base
- create_ticket
- escalate_to_human
## Session Behavior
Maintain context across a full support conversation. A session ends when the issue is resolved or escalated.The markdown structure isn’t arbitrary. Eve looks for specific H2 sections — Purpose, Behavior, Tools Available, and Session Behavior — and maps them to runtime configuration. You can add custom sections, and they’ll be passed to the model as additional context.
The index.ts File
The index.ts file is where you wire together the agent’s runtime behavior. It imports the Eve SDK, registers tools, and exports the agent handler.
import { createAgent } from "@vercel/eve";
import { tools } from "./tools";
export default createAgent({
tools,
onMessage: async (message, session) => {
// Your custom pre-processing logic here
return message;
},
onComplete: async (response, session) => {
// Post-processing or logging
await logToDatabase(session.id, response);
}
});The createAgent function is the entry point. It accepts tools, lifecycle hooks, and session configuration. You’re not required to implement every hook — Eve provides sensible defaults for everything you leave out.
Defining Tools in TypeScript
Tools are what give an agent real capabilities. In Eve, each tool is a typed TypeScript function that the agent can call during a conversation or task.
Your tools.ts file exports an array of tool definitions:
import { defineTool } from "@vercel/eve";
import { z } from "zod";
export const tools = [
defineTool({
name: "search_knowledge_base",
description: "Search the internal knowledge base for articles and documentation",
input: z.object({
query: z.string().describe("The search query"),
limit: z.number().optional().default(5)
}),
execute: async ({ query, limit }) => {
const results = await fetch(`/api/kb?q=${encodeURIComponent(query)}&limit=${limit}`);
return results.json();
}
}),
defineTool({
name: "create_ticket",
description: "Create a support ticket in the ticketing system",
input: z.object({
title: z.string(),
description: z.string(),
priority: z.enum(["low", "medium", "high", "urgent"])
}),
execute: async (input) => {
// Ticket creation logic
return { ticketId: "T-1234", status: "created" };
}
})
];Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
A few things worth noting here. Eve uses Zod for input validation — this catches malformed calls before they hit your execution logic. The description field on each tool and each parameter is passed directly to the model, so clear descriptions significantly improve tool selection accuracy.
Tools run server-side in Vercel’s edge runtime by default, but you can configure specific tools to run in Node.js if they require Node-specific APIs.
Deploying to Production
Once your agent structure is in place, deployment is a single command:
vercel deployEve’s build step detects the agents/ directory, compiles each agent, and creates the necessary API routes automatically. The support-agent folder becomes available at /api/agents/support-agent, and so on.
Configuring the eve.config.ts File
Before deploying to production, you’ll want to configure eve.config.ts:
import { defineConfig } from "@vercel/eve";
export default defineConfig({
model: {
provider: "anthropic",
name: "claude-3-5-sonnet-20241022",
temperature: 0.3
},
sessions: {
storage: "vercel-kv",
ttl: 86400 // 24 hours in seconds
},
rateLimit: {
requestsPerMinute: 60,
tokensPerDay: 1000000
}
});The sessions.storage option is important. For production, you should point this at Vercel KV (their managed Redis service) rather than the default in-memory store. In-memory sessions don’t persist across cold starts or multiple instances — which will cause you real problems at scale.
Environment Variables
Set your LLM API keys and any other secrets through Vercel’s environment variable UI or CLI:
vercel env add ANTHROPIC_API_KEY
vercel env add VERCEL_KV_REST_API_URL
vercel env add VERCEL_KV_REST_API_TOKENEve automatically picks up environment variables prefixed with the provider name. You don’t need to pass them explicitly in config.
Working with Durable Sessions
Durable sessions are one of Eve’s most practical features. They let an agent maintain context across multiple messages, tool calls, and even page reloads — without you building a custom state layer.
How Sessions Work
When a user starts a conversation, Eve creates a session with a unique ID. That ID persists across the full interaction. Every message, tool result, and agent decision is appended to the session state, which lives in your configured storage backend.
Sessions are accessed through the session object passed to your handlers:
export default createAgent({
tools,
onMessage: async (message, session) => {
// Read from session state
const previousContext = session.get("userIntent");
// Write to session state
if (message.includes("billing")) {
session.set("hasBillingIssue", true);
}
return message;
}
});The session store is scoped to the session ID, so different users never see each other’s state. TTL is configurable per agent — a customer support session might expire after 24 hours, while a long-running background workflow might need 30 days.
Session Continuity Across Requests
To resume a session from the client side, pass the session ID in the request header:
const response = await fetch("/api/agents/support-agent", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Eve-Session-Id": existingSessionId
},
body: JSON.stringify({ message: "Following up on my earlier question" })
});If the session ID exists in storage, Eve loads the full context. If it doesn’t (expired or new user), Eve creates a fresh session. This makes handling reconnects and page refreshes straightforward.
Implementing Human-in-the-Loop
Human-in-the-loop (HITL) is where a lot of agent frameworks fall short. They either don’t support it at all, or they require you to build a separate approval workflow. Eve has it built in as a first-class concept.
Defining Escalation Points
You can mark specific tools or conditions as requiring human approval before execution:
defineTool({
name: "process_refund",
description: "Process a customer refund",
requiresApproval: true,
input: z.object({
orderId: z.string(),
amount: z.number(),
reason: z.string()
}),
execute: async (input) => {
// This only runs after a human approves
return await refundService.process(input);
}
})When the agent tries to call process_refund, Eve pauses execution and emits a pending_approval event. The session stays open in storage. Nothing proceeds until a human approves or rejects.
Building the Approval UI
On your frontend, listen for the pending approval state and render a confirmation interface:
const agentResponse = await callAgent(message);
if (agentResponse.status === "pending_approval") {
// Show approval UI to the user or an operator
const { approved } = await renderApprovalModal({
tool: agentResponse.pendingTool,
input: agentResponse.pendingInput,
reasoning: agentResponse.agentReasoning
});
// Resume the session with the decision
await resumeSession(agentResponse.sessionId, { approved });
}The agentResponse.agentReasoning field is particularly useful here — it shows why the agent wanted to take this action, which helps humans make a fast, informed decision.
Escalation vs. Interruption
Eve distinguishes between two HITL patterns. Interruption pauses execution at a specific tool call and waits for approval before continuing. Escalation hands the entire session off to a human agent and stops automated processing.
Interruption is for “check before you act” scenarios. Escalation is for “this is beyond what the agent should handle.” Both are configured in the agent’s agent.md under Session Behavior, and both can be triggered programmatically in your TypeScript handlers.
Building Multi-Agent Workflows
Production applications often need multiple agents working together — one to triage, one to handle specific domains, one to generate outputs. Eve supports this through agent-to-agent calls.
Calling One Agent from Another
Any agent can call another agent as if it were a tool:
import { callAgent } from "@vercel/eve";
defineTool({
name: "escalate_to_billing",
description: "Hand off to the billing specialist agent",
input: z.object({
summary: z.string(),
sessionId: z.string()
}),
execute: async ({ summary, sessionId }) => {
return await callAgent("billing-agent", {
message: summary,
inheritSession: sessionId
});
}
})The inheritSession option passes the full session context from the source agent to the target. This means the billing agent doesn’t start cold — it knows everything the support agent already established.
Orchestration Patterns
For more complex workflows, you can define an orchestrator agent that coordinates sub-agents:
agents/
├── orchestrator/
│ ├── agent.md # Decides which agents to invoke and when
│ └── index.ts
├── research-agent/
├── writer-agent/
└── reviewer-agent/The orchestrator’s agent.md describes the routing logic in natural language. The TypeScript handles the actual calls. This separation keeps your orchestration logic readable and auditable.
Where MindStudio Fits Into Your Agent Stack
Vercel Eve handles the infrastructure side of production agents well — deployment, sessions, HITL, agent coordination. But there’s a gap it doesn’t fill: the 1,000+ integrations and pre-built capabilities that most real-world workflows depend on.
Remy doesn't build the plumbing. It inherits it.
Other agents wire up auth, databases, models, and integrations from scratch every time you ask them to build something.
Remy ships with all of it from MindStudio — so every cycle goes into the app you actually want.
That’s where MindStudio comes in. MindStudio’s Agent Skills Plugin exposes over 120 typed capabilities — sendEmail(), searchGoogle(), generateImage(), runWorkflow() — as simple method calls that any agent can use, including agents built on Eve.
Instead of writing and maintaining individual integration code for every tool your agent needs, you can call MindStudio’s capabilities directly:
import { MindStudioAgent } from "@mindstudio-ai/agent";
const agent = new MindStudioAgent({ apiKey: process.env.MINDSTUDIO_KEY });
defineTool({
name: "send_support_summary",
description: "Email a support summary to the customer",
input: z.object({
to: z.string(),
summary: z.string()
}),
execute: async ({ to, summary }) => {
return await agent.sendEmail({ to, subject: "Your support case", body: summary });
}
})The plugin handles rate limiting, retries, and authentication — so your Eve agent stays focused on reasoning and routing, not plumbing.
If you’d rather build agents without writing code at all, MindStudio’s visual builder lets you create multi-step workflows with the same integrations in a no-code interface. The average build takes under an hour. You can try it free at mindstudio.ai.
The two tools complement each other: Eve for production infrastructure and TypeScript-defined agent logic, MindStudio for capabilities and integrations that would otherwise take days to build and maintain.
Common Mistakes and How to Avoid Them
A few patterns come up repeatedly when teams move from development to production with Eve.
Using in-memory session storage in production. The default session storage works fine locally but breaks under real load. Switch to Vercel KV before your first production deploy. It takes about five minutes and prevents a lot of pain.
Writing tool descriptions for developers, not for the model. The description field in your tool definition is read by the LLM, not by humans. Write descriptions that explain what the tool does and when to use it — not what the function signature looks like.
Treating durable sessions as a database. Sessions are for conversation state, not persistent business data. If you need to store records that outlive a session (tickets, user profiles, transaction history), write to your actual database from within the tool’s execute function.
Skipping HITL on high-stakes actions. It’s tempting to ship without approval flows because they add friction. But for actions with real consequences — sending emails, processing payments, modifying records — the friction is the point. Add requiresApproval: true early, even if you plan to relax it later.
Not logging agent reasoning. Eve exposes model reasoning at each step. Store it. When something goes wrong in production, having a record of why the agent made a specific decision is the difference between a 10-minute fix and a 3-hour debugging session.
Frequently Asked Questions
What is Vercel Eve and how is it different from the Vercel AI SDK?
The Vercel AI SDK is a general-purpose library for adding AI features to applications — streaming text, generating structured data, building chatbots. Vercel Eve is specifically for building and deploying production AI agents. It adds the infrastructure layer that agents need: durable sessions, HITL workflows, agent-to-agent coordination, and a file-based structure that scales across multiple agents in the same project. Eve uses the AI SDK internally but is a higher-level abstraction built for agent-specific use cases.
Remy is new. The platform isn't.
Remy is the latest expression of years of platform work. Not a hastily wrapped LLM.
Can Vercel Eve agents run autonomously in the background?
Yes. In addition to request/response agents, Eve supports background agent runs triggered by cron schedules, webhooks, or other events. You configure these in eve.config.ts under the triggers key. Background runs still use the same session and tool infrastructure — they just don’t have an interactive user on the other end.
How does human-in-the-loop work at scale with many simultaneous users?
Eve’s HITL implementation is session-scoped. When an agent pauses for approval, only that session waits — other sessions continue running independently. Pending approvals queue in your session storage (Vercel KV) until resolved. For high-volume applications, you can build an operator dashboard that pulls all pending approvals from KV and lets your team process them in bulk. Eve exposes an API endpoint for listing and resolving pending approvals.
What LLM providers does Vercel Eve support?
Eve supports OpenAI, Anthropic, Google Gemini, and Mistral out of the box. You set the provider in eve.config.ts and pass API keys via environment variables. Switching providers is a one-line config change — your tool definitions and agent logic stay the same. Custom or self-hosted models can be configured using the custom provider option with a base URL.
How do you handle errors and retries in production?
Eve includes built-in retry logic for tool execution failures with configurable backoff. You can customize retry behavior per tool using the retry option in defineTool. For LLM call failures, Eve uses Vercel’s edge runtime error handling and will surface errors to your onError handler in index.ts. For critical tools where failures need human review, combine error handling with Eve’s escalation system to route failures to a human operator automatically.
Is Eve suitable for multi-tenant applications?
Yes, with some configuration. Session isolation is enforced by session ID, but tenant isolation at the infrastructure level requires you to namespace your session keys by tenant ID. The recommended pattern is to include a tenant identifier in the session ID format (e.g., tenant-123:session-abc) and validate tenant ownership in your onMessage handler before processing requests.
Key Takeaways
- Vercel Eve defines agents as folders of markdown and TypeScript, making them version-controlled, self-documenting, and easy to manage at scale.
- Durable sessions require Vercel KV in production — don’t ship with in-memory storage.
- Human-in-the-loop is a first-class feature in Eve, not an afterthought. Use
requiresApprovalon any tool that has real-world consequences. - Multi-agent workflows are built by having agents call each other as tools, with session context passing between them.
- Tool descriptions are written for the model, not for developers — clarity in descriptions directly affects how accurately the agent selects tools.
- For capabilities beyond what you’re willing to build and maintain yourself, MindStudio’s Agent Skills Plugin gives your Eve agents 120+ typed integrations as simple method calls.
If you’re evaluating where to start, try MindStudio for rapid prototyping and workflow automation — you can go from idea to working agent in under an hour without writing a line of code.
