---
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-06-30T02:30:35.153Z"
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?

That's the same first decision for our agent. Not what it can do, who it is. With eve, an agent's identity lives in one always-on file, `instructions.md`, that the model reads on every single turn. Get that file right and the agent behaves like a trustworthy advisor before it has a single tool to its name.

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. No tools yet. Just a model and an identity, talking 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@latest init spoke-and-mirror
cd spoke-and-mirror
```

`init` creates a project, installs dependencies, and initializes a Git repo. The first time we run it, we'll get this message:

```text
⚠ 1 setup issue: model provider not linked · /model
```

That's expected, not a bug. eve's default model (`anthropic/claude-sonnet-4.6`) routes through the Vercel AI Gateway, and the gateway needs a credential before it answers. Type `/model` and eve opens a small **Configure the agent model** menu (`↑/↓` to move, `Enter` to select, `Esc` to cancel) with three rows:

- **Change model** — opens the searchable AI Gateway catalog, pre-selected on the model you're currently running. Pick one and eve rewrites the `model` field in `agent/agent.ts` for you, confirming only once the new id resolves. You can skip the menu entirely with `/model anthropic/claude-opus-4.8`.
- **Configure provider** — the row that clears this setup issue. It shows in bold yellow as *Required to enable the agent* until a credential is found. Selecting it first asks **which provider** to use (keep **AI Gateway** — choosing your own provider just prints wiring instructions and stops, leaving setup untouched), then **how to connect** to the gateway:
  - **Paste an `AI_GATEWAY_API_KEY`** — a static gateway key, saved straight to `.env.local`.
  - **OR: Connect a Vercel project** — walks the same team and project pickers as first-time setup, then pulls that project's environment into `.env.local`. This doesn't drop a static key: you get a short-lived `VERCEL_OIDC_TOKEN`, and gateway model ids authenticate through Vercel OIDC — nothing to copy or rotate by hand. (If the token later expires, re-run the link to refresh it.)
- **Done** — closes the menu.

eve reloads `.env.local` on its own (no restart), and the footer flips from the yellow warning to your connection — something like `anthropic/claude-sonnet-4.6 · AI Gateway (spoke-and-mirror)`. The setup notice is gone; there's a brain that will actually answer now.

\*\*Note: A \`Session ended\` line right after linking is normal\*\*

Reloading `.env.local` restarts the dev server, which ends whatever session was open. So just after linking you may see `Session ended — started a new session. Earlier context was cleared` (and, if a turn was mid-flight, a stray `Missing or empty 'message' field` error). Nothing broke — the link took. Type your question fresh and the agent responds.

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
└── 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.

No catalog, no tools, no dashboard. Just a brain and a blank personality.

\*\*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, you can always type `npx eve dev` 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"
You are a helpful assistant.
```

Of course it acts generic. We never told it who it is.

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 picked a sensible **default** (`anthropic/claude-sonnet-4.6`); 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`. A gateway model id like this routes through the Vercel AI Gateway, the same credential you linked 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@latest init spoke-and-mirror` created the project and the dev server boots with `0 errors, 0 warnings`.
- [ ] The model provider is linked via `/model` (or `eve link` / `AI_GATEWAY_API_KEY`) and the `model provider not linked` notice has cleared.
- [ ] `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 names tools that don't exist yet (`lookup_service`, `book_repair`, and friends). That's deliberate: you're describing the front-desk advisor you're about to build the hands for. Over the next lessons, each of those tools becomes a real file in `agent/tools/`, and the agent grows into the role you just wrote.


---

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