How to Build Production AI Agents with Vercel Eve: A Step-by-Step Guide
Build and deploy a production-grade AI agent using Vercel Eve's file-system-first framework. Covers skills, sub-agents, channels, evals, and Slack integration.
Why Most AI Agents Fall Apart in Production
Prototyping an AI agent is easy. Getting one to actually work reliably — handling errors gracefully, scaling across users, integrating with your team’s tools, and behaving predictably over time — is a completely different problem.
That’s where Vercel Eve comes in. Eve is a file-system-first framework for building production AI agents that brings structure to a space that’s been chaotic. If you’ve used Next.js, the mental model will feel familiar: define your agent’s components as files, and the framework handles the wiring.
This guide walks through building a production-grade AI agent with Eve from scratch. You’ll learn how to define skills, compose sub-agents, connect communication channels like Slack, and write evals that catch problems before they reach users.
What Makes Eve Different: The File-System-First Model
Most agent frameworks ask you to write a lot of glue code. You define capabilities, wire them into an agent loop, configure integrations manually, and hope it all holds together when traffic spikes or an API returns an unexpected response.
Eve takes a different approach. Your agent’s structure maps directly to your project’s file structure. Skills live in a /skills directory. Sub-agents live in /agents. Channel configurations in /channels. Evals in /evals. The framework reads those files and assembles everything automatically.
This has a few practical benefits:
- Discoverability — anyone on your team can understand the agent’s capabilities by reading the directory
- Modularity — skills and agents can be reused across projects without copy-pasting logic
- Testability — evals run against the same skill definitions your production agent uses, not a separate mock
- ✕a coding agent
- ✕no-code
- ✕vibe coding
- ✕a faster Cursor
The one that tells the coding agents what to build.
The result is an agent architecture that doesn’t require a PhD to maintain six months after you built it.
Prerequisites and Project Setup
Before building anything, make sure you have the following ready:
- Node.js 18+ installed
- A Vercel account (free tier works for development)
- API keys for your chosen LLM (OpenAI, Anthropic, or others)
- A Slack workspace with permission to add apps (for the channel integration later)
Initialize the Project
Start by creating a new Eve project using the CLI:
npm create eve-app@latest my-agent
cd my-agent
npm installThe scaffolded project gives you a clean directory structure:
my-agent/
├── agents/
│ └── main.ts
├── skills/
│ └── .gitkeep
├── channels/
│ └── .gitkeep
├── evals/
│ └── .gitkeep
├── eve.config.ts
└── package.jsonOpen eve.config.ts to set your model and global defaults:
import { defineConfig } from '@vercel/eve';
export default defineConfig({
model: 'gpt-4o',
temperature: 0.2,
maxTokens: 2048,
retries: 3,
});Lower temperature is appropriate for production agents doing structured work. You can override these defaults at the individual skill or agent level when needed.
Building Agent Skills
Skills are the atomic capabilities of your agent. Each skill is a single file that exports a typed function with a name, description, input schema, and handler.
Anatomy of a Skill
Here’s a basic web search skill:
// skills/search-web.ts
import { defineSkill } from '@vercel/eve';
import { z } from 'zod';
export default defineSkill({
name: 'searchWeb',
description: 'Search the web for current information on a given topic',
input: z.object({
query: z.string().describe('The search query'),
maxResults: z.number().optional().default(5),
}),
async handler({ query, maxResults }) {
// Implementation using your preferred search API
const results = await fetchSearchResults(query, maxResults);
return { results };
},
});The description field matters more than you might think. Eve uses it to help the agent decide when to invoke each skill. Be specific: “Search the web for current information” is better than “search the web.”
Writing Skills for Production
A few things make the difference between a skill that works in demos and one that holds up in production:
Type your inputs strictly. Use Zod schemas with .describe() annotations on every field. This creates a clear contract between the agent’s reasoning and the skill’s behavior.
Handle errors explicitly. Don’t let a failed API call crash your agent loop. Return structured error states instead:
async handler({ query }) {
try {
const results = await fetchSearchResults(query);
return { success: true, results };
} catch (err) {
return { success: false, error: err.message };
}
}Log for observability. Eve integrates with Vercel’s logging infrastructure, but you need to instrument your skills. Add structured logs at the start and end of each handler so you can trace issues in production.
Common Skills to Build First
For most business-facing agents, start with these foundational skills before adding complexity:
- Data retrieval — fetch records from your CRM, database, or internal API
- Web search — pull in current information the model wasn’t trained on
- Document summarization — condense long content into actionable summaries
- Notification sending — push updates to Slack, email, or other channels
- Data writing — update records, create tickets, or log information back to source systems
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.
Composing Multi-Agent Workflows with Sub-Agents
Skills give your agent capabilities. Sub-agents give your system scale.
A sub-agent is a specialized agent with its own skill set and system prompt that your main agent can delegate tasks to. This pattern is useful when:
- A task requires deep focus that would distract a general-purpose agent
- You want to parallelize work across multiple agents
- You need to enforce different model settings (like a stricter temperature) for specific tasks
Defining a Sub-Agent
// agents/researcher.ts
import { defineAgent } from '@vercel/eve';
export default defineAgent({
name: 'researcher',
description: 'Researches topics in depth using web search and document analysis',
systemPrompt: `You are a thorough research assistant. When given a topic,
search for multiple sources, cross-reference claims, and return a structured
summary with citations. Do not speculate. If you cannot find reliable
information, say so.`,
skills: ['search-web', 'fetch-url', 'summarize-document'],
model: 'gpt-4o',
});Calling a Sub-Agent from Your Main Agent
Your main agent file imports and delegates to the sub-agent:
// agents/main.ts
import { defineAgent } from '@vercel/eve';
export default defineAgent({
name: 'main',
systemPrompt: `You are a business intelligence assistant. For research tasks,
delegate to the researcher agent. For data retrieval, use the CRM skill directly.
Always cite your sources in responses.`,
skills: ['search-crm', 'send-notification'],
subAgents: ['researcher', 'analyst'],
});Eve resolves the sub-agent references by looking in your /agents directory. No manual registration required.
When to Use Sub-Agents vs. Skills
A common question when designing agent architectures is whether a piece of functionality should be a skill or a sub-agent. Here’s a practical rule of thumb:
- If it’s a single, bounded action (call an API, write a record, generate text), it’s a skill.
- If it involves multi-step reasoning or using multiple skills in sequence, it’s a sub-agent.
A skill that calls a search API is a skill. An agent that searches the web, reads three URLs, and synthesizes the results into a report is a sub-agent.
Connecting Communication Channels
Channels define how your agent communicates with the outside world. Eve ships with built-in channel support for Slack, webhooks, and HTTP APIs.
Setting Up the Slack Channel
First, create a Slack app and generate the necessary credentials:
- Go to api.slack.com/apps and create a new app
- Enable Socket Mode for local development
- Add the following OAuth scopes:
chat:write,channels:read,im:history,app_mentions:read - Install the app to your workspace and copy the Bot Token and App-Level Token
Now define the channel configuration:
// channels/slack.ts
import { defineChannel } from '@vercel/eve';
export default defineChannel({
type: 'slack',
agent: 'main',
config: {
botToken: process.env.SLACK_BOT_TOKEN,
appToken: process.env.SLACK_APP_TOKEN,
},
triggers: [
{ event: 'app_mention', handler: 'onMention' },
{ event: 'direct_message', handler: 'onDirectMessage' },
],
});Store your tokens in environment variables — never hardcode credentials. Vercel’s environment variable system handles this cleanly for both development and production.
Handling Slack Events
Eve’s channel abstraction normalizes incoming events so your agent doesn’t have to parse raw Slack payloads:
// channels/slack.ts (continued)
handlers: {
async onMention({ message, say, thread }) {
const response = await agent.run(message.text, {
context: { channel: message.channel, user: message.user },
});
await say({ text: response, thread_ts: thread });
},
async onDirectMessage({ message, say }) {
const response = await agent.run(message.text);
await say(response);
},
},Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
The thread parameter automatically threads replies back into the original conversation — which matters for team workflows where context needs to stay organized.
Adding Webhook and HTTP Channels
For integrating with external systems that need to trigger your agent via API:
// channels/webhook.ts
import { defineChannel } from '@vercel/eve';
export default defineChannel({
type: 'http',
agent: 'main',
path: '/api/agent',
auth: {
type: 'bearer',
token: process.env.WEBHOOK_SECRET,
},
});This creates an authenticated HTTP endpoint on your Vercel deployment that any external system can POST to.
Writing Evals for Production Reliability
Evals are the part most teams skip — and it shows. Without them, you’re shipping blind and discovering regressions in production when users complain.
Eve’s eval system lets you define test cases with inputs and expected behaviors, then run them against your live skill and agent definitions.
Writing Your First Eval
// evals/search-skill.eval.ts
import { defineEval } from '@vercel/eve';
export default defineEval({
skill: 'search-web',
cases: [
{
name: 'returns results for valid query',
input: { query: 'Q3 2024 AI market trends', maxResults: 3 },
expect: (output) => {
expect(output.success).toBe(true);
expect(output.results.length).toBeGreaterThan(0);
},
},
{
name: 'handles empty query gracefully',
input: { query: '' },
expect: (output) => {
expect(output.success).toBe(false);
expect(output.error).toBeDefined();
},
},
],
});Writing Agent-Level Evals
Skill evals test individual capabilities. Agent evals test full conversations:
// evals/main-agent.eval.ts
import { defineAgentEval } from '@vercel/eve';
export default defineAgentEval({
agent: 'main',
cases: [
{
name: 'correctly delegates research tasks',
messages: [
{ role: 'user', content: 'Research the current state of vector databases' },
],
expect: (response) => {
// Check that the agent invoked the researcher sub-agent
expect(response.trace.subAgentsCalled).toContain('researcher');
expect(response.content).toMatch(/sources|references|according to/i);
},
},
],
});The trace object gives you visibility into what the agent actually did — which skills it called, which sub-agents it delegated to, and how many turns it took. This is invaluable for debugging unexpected behavior.
Running Evals in CI
Add this to your CI pipeline to catch regressions before deployment:
npx eve eval --all --reporter=githubEve outputs results in a format GitHub Actions can annotate directly on pull requests. This makes it easy for reviewers to see whether a code change broke any agent behavior.
Deploying to Vercel
Once your skills, sub-agents, channels, and evals are in shape, deploying is straightforward.
Pre-Deployment Checklist
Before pushing to production, verify:
- All environment variables are set in your Vercel project settings
- Evals pass with
npx eve eval --all - Your Slack channel’s redirect URL and event subscriptions point to your production domain
- Rate limits are configured appropriately for your expected traffic
Deploy
vercel deploy --prodEve automatically provisions the necessary serverless functions and edge routes for your channels. Your Slack integration goes live as soon as the deployment completes and you update your Slack app’s event subscription URL.
Monitoring in Production
Eve integrates with Vercel Analytics and logs. After deployment, watch for:
- Error rates per skill — a spike in failures for a specific skill often points to an upstream API issue
- Latency per agent turn — if your agent is consistently slow, look at which skills are the bottleneck
- Token usage — unexpected spikes usually mean a prompt or skill is generating more output than expected
How MindStudio Fits Into Agent Development
Building agents with Eve gives you a solid, developer-first framework. But Eve is code-first — you need to write and maintain TypeScript files, manage deployments, and handle the full infrastructure layer yourself.
For teams that want to build and iterate on AI agents without that overhead, MindStudio covers a lot of the same ground through a visual no-code builder. You can wire together skills, integrate with Slack, build multi-step workflows, and deploy agents — all without writing a single line of code.
MindStudio’s Agent Skills Plugin is particularly relevant here. It’s an npm SDK that lets code-based agents like those built with Eve call MindStudio’s 120+ typed capabilities as simple method calls — things like agent.sendEmail(), agent.searchGoogle(), or agent.runWorkflow(). This means you can use Eve for the agent architecture while offloading specific capabilities (integrations, media generation, data access) to MindStudio’s infrastructure, which handles rate limiting, retries, and auth automatically.
If you’re prototyping before committing to a full Eve build, MindStudio can help validate the workflow logic quickly. Agents that take weeks to code from scratch often take a day or less to test in MindStudio’s builder.
You can try MindStudio free at mindstudio.ai.
Common Mistakes and How to Avoid Them
Even well-structured Eve projects run into predictable problems. Here are the ones that show up most often:
Over-relying on one large agent. If your main agent has 15+ skills, it will make poor decisions about which ones to use. Break specialized functionality into sub-agents and keep skill counts manageable per agent.
Vague skill descriptions. The model uses your skill descriptions to decide when to invoke them. “Fetches data” is too vague. “Retrieves customer account details from Salesforce given an account ID or email address” is specific enough to work reliably.
No error states in skill handlers. Skills that throw exceptions instead of returning error states crash the agent loop. Always return a structured response, even on failure.
Skipping evals until something breaks. Write evals alongside your skills, not after production issues surface. Even 3–4 test cases per skill catches most regressions.
Hardcoding context in system prompts. Don’t put today’s date or user-specific information in the system prompt. Pass dynamic context through the run call so you can use the same agent definition for all users.
Frequently Asked Questions
What is Vercel Eve and who is it for?
Vercel Eve is a file-system-first framework for building production-ready AI agents. It’s designed for developers who want structure and reliability beyond basic prototype setups. If you’re building agents that need to integrate with business tools, handle real user traffic, and be maintained by a team, Eve provides the architecture to do that without starting from scratch every time.
How does the file-system-first approach differ from other agent frameworks?
Remy doesn't write the code. It manages the agents who do.
Remy runs the project. The specialists do the work. You work with the PM, not the implementers.
Most agent frameworks are code-first — you write functions, register them with an agent, and wire everything together manually. Eve maps your agent’s components (skills, sub-agents, channels, evals) to files in your project directory. The framework discovers and assembles them automatically, which reduces boilerplate and makes the structure readable to anyone on the team.
What are evals and why do they matter for AI agents?
Evals are automated tests for your agent’s behavior. Unlike unit tests that check deterministic code, evals verify that your agent produces appropriate outputs for given inputs — including edge cases and error conditions. They’re essential for production agents because LLM behavior can shift subtly when you update a prompt, change a model, or add a new skill. Without evals, you won’t catch those regressions until users do.
Can I use Eve with models other than OpenAI?
Yes. Eve’s eve.config.ts supports any model available through the AI SDK, including Anthropic’s Claude models, Google Gemini, and open-source models via compatible endpoints. You can also set different models per agent or skill, which is useful for tasks where cost and capability tradeoffs matter.
How do sub-agents differ from skills in Eve?
Skills are atomic, single-step operations — call an API, query a database, generate text. Sub-agents are specialized agents with their own reasoning loops that can use multiple skills in sequence. Use skills for bounded actions, sub-agents for multi-step tasks that require their own judgment. A good rule: if the task needs more than one skill to complete, it’s probably a sub-agent.
What’s the best way to handle authentication for Slack and other channels?
Store all credentials as environment variables — never in code. For Slack specifically, you need a Bot Token (for sending messages) and an App-Level Token (for Socket Mode during development). In production, Vercel’s environment variable system keeps these secure and separate per deployment environment (development, staging, production). Eve’s channel configuration reads from process.env automatically when you reference variables by name.
Key Takeaways
Building production AI agents with Vercel Eve requires understanding a few core concepts:
- File-system-first structure maps directly to how your agent operates — skills, sub-agents, channels, and evals each live in their own directory and are auto-discovered by the framework
- Skills are typed, single-purpose capabilities; write them with strict schemas, explicit error handling, and structured logging
- Sub-agents handle multi-step reasoning and can be composed together for complex workflows — keep skill counts per agent manageable
- Channels like Slack integrate through declarative configuration files; Eve normalizes events so your agent code stays clean
- Evals are not optional for production — write them alongside skills, run them in CI, and treat regressions as bugs
If you want to explore agent building without the full development setup, MindStudio offers a no-code builder with 1,000+ integrations and 200+ AI models. You can prototype and validate agent workflows quickly, then connect your own code-based agents via the Agent Skills Plugin when you’re ready to build out a custom stack.
