Building Agents with eve

What do the best bike shop employees have in common? They're good at diagnosing bike problems, quoting from a real catalog, finding open repair appointment slots, and remembering a customer's bikes. They're good at holding a conversation, and they know when to stop and check in with you before they start doing something really expensive.

An agent automates the repetitive intake, scheduling, and FAQs, so the shop can grow its volume without growing its payroll. This is a very bike-specific example, but the principles apply to any domain.

We're going to build a production bike shop dispatcher agent with eve, the filesystem-first framework for durable agents. Think of eve as being Next.js but for agents. Its whole conceit is that an agent is a directory. Instructions in one file, tools in a folder, channels in another. That structure is what lets one agent run in the terminal, over HTTP, and inside Slack without you rewriting code over and over again.

Why do we need a framework?

Before Next.js, every web app made the same plumbing decisions from scratch: where routes live, how rendering works, how it deploys. Next.js made those calls so you could spend your time on the app instead of the scaffolding around it.

Agents today are stuck where web apps were before that. Calling a model is the easy afternoon-demo part. Everything around it, where instructions live, how a tool gets registered, what happens when a run dies halfway through, is yours to invent. Every time.

eve makes those decisions for you. Without a framework, a production agent means hand-wiring a project layout, a home for prompts, tool registration, durable state, retries, approval gates, and a separate adapter for every surface, then owning all of it. With eve, instructions are Markdown, tools are TypeScript files in a folder, and durability, approvals, and channels are already there.

That's what "an agent is a directory" really buys you: the filename is the API. A file at agent/tools/lookup_service.ts is a tool called lookup_service. Drop a file in channels/ and the agent shows up there. Nothing to register, because the directory is the registry.

Let's build the front desk and put it to work. The project is Spoke & Mirror Cyclery's dispatcher, and by the end it's deployed and taking real bookings. The finished build lives at vercel-labs/bike-shop-agent, your reference checkpoint any time a step doesn't line up.

Commit after each lesson so you have a checkpoint to roll back to.

What you'll actually build

We build the dispatcher bottom-up, then cross the gap into production:

A working agent with real tools:

• Scaffold an eve agent and give it a front-desk persona
• Add typed tools that quote from a real service catalog and find open slots
• Drive it over the same stable HTTP session API every eve app exposes

An agent with memory and judgment:

• Remember a customer's bikes across turns with durable session state
• Load a different playbook per membership tier with a dynamic skill
• Park expensive bookings for human approval, then resume the exact step

The same agent, everywhere your users are:

• Put it behind a web dashboard with useEveAgent
• Add Slack as a channel without touching a single tool
• Stamp authenticated identity at the door that drives the per-tier desk

Shipped to production:

• Replace placeholder auth with a real, fail-closed policy
• Build and deploy to Vercel, then smoke-test the live agent

Prerequisites

• Node.js 24+ and npm installed
• A Vercel account (free tier works)
• A model credential, easiest through the Vercel AI Gateway, or a linked Vercel project
• Enough terminal comfort to run curl

Course sections

Section 1: Your First Agent

Scaffold the dispatcher, give it the Spoke & Mirror persona, add its first typed tool, and drive it over the HTTP session API.

Section 2: Give It a Memory and a Brain

Add a second tool, durable per-session state that remembers the customer's bikes, and a dynamic skill that changes the desk per membership tier.

Section 3: Put a Human in the Loop

Watch the agent book an expensive job unsupervised, then gate it on cost-based human approval that pauses and resumes the durable session.

Section 4: Meet Your Users Where They Are

Put the same agent behind a web dashboard and Slack without touching tool code, then stamp authenticated identity that feeds the per-tier playbook.

Section 5: Ship It

Swap placeholder auth for a real fail-closed policy, deploy the dispatcher to Vercel, and smoke-test it live.