---
title: "Scaffold the Dispatcher"
description: "Scaffold the dispatcher with npx eve init, watch the generic skeleton fall flat on a bike question, then pin a model in agent.ts and write the front-desk persona in instructions.md until it answers in character in the dev TUI."
canonical_url: "https://vercel.com/academy/building-agents-with-eve/scaffold-the-dispatcher"
md_url: "https://vercel.com/academy/building-agents-with-eve/scaffold-the-dispatcher.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-03T03:33:28.745Z"
content_type: "lesson"
course: "building-agents-with-eve"
course_title: "Building Agents with eve"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Scaffold the Dispatcher

# Scaffold the Dispatcher

A new hire shows up for their first shift at the bike shop. Before they touch a wrench or sell a tune-up, they need to know one thing: who they are at that counter. Are they a robot reading prices off a screen, or a front-desk advisor who asks what the bike is *doing* before quoting anything?

Our agent needs the same grounding: who it is at the counter. With eve, that identity lives in `instructions.md`, an always-on file the model reads on every turn. A clear persona lets the agent act like a trustworthy advisor before it has tools.

Let's scaffold a fresh agent the way you'd start any real eve project, watch it answer like a generic chatbot, then give it a personality. For now, it only needs a model and an identity so we can talk to it in the terminal.

## Outcome

A scaffolded agent that answers in the Spoke & Mirror front-desk voice in the dev TUI, before it has any tools.

## Hands-on exercise

### Scaffold it

One command creates the whole project:

```bash
npx eve@0.84 init spoke-and-mirror --channel-web-nextjs
cd spoke-and-mirror
```

`init` creates the project, installs dependencies, initializes a Git repo, and opens the terminal UI. If eve finds a model connection on your machine (a key in your shell, a saved login, or the Vercel CLI's current team), it reuses it and drops you at the composer. If it doesn't, the first thing you see is `/login`:

```text
1. Vercel Account
2. Vercel AI Gateway API Key
3. ChatGPT Subscription
4. OpenAI API Key
5. Anthropic API Key
```

This is expected. The scaffold's default model (`openai/gpt-6-luna-fast`) routes through the Vercel AI Gateway, and the gateway needs a credential before it answers. Type to filter, `Enter` to select, `Esc` to back out.

- **Vercel Account:** The path we'll use in this course. eve opens a browser so you can sign in, shows a team picker if you belong to more than one team, and checks that team's AI Gateway access before returning you to the composer.
- **Vercel AI Gateway API Key:** Paste a gateway key instead, if you already have one.

eve saves keys and logins in your operating system's secret store, never in a project file, so there's no key sitting in the repo waiting to get committed. The connection takes effect on your next message, with no restart. The footer shows the active model and connection, something like `gpt-6-luna · high · ⚡︎`.

\*\*Note: \`/login\` and \`/model\` do different jobs\*\*

`/login` decides *how* eve reaches a model. `/model` decides *which* model, then walks you through speed and reasoning, and writes your choice into `agent/agent.ts`. If the dispatcher can't answer, start with `/login`.

With the model linked, take a look at what eve generated. The pieces that matter for this lesson:

```text
spoke-and-mirror/
├── agent/
│   ├── agent.ts          # chooses the model, configures the runtime
│   ├── instructions.md   # the always-on persona, read every turn
│   └── channels/
│       └── eve.ts        # the built-in HTTP channel, shipped with every app
├── app/                   # web dashboard; we'll open and customize it in 4.1
├── next.config.ts         # mounts the agent routes in Next.js
└── package.json
```

There's no `agent/tools/` yet, that's intentional. You add it in 1.2 the moment you write your first tool, and eve picks it up by the folder it lives in.

At this point, the scaffold gives you a model, a blank personality, and a web dashboard we will deliberately leave alone until Section 4. The catalog and tools come next.

\*\*Note: Why scaffold the web channel now?\*\*

`--channel-web-nextjs` generates the Next.js dashboard alongside the agent, so it's already wired when we reach it in 4.1. Until then, keep using the terminal UI with `npm run dev:eve`.

\*\*Note: Learn with your agent\*\*

Building agents is more fun when you have an agent to help. Now that the project exists, two optional installs set that up. Run them from inside `spoke-and-mirror`.

The **eve skill** teaches the coding agent beside you the framework, so it can build along:

```sh
npx skills add https://github.com/vercel/eve --skill eve
```

The **Academy skill** for this course lets it walk you through each lesson:

```sh
npx skills add vercel-labs/academy-skills \
  --skill building-agents-with-eve -y
```

Both are optional, but half of building with eve is learning to drive an agent, so you may as well start now.

### Chat with the default dispatcher

Once the TUI is ready, let's ask our generic agent a question a customer would actually ask:

\*\*Note: The dispatcher response will vary based on the model\*\*

If you need to run eve again, type `npm run dev:eve` to start over.

```text
you type > my rear bike brake feels spongy and kind of honks on the way down the hill

dispatcher response (with slight variations based on the model) > That sounds like it could be a few things, possibly worn brake pads,
contaminated rotors, or air in the line if it's hydraulic. You could try cleaning
the rotors, replacing the pads, or bleeding the brakes. If you're not comfortable
doing it yourself, take it to a bike shop!
```

Helpful, technically. But that's a search engine in a trench coat. It dumps every possibility, suggests you fix it yourself, and sends you to *some other* bike shop. It has no idea it *is* the bike shop. That's because right now its entire identity is the scaffold default:

```md title="agent/instructions.md"
# Identity

You are a general-purpose AI agent powered by eve, Vercel's agent framework.

# Customization

Your behavior and capabilities are defined by this project's code. You can be customized into whatever kind of agent the user wants by updating the project's instructions, tools, skills, connections, channels, subagents, and schedules.
```

Of course it acts generic. We told it to be a general-purpose agent, and it listened.

Two files own the agent's starting point. Let's set both. Stop the dev server first (Ctrl-C).

## Challenge

**1. Pin the model in `agent/agent.ts`.** This is where you choose the brain. The scaffold starts with `model: "openai/gpt-6-luna-fast"` and `reasoning: "high"`. The front desk of a real shop deserves the sharpest diagnosis we can give it, so we'll run the dispatcher on `anthropic/claude-opus-4.8` and replace both lines. A gateway model id like this routes through the Vercel AI Gateway, the same connection you logged in with a moment ago, so switching models needs no new key.

**2. Write the persona in `agent/instructions.md`.** Replace the bland default with a real front-desk advisor. Think about what makes the shop's front desk good, and write it as standing rules, not a script:

- Diagnose before quoting. Ask what the bike is doing, the noise, the symptom, when it started, before naming a service.
- Quote in real dollars from the catalog. Never invent a price.
- Be upfront about cost. A big job needs a sign-off, and that's normal, not something to apologize for.

### Done-When

- [ ] `npx eve@0.84 init spoke-and-mirror --channel-web-nextjs` created the project and `npm run dev:eve` opens the terminal UI.
- [ ] You connected a model through `/login` (or an `AI_GATEWAY_API_KEY` in your shell), and the footer shows the active model and connection.
- [ ] `agent/agent.ts` exports `defineAgent` with the model pinned to `anthropic/claude-opus-4.8`.
- [ ] `agent/instructions.md` describes the Spoke & Mirror front-desk advisor (diagnose-first, real-dollar quotes, upfront about cost).
- [ ] In the TUI, a vague symptom gets a diagnostic question back, in character, not a generic chatbot answer.

## Solution

`agent/agent.ts`:

```ts title="agent/agent.ts"
import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
});
```

`agent/instructions.md`:

```md title="agent/instructions.md"
You are the front-desk advisor at Spoke & Mirror Cyclery. You help
customers figure out what their bike needs and get it booked in.

- Diagnose before you quote. Ask what the bike is actually doing (the noise, the
  symptom, when it started) before you name a service.
- Use the tools rather than guessing. Look up real services and prices with
  `lookup_service`, find real openings with `check_availability`, and book with
  `book_repair`.
- Quote in real dollars from the catalog. Never invent a price.
- Remember the customer's bikes with `remember_bike`, and check `recall_bikes`
  before asking them to repeat details the shop already has on file.
- Be upfront about cost. Big jobs need a sign-off before they're booked. That's
  expected, not a problem, so don't apologize for it.
```

The persona deliberately names tools that don't exist yet, including `lookup_service` and `book_repair`. Each becomes a file in `agent/tools/` as you build out the front-desk role.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)