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:

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:

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

This message is expected. eve's default model (anthropic/claude-sonnet-4.6) routes through the Vercel AI Gateway, which needs a credential before it answers. Type /model to open the Configure the agent model menu (↑/↓ to move, Enter to select, Esc to cancel):

Change model: Opens the searchable AI Gateway catalog with the current model selected. Pick one and eve rewrites the model field in agent/agent.ts after the new id resolves. You can skip the menu with /model anthropic/claude-opus-4.8.
Configure provider: Clears the setup issue. It appears in bold yellow as Required to enable the agent until eve finds a credential. First choose a provider. Keep AI Gateway for this course; choosing your own provider prints wiring instructions and leaves setup unchanged. Then choose how to connect:
- Paste an AI_GATEWAY_API_KEY: Saves a static gateway key to .env.local.
- OR: Connect a Vercel project: Walks through the team and project pickers, then pulls the project's environment into .env.local. Instead of a static key, you get a short-lived VERCEL_OIDC_TOKEN that authenticates gateway model ids through Vercel OIDC. If it expires, run the link again.
Done: Closes the menu.

eve reloads .env.local on its own. The footer changes from the yellow warning to a connection such as anthropic/claude-sonnet-4.6 · AI Gateway (spoke-and-mirror), and the setup notice disappears.

A `Session ended` line right after linking is normal

Reloading .env.local restarts the dev server and ends the open session. Immediately after linking, you may see Session ended — started a new session. Earlier context was cleared. If a turn was in progress, you might also see a stray Missing or empty 'message' field error. The connection still succeeded. Send the question again in the new session.

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

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.

At this point, the scaffold gives you a model and a blank personality. The catalog, tools, and dashboard come later.

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:

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

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

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:

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.

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:

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:

agent/agent.ts

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

agent/instructions.md:

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.