Your First Agent

The Build an Agent tutorial constructs one app end to end, a data analytics assistant. You ask in natural language, and over the next nine steps it learns to query a warehouse, run analysis in a sandbox, remember your team's metric definitions, and refuse to exceed your query budget without asking.

Step 1 gets it talking. The scaffold bundles a small sample dataset, so your first question works with zero setup.

Prerequisites

• Node 24 or newer and npm.
• A model credential. The scaffold's default model goes through the Vercel AI Gateway, so you need AI_GATEWAY_API_KEY (or VERCEL_OIDC_TOKEN pulled via vercel link). A direct provider model like anthropic("claude-opus-4-8") instead needs that provider's AI SDK package and key, here @ai-sdk/anthropic and ANTHROPIC_API_KEY.

If you have not run eve before, complete Getting Started first. Without a credential, "Run the agent" below fails when the runtime tries to reach the model; the dev TUI's /model flow walks you through pasting a key or linking a project.

Scaffold the agent

npx eve@latest init analytics-assistant
cd analytics-assistant

The command writes the starter agent with eve's default model and built-in HTTP API channel (agent/channels/eve.ts), installs dependencies, initializes Git, and starts the development server. Stop the server before continuing with the edits below. It does not create a Vercel project or deploy. init creates the analytics-assistant/ directory, so cd into it before running further commands.

Set the model

agent/agent.ts holds the model and config. Use a capable model for analysis work:

import { defineAgent } from "eve";

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

Give it an analyst persona

agent/instructions.md is the always-on system prompt. Replace the starter text with a standing identity for a data analyst:

You are a senior data analyst. You answer questions about the team's data.

- Prefer exact numbers to hand-waving. If you can compute it, compute it.
- State the assumptions behind any number you report (date range, filters, grain).
- Use the tools available to you rather than guessing. If you cannot answer from
  the data, say so plainly.

Instructions are identity and standing rules. On-demand procedures belong in skills (Step 7), and actions belong in tools (Step 3). See Instructions.

Run the agent

npm run dev

The init scaffold writes a dev script that runs the eve dev binary from the project's node_modules. The local runtime boots and the dev TUI opens. Ask it something it can answer from general knowledge first:

What's a good way to measure week-over-week retention?

You get a reply that follows the analyst persona. It can't see your data yet (that comes in Step 3). First, a look at what happened under the hood.

→ Next: How it runs

Learn more: Getting Started · Instructions