First Agent

The first tutorial step is about creating a real, runnable eve agent before adding warehouse access, analytical tools, memory, spend controls, or deployment. The tutorial app is an analytics assistant: users ask questions in natural language, and later steps teach it to query data, run analysis, remember team definitions, and ask before exceeding a budget. In this first step, the goal is narrower and practical. You scaffold the project, choose a capable model, replace the starter instructions with an analyst identity, and confirm the local runtime can answer a general analysis question. Sources: docs/tutorial/first-agent.mdx

Purpose and Scope

Use this page when you want the shortest source-backed path from an empty directory to a working eve agent. The tutorial assumes the reader is building the documented analytics assistant rather than a generic demo. That matters because the first prompt, model choice, and standing instructions are all framed around data analysis. The scaffold already includes a small sample dataset, but this step deliberately does not teach warehouse querying yet. Instead, it proves that the application boots, reaches a model, opens the development TUI, and responds with the persona you authored. Sources: docs/tutorial/first-agent.mdx

This page covers only the first tutorial milestone. It does not configure Vercel deployment, create a Vercel project, add external data, define tools, add skills, or enforce query budgets. Those are later tutorial and guide concerns. The important mental model is that eve projects are authored through conventional files under the agent directory. In step one, two files are central: the runtime configuration file that selects the model, and the instructions file that supplies the always-on behavior rules. Sources: docs/tutorial/first-agent.mdx

Relevant Source Files

• docs/tutorial/first-agent.mdx — Canonical tutorial source for the first-agent flow, including prerequisites, scaffold commands, model configuration, analyst instructions, local run command, and the first prompt to try.

Prerequisites

Before scaffolding, make sure the local environment can run the generated project and call a model. The tutorial requires Node 24 or newer and npm. It also requires a model credential because the local runtime will contact the selected model when you send the first question. The scaffold default routes through the Vercel AI Gateway, so the expected credential is an AI Gateway key, or an OIDC token obtained by linking with Vercel. Without a credential, the project may scaffold successfully, but the first model-backed run will fail when the runtime tries to answer. Sources: docs/tutorial/first-agent.mdx

The tutorial also calls out an alternate direct-provider path. If you configure a direct Anthropic model in code, you need the provider package and the provider API key rather than only a gateway credential. This distinction is useful for debugging because dependency errors and authentication errors come from different layers. A missing package prevents the app from importing the provider model. A missing key lets the project start farther but fails when the provider request is made. If you have never run eve before, complete the Getting Started flow first so local credentials and project expectations are familiar. Sources: docs/tutorial/first-agent.mdx

Scaffold the Agent

Run the initializer from the directory where you want the new project folder to be created. The tutorial names the project analytics assistant, and the command creates that directory for you. After initialization, change into the new directory before editing or running commands. The initializer writes the starter agent, installs dependencies, initializes Git, and starts the development server. It also includes the built-in HTTP API channel in the generated agent channel file, which gives the starter app a local HTTP-facing surface for the development workflow. Sources: docs/tutorial/first-agent.mdx

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

One important operational detail is that initialization starts the development server, but the tutorial asks you to stop it before making the first edits. That keeps the flow explicit: scaffold first, then change the agent configuration and instructions, then run the app again through the generated development script. The scaffold does not deploy anything and does not create a Vercel project. Treat it as a local project bootstrapper, not as a production release command. The directory it creates is the workspace for every subsequent tutorial step. Sources: docs/tutorial/first-agent.mdx

Configure the Model

The model setting lives in the agent runtime configuration file. In the tutorial, that file exports a definition created with the eve helper and selects an Anthropic Opus model through the gateway model identifier. The key idea is that the model belongs in configuration, not in the instructions text. This keeps the agent persona and the runtime provider choice separate, which makes later changes easier. You can update the model for capability, cost, routing, or provider reasons without rewriting the analyst rules that govern the assistant’s behavior. Sources: docs/tutorial/first-agent.mdx

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

For the analytics assistant, the tutorial recommends a capable model because later steps will involve analysis work. At this stage, the model is used only to answer a general question, but choosing the intended class of model early avoids confusing results when the persona asks it to compute, state assumptions, and avoid guessing. If you use the gateway string shown in the tutorial, make sure the gateway credential is available. If you switch to a direct provider model, make sure the provider package and key are installed and configured consistently with that provider’s naming format. Sources: docs/tutorial/first-agent.mdx

Author the Analyst Persona

The always-on system prompt lives in the instructions file. Replace the starter text with an identity that tells the assistant it is a senior data analyst answering questions about team data. The instructions should also define the behavioral rules that apply to every turn. In the tutorial, those rules emphasize exact numbers over vague summaries, explicit assumptions for reported metrics, tool use instead of guessing, and honest refusal when data is insufficient. These rules are deliberately durable: they shape the assistant before any specialized tools or skills are added. Sources: docs/tutorial/first-agent.mdx

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.

This is also the first place the tutorial separates core eve primitives. Instructions are identity and standing policy. Skills are for on-demand procedures that the agent can load later, and tools are for actions the model can call. That distinction prevents the system prompt from becoming a dumping ground for every process detail. In this first step, only instructions are needed because the agent is not yet querying a warehouse or running analysis. Later, when procedures and executable capabilities appear, keep them in the more specific filesystem locations designed for those responsibilities. Sources: docs/tutorial/first-agent.mdx

Run the Local Development Flow

After editing the model and instructions, start the generated project with the scaffolded development script. The tutorial explains that the script runs the local eve development binary from the project dependencies. The local runtime boots and the development terminal UI opens. This UI is where you send the first message and observe whether the agent can complete a basic model turn. The initial prompt should be something answerable from general knowledge because the assistant does not have data access yet. Sources: docs/tutorial/first-agent.mdx

npm run dev

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

A successful reply should reflect the analyst persona even though it cannot inspect your warehouse. Look for practical signs that the instruction file is active: the answer should be analytical, should avoid pretending it has unseen data, and should discuss assumptions or measurement choices. If the run fails before a response, check credentials first because the tutorial specifically notes that missing model access causes failure when the runtime reaches the model. If the response is generic or ignores the analyst stance, verify that you edited the correct instructions file in the generated agent project. Sources: docs/tutorial/first-agent.mdx

System-to-Code Mapping

Next Steps

When this step is complete, you have a working local agent with a model, an analyst identity, and a development loop. The next tutorial work should add the capabilities that make the assistant useful for actual analytics: connecting data, querying, running analysis, and later guarding spend. Keep the first-step separation intact as the project grows. Configuration belongs in the runtime config, durable identity belongs in instructions, executable actions belong in tools, and reusable procedures belong in skills. That organization is what keeps the tutorial app inspectable as it moves from a talking assistant to a capable analytics workflow. Sources: docs/tutorial/first-agent.mdx