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@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:

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 · ⚡︎.

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

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

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

Chat with the default dispatcher

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

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:

# 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:

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

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.